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