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