1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2018-2020, Linaro Limited 4 */ 5 6 #ifndef PKCS11_TA_H 7 #define PKCS11_TA_H 8 9 #include <stdbool.h> 10 #include <stdint.h> 11 12 #define PKCS11_TA_UUID { 0xfd02c9da, 0x306c, 0x48c7, \ 13 { 0xa4, 0x9c, 0xbb, 0xd8, 0x27, 0xae, 0x86, 0xee } } 14 15 /* PKCS11 trusted application version information */ 16 #define PKCS11_TA_VERSION_MAJOR 0 17 #define PKCS11_TA_VERSION_MINOR 1 18 #define PKCS11_TA_VERSION_PATCH 0 19 20 /* Attribute specific values */ 21 #define PKCS11_UNAVAILABLE_INFORMATION UINT32_C(0xFFFFFFFF) 22 #define PKCS11_UNDEFINED_ID PKCS11_UNAVAILABLE_INFORMATION 23 #define PKCS11_FALSE false 24 #define PKCS11_TRUE true 25 26 /* 27 * Note on PKCS#11 TA commands ABI 28 * 29 * For evolution of the TA API and to not mess with the GPD TEE 4 parameters 30 * constraint, all the PKCS11 TA invocation commands use a subset of available 31 * the GPD TEE invocation parameter types. 32 * 33 * Param#0 is used for the so-called control arguments of the invoked command 34 * and for providing a PKCS#11 compliant status code for the request command. 35 * Param#0 is an in/out memory reference (aka memref[0]). The input buffer 36 * stores serialized arguments for the command. The output buffer store the 37 * 32bit TA return code for the command. As a consequence, param#0 shall 38 * always be an input/output memory reference of at least 32bit, more if 39 * the command expects more input arguments. 40 * 41 * When the TA returns with TEE_SUCCESS result, client shall always get the 42 * 32bit value stored in param#0 output buffer and use the value as TA 43 * return code for the invoked command. 44 * 45 * Param#1 can be used for input data arguments of the invoked command. 46 * It is unused or is a input memory reference, aka memref[1]. 47 * Evolution of the API may use memref[1] for output data as well. 48 * 49 * Param#2 is mostly used for output data arguments of the invoked command 50 * and for output handles generated from invoked commands. 51 * Few commands uses it for a secondary input data buffer argument. 52 * It is unused or is a input/output/in-out memory reference, aka memref[2]. 53 * 54 * Param#3 is currently unused and reserved for evolution of the API. 55 */ 56 57 enum pkcs11_ta_cmd { 58 /* 59 * PKCS11_CMD_PING Ack TA presence and return version info 60 * 61 * [in] memref[0] = 32bit, unused, must be 0 62 * [out] memref[0] = 32bit return code, enum pkcs11_rc 63 * [out] memref[2] = [ 64 * 32bit version major value, 65 * 32bit version minor value 66 * 32bit version patch value 67 * ] 68 */ 69 PKCS11_CMD_PING = 0, 70 71 /* 72 * PKCS11_CMD_SLOT_LIST - Get the table of the valid slot IDs 73 * 74 * [in] memref[0] = 32bit, unused, must be 0 75 * [out] memref[0] = 32bit return code, enum pkcs11_rc 76 * [out] memref[2] = 32bit array slot_ids[slot counts] 77 * 78 * The TA instance may represent several PKCS#11 slots and 79 * associated tokens. This commadn reports the IDs of embedded tokens. 80 * This command relates the PKCS#11 API function C_GetSlotList(). 81 */ 82 PKCS11_CMD_SLOT_LIST = 1, 83 84 /* 85 * PKCS11_CMD_SLOT_INFO - Get cryptoki structured slot information 86 * 87 * [in] memref[0] = 32bit slot ID 88 * [out] memref[0] = 32bit return code, enum pkcs11_rc 89 * [out] memref[2] = (struct pkcs11_slot_info)info 90 * 91 * The TA instance may represent several PKCS#11 slots/tokens. 92 * This command relates the PKCS#11 API function C_GetSlotInfo(). 93 */ 94 PKCS11_CMD_SLOT_INFO = 2, 95 96 /* 97 * PKCS11_CMD_TOKEN_INFO - Get cryptoki structured token information 98 * 99 * [in] memref[0] = 32bit slot ID 100 * [out] memref[0] = 32bit return code, enum pkcs11_rc 101 * [out] memref[2] = (struct pkcs11_token_info)info 102 * 103 * The TA instance may represent several PKCS#11 slots/tokens. 104 * This command relates the PKCS#11 API function C_GetTokenInfo(). 105 */ 106 PKCS11_CMD_TOKEN_INFO = 3, 107 108 /* 109 * PKCS11_CMD_MECHANISM_IDS - Get list of the supported mechanisms 110 * 111 * [in] memref[0] = 32bit slot ID 112 * [out] memref[0] = 32bit return code, enum pkcs11_rc 113 * [out] memref[2] = 32bit array mechanism IDs 114 * 115 * This command relates to the PKCS#11 API function 116 * C_GetMechanismList(). 117 */ 118 PKCS11_CMD_MECHANISM_IDS = 4, 119 120 /* 121 * PKCS11_CMD_MECHANISM_INFO - Get information on a specific mechanism 122 * 123 * [in] memref[0] = [ 124 * 32bit slot ID, 125 * 32bit mechanism ID (PKCS11_CKM_*) 126 * ] 127 * [out] memref[0] = 32bit return code, enum pkcs11_rc 128 * [out] memref[2] = (struct pkcs11_mechanism_info)info 129 * 130 * This command relates to the PKCS#11 API function 131 * C_GetMechanismInfo(). 132 */ 133 PKCS11_CMD_MECHANISM_INFO = 5, 134 135 /* 136 * PKCS11_CMD_OPEN_SESSION - Open a session 137 * 138 * [in] memref[0] = [ 139 * 32bit slot ID, 140 * 32bit session flags, 141 * ] 142 * [out] memref[0] = 32bit return code, enum pkcs11_rc 143 * [out] memref[2] = 32bit session handle 144 * 145 * This command relates to the PKCS#11 API function C_OpenSession(). 146 */ 147 PKCS11_CMD_OPEN_SESSION = 6, 148 149 /* 150 * PKCS11_CMD_CLOSE_SESSION - Close an opened session 151 * 152 * [in] memref[0] = 32bit session handle 153 * [out] memref[0] = 32bit return code, enum pkcs11_rc 154 * 155 * This command relates to the PKCS#11 API function C_CloseSession(). 156 */ 157 PKCS11_CMD_CLOSE_SESSION = 7, 158 159 /* 160 * PKCS11_CMD_CLOSE_ALL_SESSIONS - Close all client sessions on token 161 * 162 * [in] memref[0] = 32bit slot ID 163 * [out] memref[0] = 32bit return code, enum pkcs11_rc 164 * 165 * This command relates to the PKCS#11 API function 166 * C_CloseAllSessions(). 167 */ 168 PKCS11_CMD_CLOSE_ALL_SESSIONS = 8, 169 170 /* 171 * PKCS11_CMD_SESSION_INFO - Get Cryptoki information on a session 172 * 173 * [in] memref[0] = 32bit session handle 174 * [out] memref[0] = 32bit return code, enum pkcs11_rc 175 * [out] memref[2] = (struct pkcs11_session_info)info 176 * 177 * This command relates to the PKCS#11 API function C_GetSessionInfo(). 178 */ 179 PKCS11_CMD_SESSION_INFO = 9, 180 181 /* 182 * PKCS11_CMD_INIT_TOKEN - Initialize PKCS#11 token 183 * 184 * [in] memref[0] = [ 185 * 32bit slot ID, 186 * 32bit PIN length, 187 * byte array label[32] 188 * byte array PIN[PIN length], 189 * ] 190 * [out] memref[0] = 32bit return code, enum pkcs11_rc 191 * 192 * This command relates to the PKCS#11 API function C_InitToken(). 193 */ 194 PKCS11_CMD_INIT_TOKEN = 10, 195 196 /* 197 * PKCS11_CMD_INIT_PIN - Initialize user PIN 198 * 199 * [in] memref[0] = [ 200 * 32bit session handle, 201 * 32bit PIN byte size, 202 * byte array: PIN data 203 * ] 204 * [out] memref[0] = 32bit return code, enum pkcs11_rc 205 * 206 * This command relates to the PKCS#11 API function C_InitPIN(). 207 */ 208 PKCS11_CMD_INIT_PIN = 11, 209 210 /* 211 * PKCS11_CMD_SET_PIN - Change user PIN 212 * 213 * [in] memref[0] = [ 214 * 32bit session handle, 215 * 32bit old PIN byte size, 216 * 32bit new PIN byte size, 217 * byte array: PIN data, 218 * byte array: new PIN data, 219 * ] 220 * [out] memref[0] = 32bit return code, enum pkcs11_rc 221 * 222 * This command relates to the PKCS#11 API function C_SetPIN(). 223 */ 224 PKCS11_CMD_SET_PIN = 12, 225 226 /* 227 * PKCS11_CMD_LOGIN - Initialize user PIN 228 * 229 * [in] memref[0] = [ 230 * 32bit session handle, 231 * 32bit user identifier, enum pkcs11_user_type 232 * 32bit PIN byte size, 233 * byte array: PIN data 234 * ] 235 * [out] memref[0] = 32bit return code, enum pkcs11_rc 236 * 237 * This command relates to the PKCS#11 API function C_Login(). 238 */ 239 PKCS11_CMD_LOGIN = 13, 240 241 /* 242 * PKCS11_CMD_LOGOUT - Log out from token 243 * 244 * [in] memref[0] = [ 245 * 32bit session handle, 246 * ] 247 * [out] memref[0] = 32bit return code, enum pkcs11_rc 248 * 249 * This command relates to the PKCS#11 API function C_Logout(). 250 */ 251 PKCS11_CMD_LOGOUT = 14, 252 }; 253 254 /* 255 * Command return codes 256 * PKCS11_<x> relates CryptoKi client API CKR_<x> 257 */ 258 enum pkcs11_rc { 259 PKCS11_CKR_OK = 0, 260 PKCS11_CKR_CANCEL = 0x0001, 261 PKCS11_CKR_SLOT_ID_INVALID = 0x0003, 262 PKCS11_CKR_GENERAL_ERROR = 0x0005, 263 PKCS11_CKR_FUNCTION_FAILED = 0x0006, 264 PKCS11_CKR_ARGUMENTS_BAD = 0x0007, 265 PKCS11_CKR_ATTRIBUTE_READ_ONLY = 0x0010, 266 PKCS11_CKR_ATTRIBUTE_SENSITIVE = 0x0011, 267 PKCS11_CKR_ATTRIBUTE_TYPE_INVALID = 0x0012, 268 PKCS11_CKR_ATTRIBUTE_VALUE_INVALID = 0x0013, 269 PKCS11_CKR_ACTION_PROHIBITED = 0x001b, 270 PKCS11_CKR_DATA_INVALID = 0x0020, 271 PKCS11_CKR_DATA_LEN_RANGE = 0x0021, 272 PKCS11_CKR_DEVICE_ERROR = 0x0030, 273 PKCS11_CKR_DEVICE_MEMORY = 0x0031, 274 PKCS11_CKR_DEVICE_REMOVED = 0x0032, 275 PKCS11_CKR_ENCRYPTED_DATA_INVALID = 0x0040, 276 PKCS11_CKR_ENCRYPTED_DATA_LEN_RANGE = 0x0041, 277 PKCS11_CKR_KEY_HANDLE_INVALID = 0x0060, 278 PKCS11_CKR_KEY_SIZE_RANGE = 0x0062, 279 PKCS11_CKR_KEY_TYPE_INCONSISTENT = 0x0063, 280 PKCS11_CKR_KEY_FUNCTION_NOT_PERMITTED = 0x0068, 281 PKCS11_CKR_KEY_NOT_WRAPPABLE = 0x0069, 282 PKCS11_CKR_KEY_UNEXTRACTABLE = 0x006a, 283 PKCS11_CKR_MECHANISM_INVALID = 0x0070, 284 PKCS11_CKR_MECHANISM_PARAM_INVALID = 0x0071, 285 PKCS11_CKR_OBJECT_HANDLE_INVALID = 0x0082, 286 PKCS11_CKR_OPERATION_ACTIVE = 0x0090, 287 PKCS11_CKR_OPERATION_NOT_INITIALIZED = 0x0091, 288 PKCS11_CKR_PIN_INCORRECT = 0x00a0, 289 PKCS11_CKR_PIN_INVALID = 0x00a1, 290 PKCS11_CKR_PIN_LEN_RANGE = 0x00a2, 291 PKCS11_CKR_PIN_EXPIRED = 0x00a3, 292 PKCS11_CKR_PIN_LOCKED = 0x00a4, 293 PKCS11_CKR_SESSION_CLOSED = 0x00b0, 294 PKCS11_CKR_SESSION_COUNT = 0x00b1, 295 PKCS11_CKR_SESSION_HANDLE_INVALID = 0x00b3, 296 PKCS11_CKR_SESSION_READ_ONLY = 0x00b5, 297 PKCS11_CKR_SESSION_EXISTS = 0x00b6, 298 PKCS11_CKR_SESSION_READ_ONLY_EXISTS = 0x00b7, 299 PKCS11_CKR_SESSION_READ_WRITE_SO_EXISTS = 0x00b8, 300 PKCS11_CKR_SIGNATURE_INVALID = 0x00c0, 301 PKCS11_CKR_SIGNATURE_LEN_RANGE = 0x00c1, 302 PKCS11_CKR_TEMPLATE_INCOMPLETE = 0x00d0, 303 PKCS11_CKR_TEMPLATE_INCONSISTENT = 0x00d1, 304 PKCS11_CKR_TOKEN_NOT_PRESENT = 0x00e0, 305 PKCS11_CKR_TOKEN_NOT_RECOGNIZED = 0x00e1, 306 PKCS11_CKR_TOKEN_WRITE_PROTECTED = 0x00e2, 307 PKCS11_CKR_USER_ALREADY_LOGGED_IN = 0x0100, 308 PKCS11_CKR_USER_NOT_LOGGED_IN = 0x0101, 309 PKCS11_CKR_USER_PIN_NOT_INITIALIZED = 0x0102, 310 PKCS11_CKR_USER_TYPE_INVALID = 0x0103, 311 PKCS11_CKR_USER_ANOTHER_ALREADY_LOGGED_IN = 0x0104, 312 PKCS11_CKR_USER_TOO_MANY_TYPES = 0x0105, 313 PKCS11_CKR_DOMAIN_PARAMS_INVALID = 0x0130, 314 PKCS11_CKR_CURVE_NOT_SUPPORTED = 0x0140, 315 PKCS11_CKR_BUFFER_TOO_SMALL = 0x0150, 316 PKCS11_CKR_SAVED_STATE_INVALID = 0x0160, 317 PKCS11_CKR_INFORMATION_SENSITIVE = 0x0170, 318 PKCS11_CKR_STATE_UNSAVEABLE = 0x0180, 319 PKCS11_CKR_PIN_TOO_WEAK = 0x01b8, 320 PKCS11_CKR_PUBLIC_KEY_INVALID = 0x01b9, 321 PKCS11_CKR_FUNCTION_REJECTED = 0x0200, 322 /* Vendor specific IDs not returned to client */ 323 PKCS11_RV_NOT_FOUND = 0x80000000, 324 PKCS11_RV_NOT_IMPLEMENTED = 0x80000001, 325 }; 326 327 /* 328 * Arguments for PKCS11_CMD_SLOT_INFO 329 */ 330 #define PKCS11_SLOT_DESC_SIZE 64 331 #define PKCS11_SLOT_MANUFACTURER_SIZE 32 332 #define PKCS11_SLOT_VERSION_SIZE 2 333 334 struct pkcs11_slot_info { 335 uint8_t slot_description[PKCS11_SLOT_DESC_SIZE]; 336 uint8_t manufacturer_id[PKCS11_SLOT_MANUFACTURER_SIZE]; 337 uint32_t flags; 338 uint8_t hardware_version[PKCS11_SLOT_VERSION_SIZE]; 339 uint8_t firmware_version[PKCS11_SLOT_VERSION_SIZE]; 340 }; 341 342 /* 343 * Values for pkcs11_slot_info::flags. 344 * PKCS11_CKFS_<x> reflects CryptoKi client API slot flags CKF_<x>. 345 */ 346 #define PKCS11_CKFS_TOKEN_PRESENT (1U << 0) 347 #define PKCS11_CKFS_REMOVABLE_DEVICE (1U << 1) 348 #define PKCS11_CKFS_HW_SLOT (1U << 2) 349 350 /* 351 * Arguments for PKCS11_CMD_TOKEN_INFO 352 */ 353 #define PKCS11_TOKEN_LABEL_SIZE 32 354 #define PKCS11_TOKEN_MANUFACTURER_SIZE 32 355 #define PKCS11_TOKEN_MODEL_SIZE 16 356 #define PKCS11_TOKEN_SERIALNUM_SIZE 16 357 358 struct pkcs11_token_info { 359 uint8_t label[PKCS11_TOKEN_LABEL_SIZE]; 360 uint8_t manufacturer_id[PKCS11_TOKEN_MANUFACTURER_SIZE]; 361 uint8_t model[PKCS11_TOKEN_MODEL_SIZE]; 362 uint8_t serial_number[PKCS11_TOKEN_SERIALNUM_SIZE]; 363 uint32_t flags; 364 uint32_t max_session_count; 365 uint32_t session_count; 366 uint32_t max_rw_session_count; 367 uint32_t rw_session_count; 368 uint32_t max_pin_len; 369 uint32_t min_pin_len; 370 uint32_t total_public_memory; 371 uint32_t free_public_memory; 372 uint32_t total_private_memory; 373 uint32_t free_private_memory; 374 uint8_t hardware_version[2]; 375 uint8_t firmware_version[2]; 376 uint8_t utc_time[16]; 377 }; 378 379 /* 380 * Values for pkcs11_token_info::flags. 381 * PKCS11_CKFT_<x> reflects CryptoKi client API token flags CKF_<x>. 382 */ 383 #define PKCS11_CKFT_RNG (1U << 0) 384 #define PKCS11_CKFT_WRITE_PROTECTED (1U << 1) 385 #define PKCS11_CKFT_LOGIN_REQUIRED (1U << 2) 386 #define PKCS11_CKFT_USER_PIN_INITIALIZED (1U << 3) 387 #define PKCS11_CKFT_RESTORE_KEY_NOT_NEEDED (1U << 5) 388 #define PKCS11_CKFT_CLOCK_ON_TOKEN (1U << 6) 389 #define PKCS11_CKFT_PROTECTED_AUTHENTICATION_PATH (1U << 8) 390 #define PKCS11_CKFT_DUAL_CRYPTO_OPERATIONS (1U << 9) 391 #define PKCS11_CKFT_TOKEN_INITIALIZED (1U << 10) 392 #define PKCS11_CKFT_SECONDARY_AUTHENTICATION (1U << 11) 393 #define PKCS11_CKFT_USER_PIN_COUNT_LOW (1U << 16) 394 #define PKCS11_CKFT_USER_PIN_FINAL_TRY (1U << 17) 395 #define PKCS11_CKFT_USER_PIN_LOCKED (1U << 18) 396 #define PKCS11_CKFT_USER_PIN_TO_BE_CHANGED (1U << 19) 397 #define PKCS11_CKFT_SO_PIN_COUNT_LOW (1U << 20) 398 #define PKCS11_CKFT_SO_PIN_FINAL_TRY (1U << 21) 399 #define PKCS11_CKFT_SO_PIN_LOCKED (1U << 22) 400 #define PKCS11_CKFT_SO_PIN_TO_BE_CHANGED (1U << 23) 401 #define PKCS11_CKFT_ERROR_STATE (1U << 24) 402 403 /* Values for user identity */ 404 enum pkcs11_user_type { 405 PKCS11_CKU_SO = 0x000, 406 PKCS11_CKU_USER = 0x001, 407 PKCS11_CKU_CONTEXT_SPECIFIC = 0x002, 408 }; 409 410 /* 411 * Values for 32bit session flags argument to PKCS11_CMD_OPEN_SESSION 412 * and pkcs11_session_info::flags. 413 * PKCS11_CKFSS_<x> reflects CryptoKi client API session flags CKF_<x>. 414 */ 415 #define PKCS11_CKFSS_RW_SESSION (1U << 1) 416 #define PKCS11_CKFSS_SERIAL_SESSION (1U << 2) 417 418 /* 419 * Arguments for PKCS11_CMD_SESSION_INFO 420 */ 421 422 struct pkcs11_session_info { 423 uint32_t slot_id; 424 uint32_t state; 425 uint32_t flags; 426 uint32_t device_error; 427 }; 428 429 /* Valid values for pkcs11_session_info::state */ 430 enum pkcs11_session_state { 431 PKCS11_CKS_RO_PUBLIC_SESSION = 0, 432 PKCS11_CKS_RO_USER_FUNCTIONS = 1, 433 PKCS11_CKS_RW_PUBLIC_SESSION = 2, 434 PKCS11_CKS_RW_USER_FUNCTIONS = 3, 435 PKCS11_CKS_RW_SO_FUNCTIONS = 4, 436 }; 437 438 /* 439 * Arguments for PKCS11_CMD_MECHANISM_INFO 440 */ 441 442 struct pkcs11_mechanism_info { 443 uint32_t min_key_size; 444 uint32_t max_key_size; 445 uint32_t flags; 446 }; 447 448 /* 449 * Values for pkcs11_mechanism_info::flags. 450 * PKCS11_CKFM_<x> reflects CryptoKi client API mechanism flags CKF_<x>. 451 */ 452 #define PKCS11_CKFM_HW (1U << 0) 453 #define PKCS11_CKFM_ENCRYPT (1U << 8) 454 #define PKCS11_CKFM_DECRYPT (1U << 9) 455 #define PKCS11_CKFM_DIGEST (1U << 10) 456 #define PKCS11_CKFM_SIGN (1U << 11) 457 #define PKCS11_CKFM_SIGN_RECOVER (1U << 12) 458 #define PKCS11_CKFM_VERIFY (1U << 13) 459 #define PKCS11_CKFM_VERIFY_RECOVER (1U << 14) 460 #define PKCS11_CKFM_GENERATE (1U << 15) 461 #define PKCS11_CKFM_GENERATE_KEY_PAIR (1U << 16) 462 #define PKCS11_CKFM_WRAP (1U << 17) 463 #define PKCS11_CKFM_UNWRAP (1U << 18) 464 #define PKCS11_CKFM_DERIVE (1U << 19) 465 #define PKCS11_CKFM_EC_F_P (1U << 20) 466 #define PKCS11_CKFM_EC_F_2M (1U << 21) 467 #define PKCS11_CKFM_EC_ECPARAMETERS (1U << 22) 468 #define PKCS11_CKFM_EC_NAMEDCURVE (1U << 23) 469 #define PKCS11_CKFM_EC_UNCOMPRESS (1U << 24) 470 #define PKCS11_CKFM_EC_COMPRESS (1U << 25) 471 472 /* 473 * Valid values for mechanism IDs 474 * PKCS11_CKM_<x> reflects CryptoKi client API mechanism IDs CKM_<x>. 475 */ 476 enum pkcs11_mechanism_id { 477 PKCS11_CKM_AES_ECB = 0x01081, 478 }; 479 #endif /*PKCS11_TA_H*/ 480