1 /* 2 * Copyright (c) 2022-2023 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 HuksTypeApi 18 * @{ 19 * 20 * @brief Defines the macros, enumerated values, data structures, 21 * and error codes used by OpenHarmony Universal KeyStore (HUKS) APIs. 22 * 23 * @since 9 24 * @version 1.0 25 */ 26 27 /** 28 * @file native_huks_type.h 29 * 30 * @brief Defines the structure and enumeration. 31 * 32 * @library libhuks_ndk.z.so 33 * @syscap SystemCapability.Security.Huks.Core 34 * 35 * @kit UniversalKeystoreKit 36 * @since 9 37 * @version 1.0 38 */ 39 40 #ifndef NATIVE_OH_HUKS_TYPE_H 41 #define NATIVE_OH_HUKS_TYPE_H 42 43 #include <stdbool.h> 44 #include <stdint.h> 45 #include <stdlib.h> 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 #define OH_HUKS_AE_TAG_LEN 16 52 #define OH_HUKS_BITS_PER_BYTE 8 53 #define OH_HUKS_MAX_KEY_SIZE 2048 54 #define OH_HUKS_AE_NONCE_LEN 12 55 #define OH_HUKS_MAX_KEY_ALIAS_LEN 64 56 #define OH_HUKS_MAX_PROCESS_NAME_LEN 50 57 #define OH_HUKS_MAX_RANDOM_LEN 1024 58 #define OH_HUKS_SIGNATURE_MIN_SIZE 64 59 #define OH_HUKS_MAX_OUT_BLOB_SIZE (5 * 1024 * 1024) 60 #define OH_HUKS_WRAPPED_FORMAT_MAX_SIZE (1024 * 1024) 61 #define OH_HUKS_IMPORT_WRAPPED_KEY_TOTAL_BLOBS 10 62 #define TOKEN_CHALLENGE_LEN 32 63 #define SHA256_SIGN_LEN 32 64 #define TOKEN_SIZE 32 65 #define MAX_AUTH_TIMEOUT_SECOND 60 66 #define SECURE_SIGN_VERSION 0x01000001 67 68 /** 69 * @brief Enumerates the key purposes. 70 * 71 * @since 9 72 * @version 1.0 73 */ 74 enum OH_Huks_KeyPurpose { 75 /** Used to encrypt the plaintext. */ 76 OH_HUKS_KEY_PURPOSE_ENCRYPT = 1, 77 /** Used to decrypt the cipher text. */ 78 OH_HUKS_KEY_PURPOSE_DECRYPT = 2, 79 /** Used to sign data. */ 80 OH_HUKS_KEY_PURPOSE_SIGN = 4, 81 /** Used to verify the signature. */ 82 OH_HUKS_KEY_PURPOSE_VERIFY = 8, 83 /** Used to derive a key. */ 84 OH_HUKS_KEY_PURPOSE_DERIVE = 16, 85 /** Used for an encrypted export. */ 86 OH_HUKS_KEY_PURPOSE_WRAP = 32, 87 /** Used for an encrypted import. */ 88 OH_HUKS_KEY_PURPOSE_UNWRAP = 64, 89 /** Used to generate a message authentication code (MAC). */ 90 OH_HUKS_KEY_PURPOSE_MAC = 128, 91 /** Used for key agreement. */ 92 OH_HUKS_KEY_PURPOSE_AGREE = 256, 93 }; 94 95 /** 96 * @brief Enumerates the digest algorithms. 97 * 98 * @since 9 99 * @version 1.0 100 */ 101 enum OH_Huks_KeyDigest { 102 /** No digest algorithm. */ 103 OH_HUKS_DIGEST_NONE = 0, 104 /** MD5. */ 105 OH_HUKS_DIGEST_MD5 = 1, 106 /** SM3. */ 107 OH_HUKS_DIGEST_SM3 = 2, 108 /** SHA-1. */ 109 OH_HUKS_DIGEST_SHA1 = 10, 110 /** SHA-224. */ 111 OH_HUKS_DIGEST_SHA224 = 11, 112 /** SHA-256. */ 113 OH_HUKS_DIGEST_SHA256 = 12, 114 /** SHA-384. */ 115 OH_HUKS_DIGEST_SHA384 = 13, 116 /** SHA-512. */ 117 OH_HUKS_DIGEST_SHA512 = 14, 118 }; 119 120 /** 121 * @brief Enumerates the padding algorithms. 122 * 123 * @since 9 124 * @version 1.0 125 */ 126 enum OH_Huks_KeyPadding { 127 /** No padding algorithm. */ 128 OH_HUKS_PADDING_NONE = 0, 129 /** Optimal Asymmetric Encryption Padding (OAEP). */ 130 OH_HUKS_PADDING_OAEP = 1, 131 /** Probabilistic Signature Scheme (PSS). */ 132 OH_HUKS_PADDING_PSS = 2, 133 /** Public Key Cryptography Standards (PKCS) #1 v1.5. */ 134 OH_HUKS_PADDING_PKCS1_V1_5 = 3, 135 /** PKCS #5. */ 136 OH_HUKS_PADDING_PKCS5 = 4, 137 /** PKCS #7. */ 138 OH_HUKS_PADDING_PKCS7 = 5, 139 /** ISO IEC 9796-2 140 * @since 18 141 */ 142 OH_HUKS_PADDING_ISO_IEC_9796_2 = 6, 143 /** ISO IEC 9797-1 144 * @since 18 145 */ 146 OH_HUKS_PADDING_ISO_IEC_9797_1 = 7, 147 }; 148 149 /** 150 * @brief Enumerates the cipher modes. 151 * 152 * @since 9 153 * @version 1.0 154 */ 155 enum OH_Huks_CipherMode { 156 /** Electronic Code Block (ECB) mode. */ 157 OH_HUKS_MODE_ECB = 1, 158 /** Cipher Block Chaining (CBC) mode. */ 159 OH_HUKS_MODE_CBC = 2, 160 /** Counter (CTR) mode. */ 161 OH_HUKS_MODE_CTR = 3, 162 /** Output Feedback (OFB) mode. */ 163 OH_HUKS_MODE_OFB = 4, 164 /** 165 * Cipher Feedback (CFB) mode. 166 * @since 12 167 */ 168 OH_HUKS_MODE_CFB = 5, 169 /** Counter with CBC-MAC (CCM) mode. */ 170 OH_HUKS_MODE_CCM = 31, 171 /** Galois/Counter (GCM) mode. */ 172 OH_HUKS_MODE_GCM = 32, 173 }; 174 175 /** 176 * @brief Enumerates the key sizes. 177 * 178 * @since 9 179 * @version 1.0 180 */ 181 enum OH_Huks_KeySize { 182 /** Rivest-Shamir-Adleman (RSA) key of 512 bits. */ 183 OH_HUKS_RSA_KEY_SIZE_512 = 512, 184 /** RSA key of 768 bits. */ 185 OH_HUKS_RSA_KEY_SIZE_768 = 768, 186 /** RSA key of 1024 bits. */ 187 OH_HUKS_RSA_KEY_SIZE_1024 = 1024, 188 /** RSA key of 2048 bits. */ 189 OH_HUKS_RSA_KEY_SIZE_2048 = 2048, 190 /** RSA key of 3072 bits. */ 191 OH_HUKS_RSA_KEY_SIZE_3072 = 3072, 192 /** RSA key of 4096 bits. */ 193 OH_HUKS_RSA_KEY_SIZE_4096 = 4096, 194 195 /** Elliptic Curve Cryptography (ECC) key of 224 bits. */ 196 OH_HUKS_ECC_KEY_SIZE_224 = 224, 197 /** ECC key of 256 bits. */ 198 OH_HUKS_ECC_KEY_SIZE_256 = 256, 199 /** ECC key of 384 bits. */ 200 OH_HUKS_ECC_KEY_SIZE_384 = 384, 201 /** ECC key of 521 bits. */ 202 OH_HUKS_ECC_KEY_SIZE_521 = 521, 203 204 /** Advanced Encryption Standard (AES) key of 128 bits. */ 205 OH_HUKS_AES_KEY_SIZE_128 = 128, 206 /** AES key of 192 bits. */ 207 OH_HUKS_AES_KEY_SIZE_192 = 192, 208 /** AES key of 256 bits. */ 209 OH_HUKS_AES_KEY_SIZE_256 = 256, 210 /** AES key of 512 bits. */ 211 OH_HUKS_AES_KEY_SIZE_512 = 512, 212 213 /** Curve25519 key of 256 bits. */ 214 OH_HUKS_CURVE25519_KEY_SIZE_256 = 256, 215 216 /** Diffie-Hellman (DH) key of 2048 bits. */ 217 OH_HUKS_DH_KEY_SIZE_2048 = 2048, 218 /** DH key of 3072 bits. */ 219 OH_HUKS_DH_KEY_SIZE_3072 = 3072, 220 /** DH key of 4096 bits. */ 221 OH_HUKS_DH_KEY_SIZE_4096 = 4096, 222 223 /** ShangMi2 (SM2) key of 256 bits. */ 224 OH_HUKS_SM2_KEY_SIZE_256 = 256, 225 /** ShangMi4 (SM4) key of 128 bits. */ 226 OH_HUKS_SM4_KEY_SIZE_128 = 128, 227 228 /** DES key of 64 bits. 229 * @since 18 230 */ 231 OH_HUKS_DES_KEY_SIZE_64 = 64, 232 /** 3DES key of 128 bits. 233 * @since 18 234 */ 235 OH_HUKS_3DES_KEY_SIZE_128 = 128, 236 /** 3DES key of 192 bits. 237 * @since 18 238 */ 239 OH_HUKS_3DES_KEY_SIZE_192 = 192, 240 }; 241 242 /** 243 * @brief Enumerates the key algorithms. 244 * 245 * @since 9 246 * @version 1.0 247 */ 248 enum OH_Huks_KeyAlg { 249 /** RSA. */ 250 OH_HUKS_ALG_RSA = 1, 251 /** ECC. */ 252 OH_HUKS_ALG_ECC = 2, 253 /** DSA. */ 254 OH_HUKS_ALG_DSA = 3, 255 256 /** AES. */ 257 OH_HUKS_ALG_AES = 20, 258 /** HMAC. */ 259 OH_HUKS_ALG_HMAC = 50, 260 /** HKDF. */ 261 OH_HUKS_ALG_HKDF = 51, 262 /** PBKDF2. */ 263 OH_HUKS_ALG_PBKDF2 = 52, 264 265 /** ECDH. */ 266 OH_HUKS_ALG_ECDH = 100, 267 /** X25519. */ 268 OH_HUKS_ALG_X25519 = 101, 269 /** Ed25519. */ 270 OH_HUKS_ALG_ED25519 = 102, 271 /** DH. */ 272 OH_HUKS_ALG_DH = 103, 273 274 /** SM2. */ 275 OH_HUKS_ALG_SM2 = 150, 276 /** SM3. */ 277 OH_HUKS_ALG_SM3 = 151, 278 /** SM4. */ 279 OH_HUKS_ALG_SM4 = 152, 280 281 /** DES. 282 * @since 18 283 */ 284 OH_HUKS_ALG_DES = 160, 285 /** 3DES. 286 * @since 18 287 */ 288 OH_HUKS_ALG_3DES = 161, 289 /** CMAC. 290 * @since 18 291 */ 292 OH_HUKS_ALG_CMAC = 162, 293 }; 294 295 /** 296 * @brief Enumerates the algorithm suites required for ciphertext imports. 297 * 298 * @since 9 299 * @version 1.0 300 */ 301 enum OH_Huks_AlgSuite { 302 /** Key material format (Length-Value format), X25519 key agreement, and AES-256-GCM encryption and decryption. 303 * | x25519_plain_pubkey_length (4 Byte) | x25519_plain_pubkey | agreekey_aad_length (4 Byte) | agreekey_aad 304 * | agreekey_nonce_length (4 Byte) | agreekey_nonce | 305 * | agreekey_aead_tag_len (4 Byte) | agreekey_aead_tag | 306 * | kek_enc_data_length (4 Byte) | kek_enc_data | kek_aad_length (4 Byte) | kek_aad 307 * | kek_nonce_length (4 Byte) | kek_nonce | kek_aead_tag_len (4 Byte) | kek_aead_tag 308 * | key_material_size_len (4 Byte) | key_material_size | key_mat_enc_length (4 Byte) | key_mat_enc_data 309 */ 310 OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING = 1, 311 312 /** Key material format (Length-Value format), ECDH-p256 key agreement, and AES-256-GCM encryption and decryption. 313 * | ECC_plain_pubkey_length (4 Byte) | ECC_plain_pubkey | agreekey_aad_length (4 Byte) | agreekey_aad 314 * | agreekey_nonce_length (4 Byte) | agreekey_nonce | 315 * | agreekey_aead_tag_len (4 Byte) | agreekey_aead_tag | 316 * | kek_enc_data_length (4 Byte) | kek_enc_data | kek_aad_length (4 Byte) | kek_aad 317 * | kek_nonce_length (4 Byte) | kek_nonce | kek_aead_tag_len (4 Byte) | kek_aead_tag 318 * | key_material_size_len (4 Byte) | key_material_size | key_mat_enc_length (4 Byte) | key_mat_enc_data 319 */ 320 OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING = 2, 321 }; 322 323 /** 324 * @brief Enumerates the key generation types. 325 * 326 * @since 9 327 * @version 1.0 328 */ 329 enum OH_Huks_KeyGenerateType { 330 /** Key generated by default. */ 331 OH_HUKS_KEY_GENERATE_TYPE_DEFAULT = 0, 332 /** Derived key. */ 333 OH_HUKS_KEY_GENERATE_TYPE_DERIVE = 1, 334 /** Key obtained by key agreement. */ 335 OH_HUKS_KEY_GENERATE_TYPE_AGREE = 2, 336 }; 337 338 /** 339 * @brief Enumerates the key generation modes. 340 * 341 * @since 9 342 * @version 1.0 343 */ 344 enum OH_Huks_KeyFlag { 345 /** Import a public key using an API. */ 346 OH_HUKS_KEY_FLAG_IMPORT_KEY = 1, 347 /** Generate a key by using an API. */ 348 OH_HUKS_KEY_FLAG_GENERATE_KEY = 2, 349 /** Generate a key by using a key agreement API. */ 350 OH_HUKS_KEY_FLAG_AGREE_KEY = 3, 351 /** Derive a key by using an API. */ 352 OH_HUKS_KEY_FLAG_DERIVE_KEY = 4, 353 }; 354 355 /** 356 * @brief Enumerates the key storage modes. 357 * 358 * @since 9 359 * @version 1.0 360 */ 361 enum OH_Huks_KeyStorageType { 362 /** The key is managed locally. */ 363 OH_HUKS_STORAGE_TEMP = 0, 364 /** The key is managed by the HUKS service. */ 365 OH_HUKS_STORAGE_PERSISTENT = 1, 366 /** The key is only used in huks. */ 367 OH_HUKS_STORAGE_ONLY_USED_IN_HUKS = 2, 368 /** The key can be allowed to export. */ 369 OH_HUKS_STORAGE_KEY_EXPORT_ALLOWED = 3, 370 }; 371 372 /** 373 * @brief Enumerates the types of keys to import. By default, 374 * a public key is imported. This field is not required when a symmetric key is imported. 375 * 376 * @since 9 377 * @version 1.0 378 */ 379 enum OH_Huks_ImportKeyType { 380 /** Public key. */ 381 OH_HUKS_KEY_TYPE_PUBLIC_KEY = 0, 382 /** Private key. */ 383 OH_HUKS_KEY_TYPE_PRIVATE_KEY = 1, 384 /** Public and private key pair. */ 385 OH_HUKS_KEY_TYPE_KEY_PAIR = 2, 386 }; 387 388 /** 389 * @brief Enumerates the salt_len types to set when PSS padding is used in RSA signing or signature 390 * verification. 391 * 392 * @since 10 393 * @version 1.0 394 */ 395 enum OH_Huks_RsaPssSaltLenType { 396 /** Salt length matches digest. */ 397 OH_HUKS_RSA_PSS_SALT_LEN_DIGEST = 0, 398 /** Set salt length to maximum possible, default type. */ 399 OH_HUKS_RSA_PSS_SALT_LEN_MAX = 1, 400 }; 401 402 /** 403 * @brief Enumerates the error codes. 404 * 405 * @since 9 406 * @version 1.0 407 */ 408 enum OH_Huks_ErrCode { 409 /** The operation is successful. */ 410 OH_HUKS_SUCCESS = 0, 411 /** Permission verification failed. */ 412 OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201, 413 /** Invalid parameters are detected. */ 414 OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401, 415 /** The API is not supported. */ 416 OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801, 417 418 /** The feature is not supported. */ 419 OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001, 420 /** Key algorithm parameters are missing. */ 421 OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002, 422 /** Invalid key algorithm parameters are detected. */ 423 OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003, 424 /** Failed to operate the file. */ 425 OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004, 426 /** The process communication failed. */ 427 OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005, 428 /** Failed to operate the algorithm library. */ 429 OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006, 430 /** Failed to access the key because the key has expired. */ 431 OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007, 432 /** Failed to access the key because the authentication has failed. */ 433 OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008, 434 /** Key access timed out. */ 435 OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009, 436 /** The number of key operation sessions has reached the limit. */ 437 OH_HUKS_ERR_CODE_SESSION_LIMIT = 12000010, 438 /** The entity does not exist. */ 439 OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011, 440 /** Internal error. */ 441 OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012, 442 /** The authentication credential does not exist. */ 443 OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013, 444 /** The memory is not sufficient. */ 445 OH_HUKS_ERR_CODE_INSUFFICIENT_MEMORY = 12000014, 446 /** Failed to call service. */ 447 OH_HUKS_ERR_CODE_CALL_SERVICE_FAILED = 12000015, 448 /** 449 * A device password is required but not set. 450 * 451 * @since 11 452 */ 453 OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET = 12000016, 454 /** 455 * The key with same alias is already exist. 456 * 457 * @since 20 458 */ 459 OH_HUKS_ERR_CODE_KEY_ALREADY_EXIST = 12000017, 460 /** 461 * The input parameter is invalid.. 462 * 463 * @since 20 464 */ 465 OH_HUKS_ERR_CODE_INVALID_ARGUMENT = 12000018 466 }; 467 468 /** 469 * @brief Enumerates the tag types. 470 * @see OH_Huks_Param 471 * 472 * @since 9 473 * @version 1.0 474 */ 475 enum OH_Huks_TagType { 476 /** Invalid tag type. */ 477 OH_HUKS_TAG_TYPE_INVALID = 0 << 28, 478 /** int32_t. */ 479 OH_HUKS_TAG_TYPE_INT = 1 << 28, 480 /** uin32_t. */ 481 OH_HUKS_TAG_TYPE_UINT = 2 << 28, 482 /** uin64_t. */ 483 OH_HUKS_TAG_TYPE_ULONG = 3 << 28, 484 /** Boolean. */ 485 OH_HUKS_TAG_TYPE_BOOL = 4 << 28, 486 /** OH_Huks_Blob. */ 487 OH_HUKS_TAG_TYPE_BYTES = 5 << 28, 488 }; 489 490 /** 491 * @brief Enumerates the user authentication types. 492 * 493 * @since 9 494 * @version 1.0 495 */ 496 enum OH_Huks_UserAuthType { 497 /** Fingerprint authentication. */ 498 OH_HUKS_USER_AUTH_TYPE_FINGERPRINT = 1 << 0, 499 /** Facial authentication. */ 500 OH_HUKS_USER_AUTH_TYPE_FACE = 1 << 1, 501 /** PIN authentication. */ 502 OH_HUKS_USER_AUTH_TYPE_PIN = 1 << 2, 503 /** 504 * Enum for tui pin auth type. 505 * 506 * @since 20 507 */ 508 OH_HUKS_USER_AUTH_TYPE_TUI_PIN = 1 << 5, 509 }; 510 511 /** 512 * @brief Enumerates the access control types. 513 * 514 * @since 9 515 * @version 1.0 516 */ 517 enum OH_Huks_AuthAccessType { 518 /** The key is invalid after the password is cleared. */ 519 OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD = 1 << 0, 520 /** The key is invalid after a new biometric feature is enrolled. */ 521 OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL = 1 << 1, 522 /** 523 * The key is always valid. 524 * 525 * @since 11 526 */ 527 OH_HUKS_AUTH_ACCESS_ALWAYS_VALID = 1 << 2, 528 }; 529 530 /** 531 * @brief Enumerates key file storage authentication levels. 532 * 533 * @since 11 534 */ 535 enum OH_Huks_AuthStorageLevel { 536 /** 537 * Key file storage security level for device encryption standard. 538 * @since 11 539 */ 540 OH_HUKS_AUTH_STORAGE_LEVEL_DE = 0, 541 /** 542 * Key file storage security level for credential encryption standard. 543 * @since 11 544 */ 545 OH_HUKS_AUTH_STORAGE_LEVEL_CE = 1, 546 /** 547 * Key file storage security level for enhanced credential encryption standard. 548 * @since 11 549 */ 550 OH_HUKS_AUTH_STORAGE_LEVEL_ECE = 2, 551 }; 552 553 /** 554 * @brief Enumerates the user authentication mode. 555 * 556 * @since 12 557 * @version 1.0 558 */ 559 enum OH_Huks_UserAuthMode { 560 /** 561 * Auth mode for local scenarios. 562 * @since 12 563 */ 564 OH_HUKS_USER_AUTH_MODE_LOCAL = 0, 565 /** 566 * Auth mode for co-auth scenarios. 567 * @since 12 568 */ 569 OH_HUKS_USER_AUTH_MODE_COAUTH = 1, 570 }; 571 572 /** 573 * @brief Enumerates the types of the challenges generated when a key is used. 574 * @see OH_Huks_ChallengePosition 575 * 576 * @since 9 577 * @version 1.0 578 */ 579 enum OH_Huks_ChallengeType { 580 /** Normal challenge, which is of 32 bytes by default. */ 581 OH_HUKS_CHALLENGE_TYPE_NORMAL = 0, 582 /** Custom challenge, which supports only one authentication for multiple keys. 583 * The valid value of a custom challenge is of 8 bytes. 584 */ 585 OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1, 586 /** Challenge is not required. */ 587 OH_HUKS_CHALLENGE_TYPE_NONE = 2, 588 }; 589 590 /** 591 * @brief Enumerates the positions of the 8-byte valid value in a custom challenge generated. 592 * 593 * @since 9 594 * @version 1.0 595 */ 596 enum OH_Huks_ChallengePosition { 597 /** Bytes 0 to 7. */ 598 OH_HUKS_CHALLENGE_POS_0 = 0, 599 /** Bytes 8 to 15. */ 600 OH_HUKS_CHALLENGE_POS_1, 601 /** Bytes 16 to 23. */ 602 OH_HUKS_CHALLENGE_POS_2, 603 /** Bytes 24 to 31. */ 604 OH_HUKS_CHALLENGE_POS_3, 605 }; 606 607 /** 608 * @brief Enumerates the signature types of the keys generated or imported. 609 * 610 * @since 9 611 * @version 1.0 612 */ 613 enum OH_Huks_SecureSignType { 614 /** 615 * The signature carries authentication information. This field is specified when a key 616 * is generated or imported. When the key is used to sign data, the data will be added with 617 * the authentication information and then be signed. 618 * NOTICE: 619 * The carried authentication information contains personal identification details. Developers are required 620 * to clearly state the purpose of use, retention policy, and destruction method of such personal information in 621 * their privacy statement. 622 */ 623 OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1, 624 }; 625 626 /** 627 * Enum for key wrap type. 628 * 629 * @since 20 630 */ 631 enum OH_Huks_KeyWrapType { 632 /** 633 * The hardware unique key wrap type. 634 * 635 * @since 20 636 */ 637 OH_HUKS_KEY_WRAP_TYPE_HUK_BASED = 2, 638 }; 639 640 /** 641 * @brief Enumerates the tag values used in parameter sets. 642 * 643 * @since 9 644 * @version 1.0 645 */ 646 enum OH_Huks_Tag { 647 /** Tags for key parameters. The value range is 1 to 200. */ 648 /** Algorithm. */ 649 OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT | 1, 650 /** Key purpose. */ 651 OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT | 2, 652 /** Key size. */ 653 OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT | 3, 654 /** Digest algorithm. */ 655 OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT | 4, 656 /** Padding algorithm. */ 657 OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT | 5, 658 /** Cipher mode. */ 659 OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT | 6, 660 /** Key type. */ 661 OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT | 7, 662 /** Associated authentication data. */ 663 OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES | 8, 664 /** Field for key encryption and decryption. */ 665 OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES | 9, 666 /** Initialized vector (IV). */ 667 OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES | 10, 668 669 /** Information generated during key derivation. */ 670 OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES | 11, 671 /** Salt value used for key derivation. */ 672 OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES | 12, 673 /** Number of iterations for key derivation. */ 674 OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT | 14, 675 676 /** Type of the generated key. For details, see {@link OH_Huks_KeyGenerateType}. */ 677 OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT | 15, 678 /** Algorithm used in key agreement. */ 679 OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT | 19, 680 /** Alias of the public key used for key agreement. */ 681 OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL | 20, 682 /** Alias of the private key used for key agreement. */ 683 OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 21, 684 /** Public key used for key agreement. */ 685 OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES | 22, 686 /** Alias of the key. */ 687 OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 23, 688 /** Size of the derived key. */ 689 OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT | 24, 690 /** Type of the key to import. For details, see {@link OH_Huks_ImportKeyType}. */ 691 OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT | 25, 692 /** Algorithm suite required for encrypted imports. */ 693 OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT | 26, 694 /** Storage mode of derived or agree keys. For details, see {@link OH_Huks_KeyStorageType}. */ 695 OH_HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT | 29, 696 /** Type of rsa pss salt length. */ 697 OH_HUKS_TAG_RSA_PSS_SALT_LEN_TYPE = OH_HUKS_TAG_TYPE_UINT | 30, 698 699 /** Tags for access control and user authentication. The value range is 301 to 500. */ 700 /** All users in the multi-user scenario. */ 701 OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL | 301, 702 /** Multi-user ID. */ 703 OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT | 302, 704 /** Specifies whether key access control is required. */ 705 OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL | 303, 706 /** User authentication type in key access control. */ 707 OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT | 304, 708 /** Timeout duration for key access. */ 709 OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT | 305, 710 /** Authentication token for the key. */ 711 OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES | 306, 712 /** 713 * Access control type. For details, see {@link OH_Huks_AuthAccessType}. 714 * This parameter must be set together with the user authentication type. 715 */ 716 OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT | 307, 717 /** Signature type for the key to be generated or imported. */ 718 OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT | 308, 719 /** Challenge type. For details, see {@link OH_Huks_ChallengeType}. */ 720 OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT | 309, 721 /** 722 * Position of the 8-byte valid value in a custom challenge. 723 * For details, see {@link OH_Huks_ChallengePosition}. 724 */ 725 OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT | 310, 726 727 /** Purpose of key authentication */ 728 OH_HUKS_TAG_KEY_AUTH_PURPOSE = OH_HUKS_TAG_TYPE_UINT | 311, 729 730 /** 731 * Security level of access control for key file storage, whose optional values are from OH_Huks_AuthStorageLevel. 732 * 733 * @since 11 734 */ 735 OH_HUKS_TAG_AUTH_STORAGE_LEVEL = OH_HUKS_TAG_TYPE_UINT | 316, 736 737 /** 738 * Authentication mode of the user authtoken，whose optional values are from enum HuksUserAuthMode. 739 * 740 * @since 12 741 */ 742 OH_HUKS_TAG_USER_AUTH_MODE = OH_HUKS_TAG_TYPE_UINT | 319, 743 744 /** Tags for key attestation. The value range is 501 to 600. */ 745 /** Challenge value used in the attestation. */ 746 OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES | 501, 747 /** Application ID used in the attestation. */ 748 OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES | 502, 749 /** Alias of the key. */ 750 OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 511, 751 /** Security level used in the attestation. */ 752 OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES | 514, 753 /** Version information used in the attestation. */ 754 OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES | 515, 755 /** 756 * @brief The tag indicates whether to overwrite the key with same alias 757 * 758 * @since 20 759 */ 760 OH_HUKS_TAG_KEY_OVERRIDE = OH_HUKS_TAG_TYPE_BOOL | 520, 761 /** 762 * 601 to 1000 are reserved for other tags. 763 * 764 * Extended tags. The value range is 1001 to 9999. 765 */ 766 /** Specifies whether it is a key alias. */ 767 OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL | 1001, 768 /** Key storage mode. For details, see {@link OH_Huks_KeyStorageType}. */ 769 OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT | 1002, 770 /** Specifies whether to allow the key to be wrapped. */ 771 OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL | 1003, 772 /** Key wrap type. */ 773 OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT | 1004, 774 /** Authentication ID. */ 775 OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES | 1005, 776 /** Role of the key. */ 777 OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT | 1006, 778 /** Key flag. For details, see {@link OH_Huks_KeyFlag}. */ 779 OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT | 1007, 780 /** Specifies whether this API is asynchronous. */ 781 OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT | 1008, 782 /** Key domain. */ 783 OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT | 1011, 784 /** 785 * Key access control based on device password setting status. 786 * True means the key can only be generated and used when the password is set. 787 * 788 * @since 11 789 */ 790 OH_HUKS_TAG_IS_DEVICE_PASSWORD_SET = OH_HUKS_TAG_TYPE_BOOL | 1012, 791 792 /** Authenticated Encryption. */ 793 OH_HUKS_TAG_AE_TAG = OH_HUKS_TAG_TYPE_BYTES | 10009, 794 795 /** 796 * 11000 to 12000 are reserved. 797 * 798 * 20001 to N are reserved for other tags. 799 */ 800 /** Symmetric key data. */ 801 OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20001, 802 /** Public key data of the asymmetric key pair. */ 803 OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20002, 804 /** Private key data of the asymmetric key pair. */ 805 OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20003, 806 }; 807 808 /** 809 * @brief Defines the return data, including the result code and message. 810 * 811 * @since 9 812 * @version 1.0 813 */ 814 struct OH_Huks_Result { 815 /** Result code. */ 816 int32_t errorCode; 817 /** Description of the result code. */ 818 const char *errorMsg; 819 /** Other data returned. */ 820 uint8_t *data; 821 }; 822 823 /** 824 * @brief Defines the structure for storing data. 825 * 826 * @since 9 827 * @version 1.0 828 */ 829 struct OH_Huks_Blob { 830 /** Data size. */ 831 uint32_t size; 832 /** Pointer to the memory in which the data is stored. */ 833 uint8_t *data; 834 }; 835 836 /** 837 * @brief Defines the parameter structure in a parameter set. 838 * 839 * @since 9 840 * @version 1.0 841 */ 842 struct OH_Huks_Param { 843 /** Tag value. */ 844 uint32_t tag; 845 846 union { 847 /** Parameter of the Boolean type. */ 848 bool boolParam; 849 /** Parameter of the int32_t type. */ 850 int32_t int32Param; 851 /** Parameter of the uint32_t type. */ 852 uint32_t uint32Param; 853 /** Parameter of the uint64_t type. */ 854 uint64_t uint64Param; 855 /** Parameter of the struct OH_Huks_Blob type. */ 856 struct OH_Huks_Blob blob; 857 }; 858 }; 859 860 /** 861 * @brief Defines the structure of the parameter set. 862 * 863 * @since 9 864 * @version 1.0 865 */ 866 struct OH_Huks_ParamSet { 867 /** Memory size of the parameter set. */ 868 uint32_t paramSetSize; 869 /** Number of parameters in the parameter set. */ 870 uint32_t paramsCnt; 871 /** Parameter array. */ 872 struct OH_Huks_Param params[]; 873 }; 874 875 /** 876 * @brief Defines the structure of the certificate chain. 877 * 878 * @since 9 879 * @version 1.0 880 */ 881 struct OH_Huks_CertChain { 882 /** Pointer to the certificate data. */ 883 struct OH_Huks_Blob *certs; 884 /** Number of certificates. */ 885 uint32_t certsCount; 886 }; 887 888 /** 889 * @brief Defines the key information structure. 890 * 891 * @since 9 892 * @version 1.0 893 */ 894 struct OH_Huks_KeyInfo { 895 /** Alias of the key. */ 896 struct OH_Huks_Blob alias; 897 /** Pointer to the key parameter set. */ 898 struct OH_Huks_ParamSet *paramSet; 899 }; 900 901 /** 902 * @brief Defines the structure of a public key. 903 * 904 * @since 9 905 * @version 1.0 906 */ 907 struct OH_Huks_PubKeyInfo { 908 /** Algorithm of the public key. */ 909 enum OH_Huks_KeyAlg keyAlg; 910 /** Length of the public key. */ 911 uint32_t keySize; 912 /** Length of the n or X value. */ 913 uint32_t nOrXSize; 914 /** Length of the e or Y value. */ 915 uint32_t eOrYSize; 916 /** Placeholder size. */ 917 uint32_t placeHolder; 918 }; 919 920 /** 921 * @brief Defines the structure of an RSA key. 922 * 923 * @since 9 924 * @version 1.0 925 */ 926 struct OH_Huks_KeyMaterialRsa { 927 /** Algorithm of the key. */ 928 enum OH_Huks_KeyAlg keyAlg; 929 /** Length of the key. */ 930 uint32_t keySize; 931 /** Length of the n value. */ 932 uint32_t nSize; 933 /** Length of the e value. */ 934 uint32_t eSize; 935 /** Length of the d value. */ 936 uint32_t dSize; 937 }; 938 939 /** 940 * @brief Defines the structure of an ECC key. 941 * 942 * @since 9 943 * @version 1.0 944 */ 945 struct OH_Huks_KeyMaterialEcc { 946 /** Algorithm of the key. */ 947 enum OH_Huks_KeyAlg keyAlg; 948 /** Length of the key. */ 949 uint32_t keySize; 950 /** Length of the x value. */ 951 uint32_t xSize; 952 /** Length of the y value. */ 953 uint32_t ySize; 954 /** Length of the z value. */ 955 uint32_t zSize; 956 }; 957 958 /** 959 * @brief Defines the structure of a DSA key. 960 * 961 * @since 9 962 * @version 1.0 963 */ 964 struct OH_Huks_KeyMaterialDsa { 965 /** Algorithm of the key. */ 966 enum OH_Huks_KeyAlg keyAlg; 967 /** Length of the key. */ 968 uint32_t keySize; 969 /** Length of the x value. */ 970 uint32_t xSize; 971 /** Length of the y value. */ 972 uint32_t ySize; 973 /** Length of the p value. */ 974 uint32_t pSize; 975 /** Length of the q value. */ 976 uint32_t qSize; 977 /** Length of the g value. */ 978 uint32_t gSize; 979 }; 980 981 /** 982 * @brief Defines the structure of a DH key. 983 * 984 * @since 9 985 * @version 1.0 986 */ 987 struct OH_Huks_KeyMaterialDh { 988 /** Algorithm of the key. */ 989 enum OH_Huks_KeyAlg keyAlg; 990 /** Length of the DH key. */ 991 uint32_t keySize; 992 /** Length of the public key. */ 993 uint32_t pubKeySize; 994 /** Length of the private key. */ 995 uint32_t priKeySize; 996 /** Reserved. */ 997 uint32_t reserved; 998 }; 999 1000 /** 1001 * @brief Defines the structure of a 25519 key. 1002 * 1003 * @since 9 1004 * @version 1.0 1005 */ 1006 struct OH_Huks_KeyMaterial25519 { 1007 /** Algorithm of the key. */ 1008 enum OH_Huks_KeyAlg keyAlg; 1009 /** Length of the 25519 key. */ 1010 uint32_t keySize; 1011 /** Length of the public key. */ 1012 uint32_t pubKeySize; 1013 /** Length of the private key. */ 1014 uint32_t priKeySize; 1015 /** Reserved. */ 1016 uint32_t reserved; 1017 }; 1018 1019 /** 1020 * @brief Defines the structure of the alias set. 1021 * 1022 * @since 20 1023 * @version 1.0 1024 */ 1025 struct OH_Huks_KeyAliasSet { 1026 /** Number of aliases. */ 1027 uint32_t aliasesCnt; 1028 /** Aliases array. */ 1029 struct OH_Huks_Blob *aliases; 1030 }; 1031 1032 #ifdef __cplusplus 1033 } 1034 #endif 1035 1036 /** @} */ 1037 #endif /* NATIVE_OH_HUKS_TYPE_H */ 1038