1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup TeeTrusted 18 * @{ 19 * 20 * @brief TEE(Trusted Excution Environment) API. 21 * Provides security capability APIs such as trusted storage, encryption and decryption, 22 * and trusted time for trusted application development. 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file tee_crypto_api.h 29 * 30 * @brief Provides APIs for cryptographic operations. 31 * 32 * You can use these APIs to implement encryption and decryption. 33 * 34 * @library NA 35 * @kit TEEKit 36 * @syscap SystemCapability.Tee.TeeClient 37 * @since 20 38 */ 39 40 #ifndef TEE_CRYPTO_API_H 41 #define TEE_CRYPTO_API_H 42 43 #include <pthread.h> 44 #include <tee_defines.h> 45 #include <tee_mem_mgmt_api.h> 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 #ifndef NULL 52 /** 53 * @brief Definition of <b>NULL</b>. 54 * 55 * @since 20 56 */ 57 #define NULL ((void *)0) 58 #endif 59 60 /** 61 * @brief Defines the maximum key length, in bits. 62 * 63 * @since 20 64 */ 65 #define TEE_MAX_KEY_SIZE_IN_BITS (1024 * 8) 66 67 /** 68 * @brief Defines the length of the SW_RSA key, in bytes. 69 * 70 * @since 20 71 */ 72 #define SW_RSA_KEYLEN 1024 73 74 /** 75 * @brief Defines the maximum length of other Diffie-Hellman (DH) information, in bytes. 76 * 77 * @since 20 78 */ 79 #define TEE_DH_MAX_SIZE_OF_OTHER_INFO 64 80 81 /** 82 * @brief Defines the maximum parameter count. 83 * 84 * @since 20 85 */ 86 #define TEE_PARAM_COUNT_MAX 9 87 88 /** 89 * @brief Enumerates the cryptographic operation handles. 90 * 91 * @since 20 92 */ 93 enum __TEE_Operation_Constants { 94 /** Cipher */ 95 TEE_OPERATION_CIPHER = 0x1, 96 /** MAC */ 97 TEE_OPERATION_MAC = 3, 98 /** AE */ 99 TEE_OPERATION_AE = 4, 100 /** Digest */ 101 TEE_OPERATION_DIGEST = 5, 102 /** Asymmetric Cipher */ 103 TEE_OPERATION_ASYMMETRIC_CIPHER = 6, 104 /** Asymmetric Signature */ 105 TEE_OPERATION_ASYMMETRIC_SIGNATURE = 7, 106 /** Key Derivation */ 107 TEE_OPERATION_KEY_DERIVATION = 8, 108 /** KDF Key Derivation */ 109 TEE_OPERATION_KDF_KEY_DERIVATION = 9, 110 }; 111 112 /** 113 * @brief Enumerates the cryptographic algorithms. 114 * 115 * @since 20 116 */ 117 enum __tee_crypto_algorithm_id { 118 /** Invalid algorithm */ 119 TEE_ALG_INVALID = 0x0, 120 /** AES_ECB_NOPAD */ 121 TEE_ALG_AES_ECB_NOPAD = 0x10000010, 122 /** AES_CBC_NOPAD */ 123 TEE_ALG_AES_CBC_NOPAD = 0x10000110, 124 /** AES_CTR */ 125 TEE_ALG_AES_CTR = 0x10000210, 126 /** AES_CTS */ 127 TEE_ALG_AES_CTS = 0x10000310, 128 /** AES_XTS */ 129 TEE_ALG_AES_XTS = 0x10000410, 130 /** AES_CBC_MAC_NOPAD */ 131 TEE_ALG_AES_CBC_MAC_NOPAD = 0x30000110, 132 /** AES_CBC_MAC_PKCS5 */ 133 TEE_ALG_AES_CBC_MAC_PKCS5 = 0x30000510, 134 /** AES_CMAC */ 135 TEE_ALG_AES_CMAC = 0x30000610, 136 /** AES_GMAC */ 137 TEE_ALG_AES_GMAC = 0x30000810, 138 /** AES_CCM */ 139 TEE_ALG_AES_CCM = 0x40000710, 140 /** AES_GCM */ 141 TEE_ALG_AES_GCM = 0x40000810, 142 /** DES_ECB_NOPAD */ 143 TEE_ALG_DES_ECB_NOPAD = 0x10000011, 144 /** DES_CBC_NOPAD */ 145 TEE_ALG_DES_CBC_NOPAD = 0x10000111, 146 /** DES_CBC_MAC_NOPAD */ 147 TEE_ALG_DES_CBC_MAC_NOPAD = 0x30000111, 148 /** DES_CBC_MAC_PKCS5 */ 149 TEE_ALG_DES_CBC_MAC_PKCS5 = 0x30000511, 150 /** DES3_ECB_NOPAD */ 151 TEE_ALG_DES3_ECB_NOPAD = 0x10000013, 152 /** DES3_CBC_NOPAD */ 153 TEE_ALG_DES3_CBC_NOPAD = 0x10000113, 154 /** DES3_CBC_MAC_NOPAD */ 155 TEE_ALG_DES3_CBC_MAC_NOPAD = 0x30000113, 156 /** DES3_CBC_MAC_PKCS5 */ 157 TEE_ALG_DES3_CBC_MAC_PKCS5 = 0x30000513, 158 /** RSASSA_PKCS1_V1_5_MD5 */ 159 TEE_ALG_RSASSA_PKCS1_V1_5_MD5 = 0x70001830, 160 /** RSASSA_PKCS1_V1_5_SHA1 */ 161 TEE_ALG_RSASSA_PKCS1_V1_5_SHA1 = 0x70002830, 162 /** RSASSA_PKCS1_V1_5_SHA224 */ 163 TEE_ALG_RSASSA_PKCS1_V1_5_SHA224 = 0x70003830, 164 /** RSASSA_PKCS1_V1_5_SHA256 */ 165 TEE_ALG_RSASSA_PKCS1_V1_5_SHA256 = 0x70004830, 166 /** RSASSA_PKCS1_V1_5_SHA384 */ 167 TEE_ALG_RSASSA_PKCS1_V1_5_SHA384 = 0x70005830, 168 /** RSASSA_PKCS1_V1_5_SHA512 */ 169 TEE_ALG_RSASSA_PKCS1_V1_5_SHA512 = 0x70006830, 170 /** RSASSA_PKCS1_V1_5_SM3 */ 171 TEE_ALG_RSASSA_PKCS1_V1_5_SM3 = 0xF0007830, 172 /** RSASSA_PKCS1_V1_5_MD5_SHA1 */ 173 TEE_ALG_RSASSA_PKCS1_V1_5_MD5_SHA1 = 0xF0008830, 174 /** RSASSA_PKCS1_PSS_MGF1_MD5 */ 175 TEE_ALG_RSASSA_PKCS1_PSS_MGF1_MD5 = 0x70111930, 176 /** RSASSA_PKCS1_PSS_MGF1_SHA1 */ 177 TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA1 = 0x70212930, 178 /** RSASSA_PKCS1_PSS_MGF1_SHA224 */ 179 TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA224 = 0x70313930, 180 /** RSASSA_PKCS1_PSS_MGF1_SHA256 */ 181 TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA256 = 0x70414930, 182 /** RSASSA_PKCS1_PSS_MGF1_SHA384 */ 183 TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA384 = 0x70515930, 184 /** RSASSA_PKCS1_PSS_MGF1_SHA512 */ 185 TEE_ALG_RSASSA_PKCS1_PSS_MGF1_SHA512 = 0x70616930, 186 /** RSAES_PKCS1_V1_5 */ 187 TEE_ALG_RSAES_PKCS1_V1_5 = 0x60000130, 188 /** RSAES_PKCS1_OAEP_MGF1_SHA1 */ 189 TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA1 = 0x60210230, 190 /** RSAES_PKCS1_OAEP_MGF1_SHA224 */ 191 TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA224 = 0x60211230, 192 /** RSAES_PKCS1_OAEP_MGF1_SHA256 */ 193 TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA256 = 0x60212230, 194 /** RSAES_PKCS1_OAEP_MGF1_SHA384 */ 195 TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA384 = 0x60213230, 196 /** RSAES_PKCS1_OAEP_MGF1_SHA512 */ 197 TEE_ALG_RSAES_PKCS1_OAEP_MGF1_SHA512 = 0x60214230, 198 /** RSA_NOPAD */ 199 TEE_ALG_RSA_NOPAD = 0x60000030, 200 /** DSA_SHA1 */ 201 TEE_ALG_DSA_SHA1 = 0x70002131, 202 /** DSA_SHA224 */ 203 TEE_ALG_DSA_SHA224 = 0x70003131, 204 /** DSA_SHA256 */ 205 TEE_ALG_DSA_SHA256 = 0x70004131, 206 /** DH_DERIVE_SHARED_SECRET */ 207 TEE_ALG_DH_DERIVE_SHARED_SECRET = 0x80000032, 208 /** MD5 */ 209 TEE_ALG_MD5 = 0x50000001, 210 /** SHA1 */ 211 TEE_ALG_SHA1 = 0x50000002, 212 /** SHA224 */ 213 TEE_ALG_SHA224 = 0x50000003, 214 /** SHA256 */ 215 TEE_ALG_SHA256 = 0x50000004, 216 /** SHA384 */ 217 TEE_ALG_SHA384 = 0x50000005, 218 /** SHA512 */ 219 TEE_ALG_SHA512 = 0x50000006, 220 /** HMAC_MD5 */ 221 TEE_ALG_HMAC_MD5 = 0x30000001, 222 /** HMAC_SHA1 */ 223 TEE_ALG_HMAC_SHA1 = 0x30000002, 224 /** HMAC_SHA224 */ 225 TEE_ALG_HMAC_SHA224 = 0x30000003, 226 /** HMAC_SHA256 */ 227 TEE_ALG_HMAC_SHA256 = 0x30000004, 228 /** HMAC_SHA384 */ 229 TEE_ALG_HMAC_SHA384 = 0x30000005, 230 /** HMAC_SHA512 */ 231 TEE_ALG_HMAC_SHA512 = 0x30000006, 232 /** HMAC_SM3 */ 233 TEE_ALG_HMAC_SM3 = 0x30000007, 234 /** AES_ECB_PKCS5 */ 235 TEE_ALG_AES_ECB_PKCS5 = 0x10000020, 236 /** AES_CBC_PKCS5 */ 237 TEE_ALG_AES_CBC_PKCS5 = 0x10000220, 238 /** AES_CBC_ISO_PADDING */ 239 TEE_ALG_AES_CBC_ISO_PADDING = 0x10000330, 240 /** ECDSA_SHA1 */ 241 TEE_ALG_ECDSA_SHA1 = 0x70001042, 242 /** ECDSA_SHA224 */ 243 TEE_ALG_ECDSA_SHA224 = 0x70002042, 244 /** ECDSA_SHA256 */ 245 TEE_ALG_ECDSA_SHA256 = 0x70003042, 246 /** ECDSA_SHA384 */ 247 TEE_ALG_ECDSA_SHA384 = 0x70004042, 248 /** ECDSA_SHA512 */ 249 TEE_ALG_ECDSA_SHA512 = 0x70005042, 250 /** ED25519 */ 251 TEE_ALG_ED25519 = 0x70005043, 252 /** ECDH_DERIVE_SHARED_SECRET */ 253 TEE_ALG_ECDH_DERIVE_SHARED_SECRET = 0x80000042, 254 /** X25519 */ 255 TEE_ALG_X25519 = 0x80000044, 256 /** ECC */ 257 TEE_ALG_ECC = 0x80000001, 258 /** ECDSA_P192 */ 259 TEE_ALG_ECDSA_P192 = 0x70001042, 260 /** ECDSA_P224 */ 261 TEE_ALG_ECDSA_P224 = 0x70002042, 262 /** ECDSA_P256 */ 263 TEE_ALG_ECDSA_P256 = 0x70003042, 264 /** ECDSA_P384 */ 265 TEE_ALG_ECDSA_P384 = 0x70004042, 266 /** ECDSA_P521 */ 267 TEE_ALG_ECDSA_P521 = 0x70005042, 268 /** ECDH_P192 */ 269 TEE_ALG_ECDH_P192 = 0x80001042, 270 /** ECDH_P224 */ 271 TEE_ALG_ECDH_P224 = 0x80002042, 272 /** ECDH_P256 */ 273 TEE_ALG_ECDH_P256 = 0x80003042, 274 /** ECDH_P384 */ 275 TEE_ALG_ECDH_P384 = 0x80004042, 276 /** ECDH_P521 */ 277 TEE_ALG_ECDH_P521 = 0x80005042, 278 /** SIP_HASH */ 279 TEE_ALG_SIP_HASH = 0xF0000002, 280 /** SM2_DSA_SM3 */ 281 TEE_ALG_SM2_DSA_SM3 = 0x70006045, 282 /** SM2_PKE */ 283 TEE_ALG_SM2_PKE = 0x80000045, 284 /** SM3 */ 285 TEE_ALG_SM3 = 0x50000007, 286 /** SM4_ECB_NOPAD */ 287 TEE_ALG_SM4_ECB_NOPAD = 0x10000014, 288 /** SM4_ECB_PKCS7 */ 289 TEE_ALG_SM4_ECB_PKCS7 = 0x10000024, 290 /** SM4_CBC_NOPAD */ 291 TEE_ALG_SM4_CBC_NOPAD = 0x10000114, 292 /** SM4_CBC_PKCS7 */ 293 TEE_ALG_SM4_CBC_PKCS7 = 0xF0000003, 294 /** SM4_CTR */ 295 TEE_ALG_SM4_CTR = 0x10000214, 296 /** SM4_CFB128 */ 297 TEE_ALG_SM4_CFB128 = 0xF0000000, 298 /** SM4_XTS */ 299 TEE_ALG_SM4_XTS = 0x10000414, 300 /** SM4_OFB */ 301 TEE_ALG_SM4_OFB = 0x10000514, 302 /** AES_OFB */ 303 TEE_ALG_AES_OFB = 0x10000510, 304 /** AES_CFB128 */ 305 TEE_ALG_AES_CFB128 = 0xF0000610, 306 /** SM4_GCM */ 307 TEE_ALG_SM4_GCM = 0xF0000005, 308 /** PBKDF2_HMAC_SHA1_DERIVE_KEY */ 309 TEE_ALG_PBKDF2_HMAC_SHA1_DERIVE_KEY = 0x800020C2, 310 /** PBKDF2_HMAC_SHA256_DERIVE_KEY */ 311 TEE_ALG_PBKDF2_HMAC_SHA256_DERIVE_KEY = 0x800040C2, 312 /** PBKDF2_HMAC_SHA384_DERIVE_KEY */ 313 TEE_ALG_PBKDF2_HMAC_SHA384_DERIVE_KEY = 0x800050C2, 314 /** PBKDF2_HMAC_SHA512_DERIVE_KEY */ 315 TEE_ALG_PBKDF2_HMAC_SHA512_DERIVE_KEY = 0x800060C2, 316 /** HKDF */ 317 TEE_ALG_HKDF = 0x80000047, 318 /** PRF */ 319 TEE_ALG_PRF = 0xF0000006, 320 }; 321 322 /** 323 * @brief Defines the <b>__tee_crypto_algorithm_id</b> struct. 324 * 325 * @see __tee_crypto_algorithm_id 326 * 327 * @since 20 328 */ 329 typedef enum __tee_crypto_algorithm_id tee_crypto_algorithm_id; 330 331 /** 332 * @brief No element is available. 333 * 334 * @since 20 335 */ 336 #define TEE_OPTIONAL_ELEMENT_NONE 0x00000000 337 338 /** 339 * @brief Enumerates the Elliptic-Curve Cryptography (ECC) curves supported. 340 * 341 * @since 20 342 */ 343 typedef enum { 344 /** CURVE_NIST_P192 */ 345 TEE_ECC_CURVE_NIST_P192 = 0x00000001, 346 /** CURVE_NIST_P224 */ 347 TEE_ECC_CURVE_NIST_P224 = 0x00000002, 348 /** CURVE_NIST_P256 */ 349 TEE_ECC_CURVE_NIST_P256 = 0x00000003, 350 /** CURVE_NIST_P384 */ 351 TEE_ECC_CURVE_NIST_P384 = 0x00000004, 352 /** CURVE_NIST_P521 */ 353 TEE_ECC_CURVE_NIST_P521 = 0x00000005, 354 /** CURVE_SM2 256 bits */ 355 TEE_ECC_CURVE_SM2 = 0x00000300, 356 /** CURVE_25519 256 bits */ 357 TEE_ECC_CURVE_25519 = 0x00000200, 358 } TEE_ECC_CURVE; 359 360 /** 361 * @brief Enumerates the Mask Generation Function (MGF1) modes. 362 * 363 * @since 20 364 */ 365 typedef enum { 366 /** SHA1 mode for DH hashing. */ 367 TEE_DH_HASH_SHA1_mode = 0, 368 /** SHA224 mode for DH hashing. */ 369 TEE_DH_HASH_SHA224_mode = 1, 370 /** SHA256 mode for DH hashing. */ 371 TEE_DH_HASH_SHA256_mode = 2, 372 /** SHA384 mode for DH hashing. */ 373 TEE_DH_HASH_SHA384_mode = 3, 374 /** SHA512 mode for DH hashing. */ 375 TEE_DH_HASH_SHA512_mode = 4, 376 /** Total number of DH hashing modes. */ 377 TEE_DH_HASH_NumOfModes, 378 } TEE_DH_HASH_Mode; 379 380 /** 381 * @brief Enumerates the Diffie-Hellman operation modes. 382 * 383 * @since 20 384 */ 385 typedef enum { 386 /** PKCS3 */ 387 TEE_DH_PKCS3_mode = 0, 388 /** X942 algorithm. */ 389 TEE_DH_ANSI_X942_mode = 1, 390 /** Number of modes. */ 391 TEE_DH_NumOfModes, 392 } TEE_DH_OpMode_t; 393 394 /** 395 * @brief Defines an enum for TEE_DH_DerivFuncMode. 396 * 397 * @since 20 398 */ 399 typedef enum { 400 /** ASN1_DerivMode */ 401 TEE_DH_ASN1_DerivMode = 0, 402 /** ConcatDerivMode */ 403 TEE_DH_ConcatDerivMode = 1, 404 /** X963_DerivMode */ 405 TEE_DH_X963_DerivMode = TEE_DH_ConcatDerivMode, 406 /** OMADRM_DerivMode */ 407 TEE_DH_OMADRM_DerivMode = 2, 408 /** ISO18033_KDF1_DerivMode */ 409 TEE_DH_ISO18033_KDF1_DerivMode = 3, 410 /** ISO18033_KDF2_DerivMode */ 411 TEE_DH_ISO18033_KDF2_DerivMode = 4, 412 /** Number of modes. */ 413 TEE_DH_DerivFunc_NumOfModes, 414 } TEE_DH_DerivFuncMode; 415 416 /** 417 * @brief Enumerates the object attributes for cryptographic operations. 418 * 419 * @since 20 420 */ 421 enum __TEE_DK_ObjectAttribute { 422 /** Pointer to the shared secret value. */ 423 TEE_DK_SECRECT = 0, 424 /** Pointer to a struct that contains other data. */ 425 TEE_DK_OTHER, 426 /** Enumerator ID of the hash function to be used. */ 427 TEE_DK_HASH_MODE, 428 /** Enumerator ID of the derivation function mode. */ 429 TEE_DK_DERIVATION_MODE 430 }; 431 432 /** 433 * @brief Defines a struct for __TEE_DK_ObjectAttribute. 434 * 435 * @see __TEE_DK_ObjectAttribute 436 * 437 * @since 20 438 */ 439 typedef enum __TEE_DK_ObjectAttribute tee_dk_objectattribute; 440 441 /** 442 * @brief Enumerates the cryptographic operation modes. 443 * 444 * @since 20 445 */ 446 enum __TEE_OperationMode { 447 /** Encryption */ 448 TEE_MODE_ENCRYPT = 0x0, 449 /** Decryption */ 450 TEE_MODE_DECRYPT, 451 /** Signing */ 452 TEE_MODE_SIGN, 453 /** Signature verification */ 454 TEE_MODE_VERIFY, 455 /** MAC */ 456 TEE_MODE_MAC, 457 /** Digest */ 458 TEE_MODE_DIGEST, 459 /** Key derivation */ 460 TEE_MODE_DERIVE 461 }; 462 463 /** 464 * @brief Enumerates the cryptographic operation states. 465 * 466 * @since 20 467 */ 468 enum tee_operation_state { 469 /** Initial */ 470 TEE_OPERATION_STATE_INITIAL = 0x00000000, 471 /** Active */ 472 TEE_OPERATION_STATE_ACTIVE = 0x00000001, 473 }; 474 475 /** 476 * @brief Defines the mode for cryptographic operations. 477 * 478 * @since 20 479 */ 480 typedef uint32_t TEE_OperationMode; 481 482 /** 483 * @brief Defines a struct for TEE_DH_OtherInfo. 484 * 485 * @since 20 486 */ 487 typedef struct { 488 /** object ID(OID) */ 489 uint8_t algorithm_id[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; 490 /** length of AlgorithmID */ 491 uint32_t size_of_algorithm_id; 492 /** public info of sender */ 493 uint8_t party_u_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; 494 /** length of PartyUInfo */ 495 uint32_t size_of_party_u_info; 496 /** public info of receiver */ 497 uint8_t party_v_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; 498 /** length of PartyVInfo */ 499 uint32_t size_of_party_v_info; 500 /** shared private info */ 501 uint8_t supp_priv_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; 502 /** length of SuppPrivInfo */ 503 uint32_t size_of_supp_priv_info; 504 /** shared public info */ 505 uint8_t supp_pub_info[TEE_DH_MAX_SIZE_OF_OTHER_INFO]; 506 /** length of SuppPubInfo */ 507 uint32_t size_of_supp_pub_info; 508 } TEE_DH_OtherInfo; 509 510 /** 511 * @brief Defines the operation information. 512 * 513 * @since 20 514 */ 515 struct __TEE_OperationInfo { 516 /** Algorithm ID */ 517 uint32_t algorithm; /* #__TEE_CRYPTO_ALGORITHM_ID */ 518 /** Operation type */ 519 uint32_t operationClass; /* #__TEE_Operation_Constants */ 520 /** Operation mode */ 521 uint32_t mode; /* #__TEE_OperationMode */ 522 /** Digest length */ 523 uint32_t digestLength; 524 /** Maximum key length */ 525 uint32_t maxKeySize; 526 /** Key length*/ 527 uint32_t keySize; 528 /** Required key usage */ 529 uint32_t requiredKeyUsage; 530 /** Handle state */ 531 uint32_t handleState; 532 /** Key */ 533 void *keyValue; 534 }; 535 536 /** 537 * @brief Defines a struct for __TEE_OperationInfo. 538 * 539 * @see __TEE_OperationInfo 540 * 541 * @since 20 542 */ 543 typedef struct __TEE_OperationInfo TEE_OperationInfo; 544 545 /** 546 * @brief Defines the key information stored in the <b>OperationInfo</b>. 547 * 548 * @since 20 549 */ 550 typedef struct { 551 /** Key length */ 552 uint32_t keySize; 553 /** Required key usage */ 554 uint32_t requiredKeyUsage; 555 } TEE_OperationInfoKey; 556 557 /** 558 * @brief Defines information about an operation. 559 * 560 * @since 20 561 */ 562 typedef struct { 563 /** Algorithm ID */ 564 uint32_t algorithm; 565 /** Operation type */ 566 uint32_t operationClass; 567 /** Operation mode */ 568 uint32_t mode; 569 /** Digest length */ 570 uint32_t digestLength; 571 /** Maximum key length */ 572 uint32_t maxKeySize; 573 /** Handle state */ 574 uint32_t handleState; 575 /** Operation state */ 576 uint32_t operationState; 577 /** Number of keys */ 578 uint32_t numberOfKeys; 579 /** Key information */ 580 TEE_OperationInfoKey keyInformation[]; 581 } TEE_OperationInfoMultiple; 582 583 /** 584 * @brief Defines the cryptographic operation handle. 585 * 586 * @since 20 587 */ 588 struct __TEE_OperationHandle { 589 /** Algorithm ID */ 590 uint32_t algorithm; 591 /** Operation type */ 592 uint32_t operationClass; 593 /** Operation mode */ 594 uint32_t mode; 595 /** Digest length */ 596 uint32_t digestLength; 597 /** Maximum key length */ 598 uint32_t maxKeySize; 599 /** Key length */ 600 uint32_t keySize; 601 /** Key length */ 602 uint32_t keySize2; 603 /** Required key usage */ 604 uint32_t requiredKeyUsage; 605 /** Handle state */ 606 uint32_t handleState; 607 /** Key */ 608 void *keyValue; 609 /** Key */ 610 void *keyValue2; 611 /** */ 612 void *crypto_ctxt; 613 /** */ 614 void *hmac_rest_ctext; 615 /** iv */ 616 void *IV; 617 /** Public key */ 618 void *publicKey; 619 /** Length of the public key */ 620 uint32_t publicKeyLen; 621 /** Private key */ 622 void *privateKey; 623 /** Length of the private key */ 624 uint32_t privateKeyLen; 625 /** Length of the IV */ 626 uint32_t IVLen; 627 /** TEE_DH_OtherInfo */ 628 TEE_DH_OtherInfo *dh_otherinfo; 629 /** TEE_DH_HASH_Mode */ 630 uint32_t dh_hash_mode; 631 /** TEE_DH_DerivFuncMode */ 632 uint32_t dh_derive_func; 633 /** TEE_DH_OpMode_t */ 634 uint32_t dh_op_mode; 635 void *dh_prime; 636 uint32_t dh_prime_size; 637 /** Operation lock */ 638 pthread_mutex_t operation_lock; 639 /** HAL information */ 640 void *hal_info; 641 }; 642 643 /** 644 * @brief Defines the data used for conversion of integers. 645 * 646 * @since 20 647 */ 648 typedef struct { 649 /** Source */ 650 uint32_t src; 651 /** Destination */ 652 uint32_t dest; 653 } crypto_uint2uint; 654 655 /** 656 * @brief Defines the maximum length of an RSA public key. 657 * 658 * @since 20 659 */ 660 #define RSA_PUBKEY_MAXSIZE sizeof(CRYS_RSAUserPubKey_t) 661 662 /** 663 * @brief Defines the maximum length of an RES private key. 664 * 665 * @since 20 666 */ 667 #define RSA_PRIVKEY_MAXSIZE sizeof(CRYS_RSAUserPrivKey_t) 668 669 /** 670 * @brief Defines a structure to hold the input and output data. 671 * 672 * @since 20 673 */ 674 typedef struct { 675 /** Source data */ 676 void *src_data; 677 /** Length of the source data */ 678 size_t src_len; 679 /** Destination data */ 680 void *dest_data; 681 /** Length of the destination data */ 682 size_t *dest_len; 683 } operation_src_dest; 684 685 /** 686 * @brief Defines the AE initialization data. 687 * 688 * @since 20 689 */ 690 typedef struct { 691 /** nonce */ 692 void *nonce; 693 /** Leng of nonce */ 694 size_t nonce_len; 695 /** Length of the tag */ 696 uint32_t tag_len; 697 /** Length of the additional authenticated data (AAD) */ 698 size_t aad_len; 699 /** Length of the payload */ 700 size_t payload_len; 701 } operation_ae_init; 702 703 /** 704 * @brief Defines the <b>__TEE_OperationHandle</b> struct. 705 * 706 * @see __TEE_OperationHandle 707 * 708 * @since 20 709 */ 710 typedef struct __TEE_OperationHandle TEE_OperationHandleVar; 711 712 /** 713 * @brief Defines the <b>__TEE_ObjectHandle</b> struct. 714 * 715 * @since 20 716 */ 717 typedef struct __TEE_ObjectHandle TEE_ObjectHandleVar; 718 719 /** 720 * @brief Allocates an operation handle. 721 * 722 * @param operation Indicates the pointer to the operation handle. 723 * @param algorithm Indicates the cipher algorithm. 724 * @param mode Indicates the operation mode. 725 * @param maxKeySize Indicates the maximum length of the key. 726 * 727 * @return Returns <b>TEE_SUCCESS</b> if the operation handle is allocated. 728 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if there is no enough memory for this operation. 729 * Returns <b>TEE_ERROR_NOT_SUPPORTED</b> if the specified algorithm is not supported. 730 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 731 * 732 * @since 20 733 */ 734 TEE_Result TEE_AllocateOperation(TEE_OperationHandle *operation, uint32_t algorithm, uint32_t mode, 735 uint32_t maxKeySize); 736 737 /** 738 * @brief Releases an operation handle. 739 * 740 * @param operation Indicates the operation handle to release. 741 * 742 * @since 20 743 */ 744 void TEE_FreeOperation(TEE_OperationHandle operation); 745 746 /** 747 * @brief Obtains operation information. 748 * 749 * @param operation Indicates the operation handle. 750 * @param operationInfo Indicates the pointer to the operation information. 751 * 752 * @since 20 753 */ 754 void TEE_GetOperationInfo(const TEE_OperationHandle operation, TEE_OperationInfo *operationInfo); 755 756 /** 757 * @brief Resets an operation handle. 758 * 759 * @param operation Indicates the operation handle to reset. 760 * 761 * @since 20 762 */ 763 void TEE_ResetOperation(TEE_OperationHandle operation); 764 765 /** 766 * @brief Sets the key for an operation. 767 * 768 * @param operation Indicates the operation handle. 769 * @param key Indicates the key. 770 * 771 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 772 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 773 * Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if there is no enough memory for this operation. 774 * 775 * @since 20 776 */ 777 TEE_Result TEE_SetOperationKey(TEE_OperationHandle operation, const TEE_ObjectHandle key); 778 779 /** 780 * @brief Sets two keys for an operation. 781 * 782 * @param operation Indicates the operation handle. 783 * @param key1 Indicates key 1. 784 * @param key2 Indicates key 2. 785 * 786 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 787 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 788 * 789 * @since 20 790 */ 791 TEE_Result TEE_SetOperationKey2(TEE_OperationHandle operation, const TEE_ObjectHandle key1, 792 const TEE_ObjectHandle key2); 793 794 /** 795 * @brief Copies an operation handle. 796 * 797 * @param dstOperation Indicates the destination operation handle. 798 * @param srcOperation Indicates the source operation handle. 799 * 800 * @since 20 801 */ 802 void TEE_CopyOperation(TEE_OperationHandle dstOperation, const TEE_OperationHandle srcOperation); 803 804 /** 805 * @brief Initializes the context to start a cipher operation. 806 * 807 * @param operation Indicates the operation handle. 808 * @param IV Indicates the pointer to the buffer storing the operation IV. If this parameter is not used, 809 * set it to <b>NULL</b>. 810 * @param IVLen Indicates the length of the IV buffer. 811 * 812 * @since 20 813 */ 814 void TEE_CipherInit(TEE_OperationHandle operation, const void *IV, size_t IVLen); 815 816 /** 817 * @brief Updates the data for a cipher operation. 818 * 819 * @param operation Indicates the operation handle. 820 * @param srcData Indicates the pointer to the source data. 821 * @param srcLen Indicates the length of the source data. 822 * @param destData Indicates the pointer to the destination data. 823 * @param destLen Indicates the pointer to the destination data length. 824 * 825 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 826 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 827 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 828 * 829 * @since 20 830 */ 831 TEE_Result TEE_CipherUpdate(TEE_OperationHandle operation, const void *srcData, size_t srcLen, void *destData, 832 size_t *destLen); 833 834 /** 835 * @brief Finalizes a cipher operation. 836 * 837 * @param operation Indicates the operation handle. 838 * @param srcData Indicates the pointer to the source data. 839 * @param srcLen Indicates the length of the source data. 840 * @param destData Indicates the pointer to the destination data. 841 * @param destLen Indicates the pointer to the destination data length. 842 * 843 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 844 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 845 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 846 * 847 * @since 20 848 */ 849 TEE_Result TEE_CipherDoFinal(TEE_OperationHandle operation, const void *srcData, size_t srcLen, void *destData, 850 size_t *destLen); 851 852 /** 853 * @brief Updates the digest. 854 * 855 * @param operation Indicates the operation handle. 856 * @param chunk Indicates the pointer to the chunk of data to be hashed. 857 * @param chunkSize Indicates the length of the chunk. 858 * 859 * @since 20 860 */ 861 void TEE_DigestUpdate(TEE_OperationHandle operation, const void *chunk, size_t chunkSize); 862 863 /** 864 * @brief Finalizes the message digest operation. 865 * 866 * @param operation Indicates the operation handle. 867 * @param chunk Indicates the pointer to the chunk of data to be hashed. 868 * @param chunkLen Indicates the length of the chunk. 869 * @param hash Indicates the pointer to the buffer storing the message hash. 870 * @param hashLen 871 * 872 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 873 * Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the operationInfo buffer is not large enough to 874 * hold the information obtained. 875 * 876 * @since 20 877 */ 878 TEE_Result TEE_DigestDoFinal(TEE_OperationHandle operation, const void *chunk, size_t chunkLen, void *hash, 879 size_t *hashLen); 880 881 /** 882 * @brief Initializes a MAC operation. 883 * 884 * @param operation Indicates the operation handle. 885 * @param IV Indicates the pointer to the buffer storing the operation IV. If this parameter is not used, 886 * set it to <b>NULL</b>. 887 * @param IVLen Indicates the length of the IV buffer. 888 * 889 * @since 20 890 */ 891 void TEE_MACInit(TEE_OperationHandle operation, void *IV, size_t IVLen); 892 893 /** 894 * @brief Updates the MAC. 895 * 896 * @param operation Indicates the operation handle. 897 * @param chunk Indicates the pointer to the chunk of MAC data. 898 * @param chunkSize Indicates the size of the chunk. 899 * 900 * @since 20 901 */ 902 void TEE_MACUpdate(TEE_OperationHandle operation, const void *chunk, size_t chunkSize); 903 904 /** 905 * @brief MAC Finalizes the MAC operation with a last chunk of message and computes the MAC. 906 * 907 * @param operation Indicates the operation handle. 908 * @param message Indicates the pointer to the buffer containing the last message chunk to MAC. 909 * @param messageLen Indicates the length of the message buffer. 910 * @param mac Indicates the pointer to the buffer storing the computed MAC. 911 * @param macLen Indicates the pointer to the MAC buffer length. 912 * 913 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 914 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 915 * 916 * @since 20 917 */ 918 TEE_Result TEE_MACComputeFinal(TEE_OperationHandle operation, const void *message, size_t messageLen, void *mac, 919 size_t *macLen); 920 921 /** 922 * @brief Finalizes the MAC operation and compares the MAC with the one passed in. 923 * 924 * @param operation Indicates the operation handle. 925 * @param message Indicates the pointer to the buffer containing the last message chunk to MAC. 926 * @param messageLen Indicates the length of the buffer. 927 * @param mac Indicates the pointer to the buffer storing the computed MAC. 928 * @param macLen Indicates the MAC buffer length. 929 * 930 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 931 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 932 * Returns <b>TEE_ERROR_MAC_INVALID</b> if the computed MAC is not the same as that passed in. 933 * 934 * @since 20 935 */ 936 TEE_Result TEE_MACCompareFinal(TEE_OperationHandle operation, const void *message, size_t messageLen, const void *mac, 937 const size_t macLen); 938 939 /** 940 * @brief Derives a key. 941 * 942 * @param operation Indicates the operation handle. 943 * @param params Indicates the pointer to the parameters for this operation. 944 * @param paramCount Indicates the number of parameters. 945 * @param derivedKey Indicates the derived key. 946 * 947 * @since 20 948 */ 949 void TEE_DeriveKey(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, 950 TEE_ObjectHandle derivedKey); 951 952 /** 953 * @brief Generates random data. 954 * 955 * @param randomBuffer Indicates the pointer to the buffer storing the random data generated. 956 * @param randomBufferLen Indicates the length of the buffer storing the random data. 957 * 958 * @since 20 959 */ 960 void TEE_GenerateRandom(void *randomBuffer, size_t randomBufferLen); 961 962 /** 963 * @brief Initializes an AE operation. 964 * 965 * @param operation Indicates the operation handle. 966 * @param nonce Indicates the pointer to the buffer for storing the nonce. 967 * @param nonceLen Indicates the length of the nonce. 968 * @param tagLen Indicates the length of the tag. 969 * @param AADLen Indicates the length of the AAD. 970 * @param payloadLen Indicates the length of the payload. 971 * 972 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 973 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 974 * 975 * @since 20 976 */ 977 TEE_Result TEE_AEInit(TEE_OperationHandle operation, void *nonce, size_t nonceLen, uint32_t tagLen, size_t AADLen, 978 size_t payloadLen); 979 980 /** 981 * @brief Updates the AAD in an AE operation. 982 * 983 * @param operation Indicates the operation handle. 984 * @param AADdata Indicates the pointer to the new AAD. 985 * @param AADdataLen Indicates the length of the new AAD. 986 * 987 * @since 20 988 */ 989 void TEE_AEUpdateAAD(TEE_OperationHandle operation, const void *AADdata, size_t AADdataLen); 990 991 /** 992 * @brief Updates data for an AE operation. 993 * 994 * @param operation Indicates the operation handle. 995 * @param srcData Indicates the pointer to the source data. 996 * @param srcLen Indicates the length of the source data. 997 * @param destData Indicates the pointer to the destination data. 998 * @param destLen Indicates the pointer to the destination data length. 999 * 1000 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1001 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 1002 * 1003 * @since 20 1004 */ 1005 TEE_Result TEE_AEUpdate(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, size_t *destLen); 1006 1007 /** 1008 * @brief Finalizes the AE encryption operation. 1009 * 1010 * @param operation Indicates the operation handle. 1011 * @param srcData Indicates the pointer to the source data. 1012 * @param srcLen Indicates the length of the source data. 1013 * @param destData Indicates the pointer to the destination data. 1014 * @param destLen Indicates the pointer to the destination data length. 1015 * @param tag Indicates the pointer to the buffer storing the computed tag. 1016 * @param tagLen Indicates the pointer to the tag buffer length. 1017 * 1018 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1019 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 1020 * 1021 * @since 20 1022 */ 1023 TEE_Result TEE_AEEncryptFinal(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, 1024 size_t *destLen, void *tag, size_t *tagLen); 1025 1026 /** 1027 * @brief Finalizes an AE decryption operation. 1028 * 1029 * @param operation Indicates the operation handle. 1030 * @param srcData Indicates the pointer to the source data. 1031 * @param srcLen Indicates the length of the source data. 1032 * @param destData Indicates the pointer to the destination data. 1033 * @param destLen Indicates the pointer to the destination data length. 1034 * @param tag Indicates the pointer to the buffer storing the computed tag. 1035 * @param tagLen Indicates the tag buffer length. 1036 * 1037 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1038 * Returns <b>TEE_ERROR_MAC_INVALID</b> if the computed tag does not match the provided tag. 1039 * 1040 * @since 20 1041 */ 1042 TEE_Result TEE_AEDecryptFinal(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, 1043 size_t *destLen, void *tag, size_t tagLen); 1044 1045 /** 1046 * @brief Performs asymmetric encryption. 1047 * 1048 * @param operation Indicates the operation handle. 1049 * @param params Indicates the pointer to the parameters for this operation. 1050 * @param paramCount Indicates the number of parameters. 1051 * @param srcData Indicates the pointer to the source data. 1052 * @param srcLen Indicates the length of the source data. 1053 * @param destData Indicates the pointer to the destination data. 1054 * @param destLen Indicates the pointer to the destination data length. 1055 * 1056 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1057 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 1058 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 1059 * 1060 * @since 20 1061 */ 1062 TEE_Result TEE_AsymmetricEncrypt(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, 1063 void *srcData, size_t srcLen, void *destData, size_t *destLen); 1064 1065 /** 1066 * @brief Performs asymmetric decryption. 1067 * 1068 * @param operation Indicates the operation handle. 1069 * @param params Indicates the pointer to the parameters for this operation. 1070 * @param paramCount Indicates the number of parameters. 1071 * @param srcData Indicates the pointer to the source data. 1072 * @param srcLen Indicates the length of the source data. 1073 * @param destData Indicates the pointer to the destination data. 1074 * @param destLen Indicates the pointer to the destination data length. 1075 * 1076 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1077 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 1078 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 1079 * 1080 * @since 20 1081 */ 1082 TEE_Result TEE_AsymmetricDecrypt(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, 1083 void *srcData, size_t srcLen, void *destData, size_t *destLen); 1084 1085 /** 1086 * @brief Signs a message digest in an asymmetric operation. 1087 * 1088 * @param operation Indicates the operation handle. 1089 * @param params Indicates the pointer to the parameters for this operation. 1090 * @param paramCount Indicates the number of parameters. 1091 * @param digest Indicates the pointer to the message digest. 1092 * @param digestLen Indicates the digest length. 1093 * @param signature Indicates the pointer to the signature. 1094 * @param signatureLen Indicates the pointer to the signature length. 1095 * 1096 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1097 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 1098 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 1099 * 1100 * @since 20 1101 */ 1102 TEE_Result TEE_AsymmetricSignDigest(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, 1103 void *digest, size_t digestLen, void *signature, size_t *signatureLen); 1104 1105 /** 1106 * @brief Verifies a message digest signature in an asymmetric operation. 1107 * 1108 * @param operation Indicates the operation handle. 1109 * @param params Indicates the pointer to the parameters for this operation. 1110 * @param paramCount Indicates the number of parameters. 1111 * @param digest Indicates the pointer to the message digest. 1112 * @param digestLen Indicates the digest length. 1113 * @param signature Indicates the pointer to the signature. 1114 * @param signatureLen Indicates the signature length. 1115 * 1116 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1117 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 1118 * Returns <b>TEE_ERROR_GENERIC</b> if the operation fails due to other errors. 1119 * 1120 * @since 20 1121 */ 1122 TEE_Result TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, 1123 void *digest, size_t digestLen, void *signature, size_t signatureLen); 1124 1125 /** 1126 * @brief Obtains information about the operation involving multiple keys. 1127 * 1128 * @param operation Indicates the operation handle. 1129 * @param operationInfoMultiple Indicates the pointer to the operation information obtained. 1130 * @param operationSize [IN/OUT] Indicates the pointer to the operation information size. 1131 * 1132 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful. 1133 * Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the operation fails due to invalid parameters. 1134 * Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the operationInfo buffer is not large enough to 1135 * hold the information obtained. 1136 * 1137 * @since 20 1138 */ 1139 TEE_Result TEE_GetOperationInfoMultiple(TEE_OperationHandle operation, TEE_OperationInfoMultiple *operationInfoMultiple, 1140 const size_t *operationSize); 1141 1142 /** 1143 * @brief Checks whether the algorithm is supported. 1144 * 1145 * @param algId Indicates the algorithm to check. 1146 * @param element Indicates the cryptographic element. 1147 * 1148 * @return Returns <b>TEE_SUCCESS</b> if the algorithm is supported. 1149 * Returns <b>TEE_ERROR_NOT_SUPPORTED</b> otherwise. 1150 * 1151 * @since 20 1152 */ 1153 TEE_Result TEE_IsAlgorithmSupported(uint32_t algId, uint32_t element); 1154 1155 #ifdef __cplusplus 1156 } 1157 #endif 1158 1159 #endif 1160 /** @} */