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 #ifndef NATIVE_OH_HUKS_TYPE_H 17 #define NATIVE_OH_HUKS_TYPE_H 18 19 /** 20 * @addtogroup HuksTypeApi 21 * @{ 22 * 23 * @brief Defines the macros, enumerated values, data structures, 24 * and error codes used by OpenHarmony Universal KeyStore (HUKS) APIs. 25 * 26 * @syscap SystemCapability.Security.Huks 27 * @since 9 28 * @version 1.0 29 */ 30 31 /** 32 * @file native_huks_type.h 33 * 34 * @brief Defines the structure and enumeration. 35 * 36 * @kit Universal Keystore Kit 37 * @since 9 38 * @version 1.0 39 */ 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 60 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 * Device password is required but not set. 408 * 409 * @since 11 410 */ 411 OH_HUKS_ERR_CODE_DEVICE_PASSWORD_UNSET = 12000016, 412 }; 413 414 /** 415 * @brief Enumerates the tag types. 416 * @see OH_Huks_Param 417 * 418 * @since 9 419 * @version 1.0 420 */ 421 enum OH_Huks_TagType { 422 /** Invalid tag type. */ 423 OH_HUKS_TAG_TYPE_INVALID = 0 << 28, 424 /** int32_t. */ 425 OH_HUKS_TAG_TYPE_INT = 1 << 28, 426 /** uin32_t. */ 427 OH_HUKS_TAG_TYPE_UINT = 2 << 28, 428 /** uin64_t. */ 429 OH_HUKS_TAG_TYPE_ULONG = 3 << 28, 430 /** Boolean. */ 431 OH_HUKS_TAG_TYPE_BOOL = 4 << 28, 432 /** OH_Huks_Blob. */ 433 OH_HUKS_TAG_TYPE_BYTES = 5 << 28, 434 }; 435 436 /** 437 * @brief Enumerates the user authentication types. 438 * 439 * @since 9 440 * @version 1.0 441 */ 442 enum OH_Huks_UserAuthType { 443 /** Fingerprint authentication. */ 444 OH_HUKS_USER_AUTH_TYPE_FINGERPRINT = 1 << 0, 445 /** Facial authentication. */ 446 OH_HUKS_USER_AUTH_TYPE_FACE = 1 << 1, 447 /** PIN authentication. */ 448 OH_HUKS_USER_AUTH_TYPE_PIN = 1 << 2, 449 }; 450 451 /** 452 * @brief Enumerates the access control types. 453 * 454 * @since 9 455 * @version 1.0 456 */ 457 enum OH_Huks_AuthAccessType { 458 /** The key is invalid after the password is cleared. */ 459 OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD = 1 << 0, 460 /** The key is invalid after a new biometric feature is enrolled. */ 461 OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL = 1 << 1, 462 /** 463 * The key is always valid. 464 * 465 * @since 11 466 */ 467 OH_HUKS_AUTH_ACCESS_ALWAYS_VALID = 1 << 2, 468 }; 469 470 /** 471 * @brief Enumerates key file storage authentication levels. 472 * 473 * @since 11 474 */ 475 enum OH_Huks_AuthStorageLevel { 476 /** 477 * Key file storage security level for device encryption standard. 478 * @since 11 479 */ 480 OH_HUKS_AUTH_STORAGE_LEVEL_DE = 0, 481 /** 482 * Key file storage security level for credential encryption standard. 483 * @since 11 484 */ 485 OH_HUKS_AUTH_STORAGE_LEVEL_CE = 1, 486 /** 487 * Key file storage security level for enhanced credential encryption standard. 488 * @since 11 489 */ 490 OH_HUKS_AUTH_STORAGE_LEVEL_ECE = 2, 491 }; 492 493 /** 494 * @brief Enumerates the types of the challenges generated when a key is used. 495 * @see OH_Huks_ChallengePosition 496 * 497 * @since 9 498 * @version 1.0 499 */ 500 enum OH_Huks_ChallengeType { 501 /** Normal challenge, which is of 32 bytes by default. */ 502 OH_HUKS_CHALLENGE_TYPE_NORMAL = 0, 503 /** Custom challenge, which supports only one authentication for multiple keys. 504 * The valid value of a custom challenge is of 8 bytes. 505 */ 506 OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1, 507 /** Challenge is not required. */ 508 OH_HUKS_CHALLENGE_TYPE_NONE = 2, 509 }; 510 511 /** 512 * @brief Enumerates the positions of the 8-byte valid value in a custom challenge generated. 513 * 514 * @since 9 515 * @version 1.0 516 */ 517 enum OH_Huks_ChallengePosition { 518 /** Bytes 0 to 7. */ 519 OH_HUKS_CHALLENGE_POS_0 = 0, 520 /** Bytes 8 to 15. */ 521 OH_HUKS_CHALLENGE_POS_1, 522 /** Bytes 16 to 23. */ 523 OH_HUKS_CHALLENGE_POS_2, 524 /** Bytes 24 to 31. */ 525 OH_HUKS_CHALLENGE_POS_3, 526 }; 527 528 /** 529 * @brief Enumerates the signature types of the keys generated or imported. 530 * 531 * @since 9 532 * @version 1.0 533 */ 534 enum OH_Huks_SecureSignType { 535 /** 536 * The signature carries authentication information. This field is specified when a key 537 * is generated or imported. When the key is used to sign data, the data will be added with 538 * the authentication information and then be signed. 539 */ 540 OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1, 541 }; 542 543 /** 544 * @brief Enumerates the tag values used in parameter sets. 545 * 546 * @since 9 547 * @version 1.0 548 */ 549 enum OH_Huks_Tag { 550 /** Tags for key parameters. The value range is 1 to 200. */ 551 /** Algorithm. */ 552 OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT | 1, 553 /** Key purpose. */ 554 OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT | 2, 555 /** Key size. */ 556 OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT | 3, 557 /** Digest algorithm. */ 558 OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT | 4, 559 /** Padding algorithm. */ 560 OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT | 5, 561 /** Cipher mode. */ 562 OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT | 6, 563 /** Key type. */ 564 OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT | 7, 565 /** Associated authentication data. */ 566 OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES | 8, 567 /** Field for key encryption and decryption. */ 568 OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES | 9, 569 /** Initialized vector (IV). */ 570 OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES | 10, 571 572 /** Information generated during key derivation. */ 573 OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES | 11, 574 /** Salt value used for key derivation. */ 575 OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES | 12, 576 /** Number of iterations for key derivation. */ 577 OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT | 14, 578 579 /** Type of the generated key. For details, see {@link OH_Huks_KeyGenerateType}. */ 580 OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT | 15, 581 /** Algorithm used in key agreement. */ 582 OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT | 19, 583 /** Alias of the public key used for key agreement. */ 584 OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL | 20, 585 /** Alias of the private key used for key agreement. */ 586 OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 21, 587 /** Public key used for key agreement. */ 588 OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES | 22, 589 /** Alias of the key. */ 590 OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 23, 591 /** Size of the derived key. */ 592 OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT | 24, 593 /** Type of the key to import. For details, see {@link OH_Huks_ImportKeyType}. */ 594 OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT | 25, 595 /** Algorithm suite required for encrypted imports. */ 596 OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT | 26, 597 /** Storage mode of derived or agree keys. For details, see {@link OH_Huks_KeyStorageType}. */ 598 OH_HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT | 29, 599 /** Type of rsa pss salt length. */ 600 OH_HUKS_TAG_RSA_PSS_SALT_LEN_TYPE = OH_HUKS_TAG_TYPE_UINT | 30, 601 602 /** Tags for access control and user authentication. The value range is 301 to 500. */ 603 /** All users in the multi-user scenario. */ 604 OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL | 301, 605 /** Multi-user ID. */ 606 OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT | 302, 607 /** Specifies whether key access control is required. */ 608 OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL | 303, 609 /** User authentication type in key access control. */ 610 OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT | 304, 611 /** Timeout duration for key access. */ 612 OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT | 305, 613 /** Authentication token for the key. */ 614 OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES | 306, 615 /** 616 * Access control type. For details, see {@link OH_Huks_AuthAccessType}. 617 * This parameter must be set together with the user authentication type. 618 */ 619 OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT | 307, 620 /** Signature type for the key to be generated or imported. */ 621 OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT | 308, 622 /** Challenge type. For details, see {@link OH_Huks_ChallengeType}. */ 623 OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT | 309, 624 /** 625 * Position of the 8-byte valid value in a custom challenge. 626 * For details, see {@link OH_Huks_ChallengePosition}. 627 */ 628 OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT | 310, 629 630 /** Purpose of key authentication */ 631 OH_HUKS_TAG_KEY_AUTH_PURPOSE = OH_HUKS_TAG_TYPE_UINT | 311, 632 633 /** 634 * Security level of access control for key file storage, whose optional values are from OH_Huks_AuthStorageLevel. 635 * 636 * @since 11 637 */ 638 OH_HUKS_TAG_AUTH_STORAGE_LEVEL = OH_HUKS_TAG_TYPE_UINT | 316, 639 640 /** Tags for key attestation. The value range is 501 to 600. */ 641 /** Challenge value used in the attestation. */ 642 OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES | 501, 643 /** Application ID used in the attestation. */ 644 OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES | 502, 645 /** Alias of the key. */ 646 OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 511, 647 /** Security level used in the attestation. */ 648 OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES | 514, 649 /** Version information used in the attestation. */ 650 OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES | 515, 651 652 /** 653 * 601 to 1000 are reserved for other tags. 654 * 655 * Extended tags. The value range is 1001 to 9999. 656 */ 657 /** Specifies whether it is a key alias. */ 658 OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL | 1001, 659 /** Key storage mode. For details, see {@link OH_Huks_KeyStorageType}. */ 660 OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT | 1002, 661 /** Specifies whether to allow the key to be wrapped. */ 662 OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL | 1003, 663 /** Key wrap type. */ 664 OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT | 1004, 665 /** Authentication ID. */ 666 OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES | 1005, 667 /** Role of the key. */ 668 OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT | 1006, 669 /** Key flag. For details, see {@link OH_Huks_KeyFlag}. */ 670 OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT | 1007, 671 /** Specifies whether this API is asynchronous. */ 672 OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT | 1008, 673 /** Key domain. */ 674 OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT | 1011, 675 /** 676 * Key access control based on device password setting status. 677 * True means the key can only be generated and used when the password is set. 678 * 679 * @since 11 680 */ 681 OH_HUKS_TAG_IS_DEVICE_PASSWORD_SET = OH_HUKS_TAG_TYPE_BOOL | 1012, 682 683 /** Authenticated Encryption. */ 684 OH_HUKS_TAG_AE_TAG = OH_HUKS_TAG_TYPE_BYTES | 10009, 685 686 /** 687 * 11000 to 12000 are reserved. 688 * 689 * 20001 to N are reserved for other tags. 690 */ 691 /** Symmetric key data. */ 692 OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20001, 693 /** Public key data of the asymmetric key pair. */ 694 OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20002, 695 /** Private key data of the asymmetric key pair. */ 696 OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20003, 697 }; 698 699 /** 700 * @brief Defines the return data, including the result code and message. 701 * 702 * @since 9 703 * @version 1.0 704 */ 705 struct OH_Huks_Result { 706 /** Result code. */ 707 int32_t errorCode; 708 /** Description of the result code. */ 709 const char *errorMsg; 710 /** Other data returned. */ 711 uint8_t *data; 712 }; 713 714 /** 715 * @brief Defines the structure for storing data. 716 * 717 * @since 9 718 * @version 1.0 719 */ 720 struct OH_Huks_Blob { 721 /** Data size. */ 722 uint32_t size; 723 /** Pointer to the memory in which the data is stored. */ 724 uint8_t *data; 725 }; 726 727 /** 728 * @brief Defines the parameter structure in a parameter set. 729 * 730 * @since 9 731 * @version 1.0 732 */ 733 struct OH_Huks_Param { 734 /** Tag value. */ 735 uint32_t tag; 736 737 union { 738 /** Parameter of the Boolean type. */ 739 bool boolParam; 740 /** Parameter of the int32_t type. */ 741 int32_t int32Param; 742 /** Parameter of the uint32_t type. */ 743 uint32_t uint32Param; 744 /** Parameter of the uint64_t type. */ 745 uint64_t uint64Param; 746 /** Parameter of the struct OH_Huks_Blob type. */ 747 struct OH_Huks_Blob blob; 748 }; 749 }; 750 751 /** 752 * @brief Defines the structure of the parameter set. 753 * 754 * @since 9 755 * @version 1.0 756 */ 757 struct OH_Huks_ParamSet { 758 /** Memory size of the parameter set. */ 759 uint32_t paramSetSize; 760 /** Number of parameters in the parameter set. */ 761 uint32_t paramsCnt; 762 /** Parameter array. */ 763 struct OH_Huks_Param params[]; 764 }; 765 766 /** 767 * @brief Defines the structure of the certificate chain. 768 * 769 * @since 9 770 * @version 1.0 771 */ 772 struct OH_Huks_CertChain { 773 /** Pointer to the certificate data. */ 774 struct OH_Huks_Blob *certs; 775 /** Number of certificates. */ 776 uint32_t certsCount; 777 }; 778 779 /** 780 * @brief Defines the key information structure. 781 * 782 * @since 9 783 * @version 1.0 784 */ 785 struct OH_Huks_KeyInfo { 786 /** Alias of the key. */ 787 struct OH_Huks_Blob alias; 788 /** Pointer to the key parameter set. */ 789 struct OH_Huks_ParamSet *paramSet; 790 }; 791 792 /** 793 * @brief Defines the structure of a public key. 794 * 795 * @since 9 796 * @version 1.0 797 */ 798 struct OH_Huks_PubKeyInfo { 799 /** Algorithm of the public key. */ 800 enum OH_Huks_KeyAlg keyAlg; 801 /** Length of the public key. */ 802 uint32_t keySize; 803 /** Length of the n or X value. */ 804 uint32_t nOrXSize; 805 /** Length of the e or Y value. */ 806 uint32_t eOrYSize; 807 /** Placeholder size. */ 808 uint32_t placeHolder; 809 }; 810 811 /** 812 * @brief Defines the structure of an RSA key. 813 * 814 * @since 9 815 * @version 1.0 816 */ 817 struct OH_Huks_KeyMaterialRsa { 818 /** Algorithm of the key. */ 819 enum OH_Huks_KeyAlg keyAlg; 820 /** Length of the key. */ 821 uint32_t keySize; 822 /** Length of the n value. */ 823 uint32_t nSize; 824 /** Length of the e value. */ 825 uint32_t eSize; 826 /** Length of the d value. */ 827 uint32_t dSize; 828 }; 829 830 /** 831 * @brief Defines the structure of an ECC key. 832 * 833 * @since 9 834 * @version 1.0 835 */ 836 struct OH_Huks_KeyMaterialEcc { 837 /** Algorithm of the key. */ 838 enum OH_Huks_KeyAlg keyAlg; 839 /** Length of the key. */ 840 uint32_t keySize; 841 /** Length of the x value. */ 842 uint32_t xSize; 843 /** Length of the y value. */ 844 uint32_t ySize; 845 /** Length of the z value. */ 846 uint32_t zSize; 847 }; 848 849 /** 850 * @brief Defines the structure of a DSA key. 851 * 852 * @since 9 853 * @version 1.0 854 */ 855 struct OH_Huks_KeyMaterialDsa { 856 /** Algorithm of the key. */ 857 enum OH_Huks_KeyAlg keyAlg; 858 /** Length of the key. */ 859 uint32_t keySize; 860 /** Length of the x value. */ 861 uint32_t xSize; 862 /** Length of the y value. */ 863 uint32_t ySize; 864 /** Length of the p value. */ 865 uint32_t pSize; 866 /** Length of the q value. */ 867 uint32_t qSize; 868 /** Length of the g value. */ 869 uint32_t gSize; 870 }; 871 872 /** 873 * @brief Defines the structure of a DH key. 874 * 875 * @since 9 876 * @version 1.0 877 */ 878 struct OH_Huks_KeyMaterialDh { 879 /** Algorithm of the key. */ 880 enum OH_Huks_KeyAlg keyAlg; 881 /** Length of the DH key. */ 882 uint32_t keySize; 883 /** Length of the public key. */ 884 uint32_t pubKeySize; 885 /** Length of the private key. */ 886 uint32_t priKeySize; 887 /** Reserved. */ 888 uint32_t reserved; 889 }; 890 891 /** 892 * @brief Defines the structure of a 25519 key. 893 * 894 * @since 9 895 * @version 1.0 896 */ 897 struct OH_Huks_KeyMaterial25519 { 898 /** Algorithm of the key. */ 899 enum OH_Huks_KeyAlg keyAlg; 900 /** Length of the 25519 key. */ 901 uint32_t keySize; 902 /** Length of the public key. */ 903 uint32_t pubKeySize; 904 /** Length of the private key. */ 905 uint32_t priKeySize; 906 /** Reserved. */ 907 uint32_t reserved; 908 }; 909 910 #ifdef __cplusplus 911 } 912 #endif 913 914 /** @} */ 915 #endif /* NATIVE_OH_HUKS_TYPE_H */ 916