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