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