Key Import Overview and Algorithm Specifications
You can import an externally generated key (for example, a key generated after key agreement or generated by a server) into HUKS for management. Once a key is imported into HUKS, the plaintext can be accessed only in a secure environment in its lifecycle.
A key can be imported in plaintext or in secure mode.
NOTE
Using an existing key alias as the alias of the key imported will overwrite the existing key.
The Group Key feature is supported since API version 23.
Plaintext Import
Importing a key in plaintext may expose the plaintext to a non-secure environment. This import mode applies to mini-system devices or security-insensitive services.
-
Plaintext import is recommended to import the public key of an asymmetric key pair.
-
It is not recommended to import symmetric keys or asymmetric key pairs.
NOTE
The mini-system devices support plaintext import but not secure import.
Secure Import
In this mode, the key to be imported is encrypted (wrapped) and then imported to HUKS through an end-to-end encrypted transmission channel established between the service and HUKS. This mode applies to security-sensitive services due to higher security than plaintext import. However, it involves more complex key material and operations.
- Encrypted import is recommended to import symmetric keys or asymmetric key pairs.
The following figure illustrates the development sequence of secure import.
During the secure import process, the following HUKS capabilities are called in sequence:
- Generate an asymmetric key pair and export the public key for key agreement between devices.
- Generate a symmetric key to encrypt the key to be imported.
- Use the symmetric key to encrypt the key to be imported to generate the key ciphertext.
- Import a wrapped key.
- Delete a key.
The public key plaintext material returned by the key export API is encapsulated in X.509 format. The key material in the key import API must be encapsulated in the LengthData-Data format, for example, [(Lengthpart1Datapart1)... (LengthpartnDatapartn)].
NOTE
- The secure import supports key agreement algorithms ECDH and X25519. The generated Shared_Key uses the AES-GCM algorithm to encrypt Caller_Kek. For details about the cipher suites, see HuksUnwrapSuite.
- The X.509 format is not supported for secure import.
- The mini-system devices support plaintext import but not secure import.
Key Material Format for Secure Import
| Content | Length |
|---|---|
| Service public key Caller_Pk length (LCaller_Pk) | 4 bytes |
| Service public key Caller_Pk | LCaller_Pk bytes |
| Shared_Key AAD2 length (LAAD2) | 4 bytes |
| Shared_Key AAD2 | LAAD2 bytes |
| Shared_Key NONCE2 length (LNONCE2) | 4 bytes |
| Shared_Key NONCE2 | LNONCE2 bytes |
| Shared_Key TAG2 length (LTAG2) | 4 bytes |
| Shared_Key TAG2 | LTAG2 bytes |
| Caller_Kek_enc length (LCaller_Kek_enc) | 4 bytes |
| Caller_Kek ciphertext Caller_Kek_enc | LCaller_Kek_enc bytes |
| Caller_Kek AAD3 length (LAAD3) | 4 bytes |
| Caller_Kek AAD3 | LAAD3 bytes |
| Caller_Kek NONCE3 length (LNONCE3) | 4 bytes |
| Caller_Kek NONCE3 | LNONCE3 bytes |
| Caller_Kek TAG3 length (LTAG3) | 4 bytes |
| Caller_Kek TAG3 | LTAG3 bytes |
| To_Import_Key_size length (LTo_Import_Key_size) | 4 bytes |
| Key plaintext material length To_Import_Key_size | LTo_Import_Key_size bytes |
| To_Import_Key_enc length (LTo_Import_Key_enc) | 4 bytes |
| To_Import_Key ciphertext To_Import_Key_enc | LTo_Import_Key_enc bytes |
Digital Envelope Import
The digital envelope feature is supported since API version 23.
This feature allows you to import the key to HUKS in digital envelope format, ensuring secure key import and preventing key leakage during transmission for security-sensitive services.
This feature is recommended to import symmetric keys or asymmetric key pairs.
The following figure shows the development sequence of digital envelope import.
According to the workflow, the HUKS capability needs to be invoked when the digital envelope is imported.
- Generate an SM4 key to encrypt the key to be imported.
- Use the generated SM4 key to encrypt the plaintext of the key to be imported in ECB and NoPadding mode. If an asymmetric key is imported, only the private key needs to be encrypted.
- Export the SM2 public key of the peer end to encrypt the generated SM4 key.
- Use the SM2 public key exported from the peer end, use the NoPadding mode, and specify SM3 as the digest algorithm to encrypt the SM4 key generated on the local end.
- Import a wrapped key.
The public key material returned by the key export API is encapsulated in X.509 format. The key material returned by the API for importing encrypted keys is encapsulated in LengthData-Data format, for example, [(LengthEncSm4DataEncSm4)(LengthEncImpKeyDataEncImpKey)].
NOTE
Only standard devices support digital envelope import.
Supported Algorithms
The following table lists the supported key import specifications.
The key management service specifications include mandatory specifications and optional specifications. Mandatory specifications are algorithm specifications that must be supported. Optional specifications can be used based on actual situation. Before using the optional specifications, refer to the documents provided by the vendor to ensure that the specifications are supported.
You are advised to use mandatory specifications in your development for compatibility purposes.
NOTE
When an RSA key is imported, the public key must be greater than or equal to 65537.
Digital envelope does not support the DSA algorithm, X25519 key, and Ed25519 key. When a digital envelope key is imported, the public key is entered in this tag as a raw key.
If the peer device is not an OpenHarmony device and does not support the key management service, the following requirements must be met when constructing digital envelope data:
The SM2 encryption result is combined in the C1C3C2 format, where C1x and C1y each have 32 bytes.
The SM2 encryption result is in ASN.1 format, and bigint is stored in big-endian mode.
Specifications for standard devices
| Algorithm | Supported Key Length (Bit) | API Version | Mandatory |
|---|---|---|---|
| AES | 128, 192, 256 | 8+ | Yes |
| RSA | 512, 768, 1024 | 8+ | No |
| RSA | 2048, 3072, 4096 | 8+ | Yes |
| RSA | An integer multiple of 8, ranging from 1024 to 2048 (inclusive) | 18+ | Yes |
| HMAC | An integer multiple of 8, ranging from 8 to 1024 (inclusive) | 8+ | Yes |
| ECC | 224 | 8+ | No |
| ECC | 256, 384, 521 | 8+ | Yes |
| ED25519 | 256 | 8+ | Yes |
| X25519 | 256 | 8+ | Yes |
| DSA | An integer multiple of 8, ranging from 512 to 1024 (inclusive) | 8+ | No |
| DH | 2048 | 8+ | Yes |
| DH | 3072, 4096 | 8+ | No |
| SM2 | 256 | 9+ | Yes |
| SM4 | 128 | 9+ | Yes |
| DES | 64 | 18+ | Yes |
| 3DES | 128, 192 | 18+ | Yes |
| ML-DSA | Security parameter set: 44, 65, and 87 | 26.0.0+ | Yes |
Specifications for mini-system devices
Before implementing the specifications for mini-system devices, determine whether your device supports the related specifications.
| Algorithm | Supported Key Length (Bit) | API Version |
|---|---|---|
| AES | 128, 192, 256 | 12+ |
| DES | 64 | 12+ |
| 3DES | 128, 192 | 12+ |
| RSA | An integer multiple of 8, ranging from 1024 to 2048 (inclusive) | 12+ |
| HMAC | An integer multiple of 8, ranging from 8 to 1024 (inclusive) | 12+ |
| CMAC | 128 | 12+ |
Key Import Formats
HUKS supports various types of keys in different formats. The following table lists the key types and key material formats supported by HUKS.
| Key Type | Algorithm | Import Format |
|---|---|---|
| Symmetric key | - | Key in bytes |
| Asymmetric key pair | - | Key pair material format |
| Public key of an asymmetric key pair | Ed25519, X25519 | Key in bytes. For details, see Importing the Public Key of an X25519 Key Pair. |
| Public key of an asymmetric key pair | RSA, ECC, ECDH, DSA, DH, SM2, ML-DSA | DER format defined in X.509 |