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