1 /* 2 * Copyright (c) 2022-2024 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 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 }; 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 user authentication mode. 495 * @since 12 496 * @version 1.0 497 */ 498 enum OH_Huks_UserAuthMode { 499 /** 500 * Local authentication. 501 * @since 12 502 */ 503 OH_HUKS_USER_AUTH_MODE_LOCAL = 0, 504 /** 505 * Remote collaborative authentication. 506 * @since 12 507 */ 508 OH_HUKS_USER_AUTH_MODE_COAUTH = 1, 509 }; 510 511 /** 512 * @brief Enumerates the types of the challenges generated when a key is used. 513 * @see OH_Huks_ChallengePosition 514 * 515 * @since 9 516 * @version 1.0 517 */ 518 enum OH_Huks_ChallengeType { 519 /** Normal challenge, which is of 32 bytes by default. */ 520 OH_HUKS_CHALLENGE_TYPE_NORMAL = 0, 521 /** Custom challenge, which supports only one authentication for multiple keys. 522 * The valid value of a custom challenge is of 8 bytes. 523 */ 524 OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1, 525 /** Challenge is not required. */ 526 OH_HUKS_CHALLENGE_TYPE_NONE = 2, 527 }; 528 529 /** 530 * @brief Enumerates the positions of the 8-byte valid value in a custom challenge generated. 531 * 532 * @since 9 533 * @version 1.0 534 */ 535 enum OH_Huks_ChallengePosition { 536 /** Bytes 0 to 7. */ 537 OH_HUKS_CHALLENGE_POS_0 = 0, 538 /** Bytes 8 to 15. */ 539 OH_HUKS_CHALLENGE_POS_1, 540 /** Bytes 16 to 23. */ 541 OH_HUKS_CHALLENGE_POS_2, 542 /** Bytes 24 to 31. */ 543 OH_HUKS_CHALLENGE_POS_3, 544 }; 545 546 /** 547 * @brief Enumerates the signature types of the keys generated or imported. 548 * 549 * @since 9 550 * @version 1.0 551 */ 552 enum OH_Huks_SecureSignType { 553 /** 554 * The signature carries authentication information. This field is specified when a key 555 * is generated or imported. When the key is used to sign data, the data will be added with 556 * the authentication information and then be signed. 557 */ 558 OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1, 559 }; 560 561 /** 562 * @brief Enumerates the tag values used in parameter sets. 563 * 564 * @since 9 565 * @version 1.0 566 */ 567 enum OH_Huks_Tag { 568 /** Tags for key parameters. The value range is 1 to 200. */ 569 /** Algorithm. */ 570 OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT | 1, 571 /** Key purpose. */ 572 OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT | 2, 573 /** Key size. */ 574 OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT | 3, 575 /** Digest algorithm. */ 576 OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT | 4, 577 /** Padding algorithm. */ 578 OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT | 5, 579 /** Cipher mode. */ 580 OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT | 6, 581 /** Key type. */ 582 OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT | 7, 583 /** Associated authentication data. */ 584 OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES | 8, 585 /** Field for key encryption and decryption. */ 586 OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES | 9, 587 /** Initialized vector (IV). */ 588 OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES | 10, 589 590 /** Information generated during key derivation. */ 591 OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES | 11, 592 /** Salt value used for key derivation. */ 593 OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES | 12, 594 /** Number of iterations for key derivation. */ 595 OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT | 14, 596 597 /** Type of the generated key. For details, see {@link OH_Huks_KeyGenerateType}. */ 598 OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT | 15, 599 /** Algorithm used in key agreement. */ 600 OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT | 19, 601 /** Alias of the public key used for key agreement. */ 602 OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL | 20, 603 /** Alias of the private key used for key agreement. */ 604 OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 21, 605 /** Public key used for key agreement. */ 606 OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES | 22, 607 /** Alias of the key. */ 608 OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 23, 609 /** Size of the derived key. */ 610 OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT | 24, 611 /** Type of the key to import. For details, see {@link OH_Huks_ImportKeyType}. */ 612 OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT | 25, 613 /** Algorithm suite required for encrypted imports. */ 614 OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT | 26, 615 /** Storage mode of derived or agree keys. For details, see {@link OH_Huks_KeyStorageType}. */ 616 OH_HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT | 29, 617 /** Type of rsa pss salt length. */ 618 OH_HUKS_TAG_RSA_PSS_SALT_LEN_TYPE = OH_HUKS_TAG_TYPE_UINT | 30, 619 620 /** Tags for access control and user authentication. The value range is 301 to 500. */ 621 /** All users in the multi-user scenario. */ 622 OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL | 301, 623 /** Multi-user ID. */ 624 OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT | 302, 625 /** Specifies whether key access control is required. */ 626 OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL | 303, 627 /** User authentication type in key access control. */ 628 OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT | 304, 629 /** Timeout duration for key access. */ 630 OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT | 305, 631 /** Authentication token for the key. */ 632 OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES | 306, 633 /** 634 * Access control type. For details, see {@link OH_Huks_AuthAccessType}. 635 * This parameter must be set together with the user authentication type. 636 */ 637 OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT | 307, 638 /** Signature type for the key to be generated or imported. */ 639 OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT | 308, 640 /** Challenge type. For details, see {@link OH_Huks_ChallengeType}. */ 641 OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT | 309, 642 /** 643 * Position of the 8-byte valid value in a custom challenge. 644 * For details, see {@link OH_Huks_ChallengePosition}. 645 */ 646 OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT | 310, 647 648 /** Purpose of key authentication */ 649 OH_HUKS_TAG_KEY_AUTH_PURPOSE = OH_HUKS_TAG_TYPE_UINT | 311, 650 651 /** 652 * Security level of access control for key file storage, whose optional values are from OH_Huks_AuthStorageLevel. 653 * 654 * @since 11 655 */ 656 OH_HUKS_TAG_AUTH_STORAGE_LEVEL = OH_HUKS_TAG_TYPE_UINT | 316, 657 658 /** 659 * Authentication mode of the user authtoken, whose optional values are from enum HuksUserAuthMode. 660 * 661 * @since 12 662 */ 663 OH_HUKS_TAG_USER_AUTH_MODE = OH_HUKS_TAG_TYPE_UINT | 319, 664 665 /** Tags for key attestation. The value range is 501 to 600. */ 666 /** Challenge value used in the attestation. */ 667 OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES | 501, 668 /** Application ID used in the attestation. */ 669 OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES | 502, 670 /** Alias of the key. */ 671 OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES | 511, 672 /** Security level used in the attestation. */ 673 OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES | 514, 674 /** Version information used in the attestation. */ 675 OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES | 515, 676 677 /** 678 * 601 to 1000 are reserved for other tags. 679 * 680 * Extended tags. The value range is 1001 to 9999. 681 */ 682 /** Specifies whether it is a key alias. */ 683 OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL | 1001, 684 /** Key storage mode. For details, see {@link OH_Huks_KeyStorageType}. */ 685 OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT | 1002, 686 /** Specifies whether to allow the key to be wrapped. */ 687 OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL | 1003, 688 /** Key wrap type. */ 689 OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT | 1004, 690 /** Authentication ID. */ 691 OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES | 1005, 692 /** Role of the key. */ 693 OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT | 1006, 694 /** Key flag. For details, see {@link OH_Huks_KeyFlag}. */ 695 OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT | 1007, 696 /** Specifies whether this API is asynchronous. */ 697 OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT | 1008, 698 /** Key domain. */ 699 OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT | 1011, 700 /** 701 * Key access control based on device password setting status. 702 * True means the key can only be generated and used when the password is set. 703 * 704 * @since 11 705 */ 706 OH_HUKS_TAG_IS_DEVICE_PASSWORD_SET = OH_HUKS_TAG_TYPE_BOOL | 1012, 707 708 /** Authenticated Encryption. */ 709 OH_HUKS_TAG_AE_TAG = OH_HUKS_TAG_TYPE_BYTES | 10009, 710 711 /** 712 * 11000 to 12000 are reserved. 713 * 714 * 20001 to N are reserved for other tags. 715 */ 716 /** Symmetric key data. */ 717 OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20001, 718 /** Public key data of the asymmetric key pair. */ 719 OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20002, 720 /** Private key data of the asymmetric key pair. */ 721 OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES | 20003, 722 }; 723 724 /** 725 * @brief Defines the return data, including the result code and message. 726 * 727 * @since 9 728 * @version 1.0 729 */ 730 struct OH_Huks_Result { 731 /** Result code. */ 732 int32_t errorCode; 733 /** Description of the result code. */ 734 const char *errorMsg; 735 /** Other data returned. */ 736 uint8_t *data; 737 }; 738 739 /** 740 * @brief Defines the structure for storing data. 741 * 742 * @since 9 743 * @version 1.0 744 */ 745 struct OH_Huks_Blob { 746 /** Data size. */ 747 uint32_t size; 748 /** Pointer to the memory in which the data is stored. */ 749 uint8_t *data; 750 }; 751 752 /** 753 * @brief Defines the parameter structure in a parameter set. 754 * 755 * @since 9 756 * @version 1.0 757 */ 758 struct OH_Huks_Param { 759 /** Tag value. */ 760 uint32_t tag; 761 762 union { 763 /** Parameter of the Boolean type. */ 764 bool boolParam; 765 /** Parameter of the int32_t type. */ 766 int32_t int32Param; 767 /** Parameter of the uint32_t type. */ 768 uint32_t uint32Param; 769 /** Parameter of the uint64_t type. */ 770 uint64_t uint64Param; 771 /** Parameter of the struct OH_Huks_Blob type. */ 772 struct OH_Huks_Blob blob; 773 }; 774 }; 775 776 /** 777 * @brief Defines the structure of the parameter set. 778 * 779 * @since 9 780 * @version 1.0 781 */ 782 struct OH_Huks_ParamSet { 783 /** Memory size of the parameter set. */ 784 uint32_t paramSetSize; 785 /** Number of parameters in the parameter set. */ 786 uint32_t paramsCnt; 787 /** Parameter array. */ 788 struct OH_Huks_Param params[]; 789 }; 790 791 /** 792 * @brief Defines the structure of the certificate chain. 793 * 794 * @since 9 795 * @version 1.0 796 */ 797 struct OH_Huks_CertChain { 798 /** Pointer to the certificate data. */ 799 struct OH_Huks_Blob *certs; 800 /** Number of certificates. */ 801 uint32_t certsCount; 802 }; 803 804 /** 805 * @brief Defines the key information structure. 806 * 807 * @since 9 808 * @version 1.0 809 */ 810 struct OH_Huks_KeyInfo { 811 /** Alias of the key. */ 812 struct OH_Huks_Blob alias; 813 /** Pointer to the key parameter set. */ 814 struct OH_Huks_ParamSet *paramSet; 815 }; 816 817 /** 818 * @brief Defines the structure of a public key. 819 * 820 * @since 9 821 * @version 1.0 822 */ 823 struct OH_Huks_PubKeyInfo { 824 /** Algorithm of the public key. */ 825 enum OH_Huks_KeyAlg keyAlg; 826 /** Length of the public key. */ 827 uint32_t keySize; 828 /** Length of the n or X value. */ 829 uint32_t nOrXSize; 830 /** Length of the e or Y value. */ 831 uint32_t eOrYSize; 832 /** Placeholder size. */ 833 uint32_t placeHolder; 834 }; 835 836 /** 837 * @brief Defines the structure of an RSA key. 838 * 839 * @since 9 840 * @version 1.0 841 */ 842 struct OH_Huks_KeyMaterialRsa { 843 /** Algorithm of the key. */ 844 enum OH_Huks_KeyAlg keyAlg; 845 /** Length of the key. */ 846 uint32_t keySize; 847 /** Length of the n value. */ 848 uint32_t nSize; 849 /** Length of the e value. */ 850 uint32_t eSize; 851 /** Length of the d value. */ 852 uint32_t dSize; 853 }; 854 855 /** 856 * @brief Defines the structure of an ECC key. 857 * 858 * @since 9 859 * @version 1.0 860 */ 861 struct OH_Huks_KeyMaterialEcc { 862 /** Algorithm of the key. */ 863 enum OH_Huks_KeyAlg keyAlg; 864 /** Length of the key. */ 865 uint32_t keySize; 866 /** Length of the x value. */ 867 uint32_t xSize; 868 /** Length of the y value. */ 869 uint32_t ySize; 870 /** Length of the z value. */ 871 uint32_t zSize; 872 }; 873 874 /** 875 * @brief Defines the structure of a DSA key. 876 * 877 * @since 9 878 * @version 1.0 879 */ 880 struct OH_Huks_KeyMaterialDsa { 881 /** Algorithm of the key. */ 882 enum OH_Huks_KeyAlg keyAlg; 883 /** Length of the key. */ 884 uint32_t keySize; 885 /** Length of the x value. */ 886 uint32_t xSize; 887 /** Length of the y value. */ 888 uint32_t ySize; 889 /** Length of the p value. */ 890 uint32_t pSize; 891 /** Length of the q value. */ 892 uint32_t qSize; 893 /** Length of the g value. */ 894 uint32_t gSize; 895 }; 896 897 /** 898 * @brief Defines the structure of a DH key. 899 * 900 * @since 9 901 * @version 1.0 902 */ 903 struct OH_Huks_KeyMaterialDh { 904 /** Algorithm of the key. */ 905 enum OH_Huks_KeyAlg keyAlg; 906 /** Length of the DH key. */ 907 uint32_t keySize; 908 /** Length of the public key. */ 909 uint32_t pubKeySize; 910 /** Length of the private key. */ 911 uint32_t priKeySize; 912 /** Reserved. */ 913 uint32_t reserved; 914 }; 915 916 /** 917 * @brief Defines the structure of a 25519 key. 918 * 919 * @since 9 920 * @version 1.0 921 */ 922 struct OH_Huks_KeyMaterial25519 { 923 /** Algorithm of the key. */ 924 enum OH_Huks_KeyAlg keyAlg; 925 /** Length of the 25519 key. */ 926 uint32_t keySize; 927 /** Length of the public key. */ 928 uint32_t pubKeySize; 929 /** Length of the private key. */ 930 uint32_t priKeySize; 931 /** Reserved. */ 932 uint32_t reserved; 933 }; 934 935 /** 936 * @brief Defines the structure of the alias set. 937 * 938 * @since 12 939 * @version 1.0 940 */ 941 struct OH_Huks_KeyAliasSet { 942 /** Number of aliases. */ 943 uint32_t aliasesCnt; 944 /** Aliases array. */ 945 struct OH_Huks_Blob *aliases; 946 }; 947 948 #ifdef __cplusplus 949 } 950 #endif 951 952 /** @} */ 953 #endif /* NATIVE_OH_HUKS_TYPE_H */ 954