1# Key Import Overview and Algorithm Specifications 2 3<!--Kit: Universal Keystore Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @wutiantian-gitee--> 6<!--Designer: @HighLowWorld--> 7<!--Tester: @wxy1234564846--> 8<!--Adviser: @zengyawen--> 9 10You 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. This ensures that no one can obtain the plaintext of the key. 11 12A key can be imported in plaintext or in encrypted (wrapped) mode. 13> **NOTE** 14> Using an existing key alias as the alias of the key imported will overwrite the existing key. 15 16## Plaintext Import 17 18Importing a key in plaintext may expose the plaintext to a non-secure environment. This import mode applies to <!--RP2-->mini-system devices<!--RP2End--> or security-insensitive services. 19 20- Plaintext import is recommended to import the public key of an asymmetric key pair. 21 22- It is not recommended to import symmetric keys or asymmetric key pairs. 23 > **NOTE** 24 > <!--RP2-->The mini-system devices<!--RP2End--> support plaintext import but not encrypted import. 25 26## Encrypted Import 27 28In 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. 29 30- Encrypted import is recommended to import symmetric keys or asymmetric key pairs. 31 32The following figure illustrates the development sequence of encrypted import. 33 34 35 36During the encrypted import process, the following HUKS capabilities are called in sequence: 37* Generate an asymmetric key pair and export the public key for key agreement between devices. 38* Generate a symmetric key to encrypt the key to be imported. 39* Use the symmetric key to encrypt the key to be imported to generate the key ciphertext. 40* Import a wrapped key. 41* Delete a key. 42 43The [public key plaintext material returned by the key export API is encapsulated in X.509 format](huks-concepts.md#public-key-material-format). The key material in the key import API must be encapsulated in the **Length<sub>Data</sub>-Data** format, for example, [(Length<sub>part1</sub>Data<sub>part1</sub>)... (Length<sub>partn</sub>Data<sub>partn</sub>)]. 44 45> **NOTE**<br> 46> 1. The encrypted 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](../../reference/apis-universal-keystore-kit/js-apis-huks.md#huksunwrapsuite9). 47> 2. The X.509 format is not supported for encrypted import. 48> 3. <!--RP2-->The mini-system devices<!--RP2End--> support plaintext import but not encrypted import. 49 50### Key Material Format for Encrypted Import 51 52| Content| Length| 53| -------- | -------- | 54| Service public key **Caller_Pk** length (L<sub>Caller_Pk</sub>)| 4 bytes| 55| Service public key **Caller_Pk**| L<sub>Caller_Pk</sub> bytes| 56| Shared_Key **AAD2** length (L<sub>AAD2</sub>)| 4 bytes| 57| Shared_Key **AAD2**| L<sub>AAD2</sub> bytes| 58| Shared_Key **Nonce2** length (L<sub>Nonce2</sub>)| 4 bytes| 59| Shared_Key **Nonce2**| L<sub>Nonce2</sub> bytes| 60| Shared_Key **TAG2** length (L<sub>TAG2</sub>)| 4 bytes| 61| Shared_Key **TAG2**| L<sub>TAG2</sub> bytes| 62| **Caller_Kek_enc** length (L<sub>Caller_Kek_enc</sub>)| 4 bytes| 63| Caller_Kek ciphertext **Caller_Kek_enc**| L<sub>Caller_Kek_enc</sub> bytes| 64| Caller_Kek **AAD3** length (L<sub>AAD3</sub>)| 4 bytes| 65| Caller_Kek **AAD3**| L<sub>AAD3</sub> bytes| 66| Caller_Kek **Nonce3** length (L<sub>Nonce3</sub>)| 4 bytes| 67| Caller_Kek **Nonce3**| L<sub>Nonce3</sub> bytes| 68| Caller_Kek **TAG3** length (L<sub>TAG3</sub>)| 4 bytes| 69| Caller_Kek **TAG3**| L<sub>TAG3</sub> bytes| 70| **To_Import_Key_size** length (L<sub>To_Import_Key_size</sub>)| 4 bytes| 71| Key plaintext material length **To_Import_Key_size**| L<sub>To_Import_Key_size</sub> bytes| 72| **To_Import_Key_enc** length (L<sub>To_Import_Key_enc</sub>)| 4 bytes| 73| To_Import_Key ciphertext **To_Import_Key_enc**| L<sub>To_Import_Key_enc</sub> bytes| 74 75## Supported Algorithms 76 77The following table lists the supported key import specifications. 78<!--Del--> 79The 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. 80 81**You are advised to use mandatory specifications in your development for compatibility purposes.** 82<!--DelEnd--> 83 84> **NOTE**<br> 85> When an RSA key is imported, the public key must be greater than or equal to 65537. 86 87**Specifications****<!--RP1--> for standard devices<!--RP1End-->** 88 89| Algorithm| Supported Key Length (Bit)| API Version| <!--DelCol4-->Mandatory| 90| -------- | -------- | -------- | -------- | 91| AES | 128, 192, 256| 8+ | Yes| 92| <!--DelRow-->RSA | 512, 768, 1024| 8+ | No| 93| RSA | 2048, 3072, 4096| 8+ | Yes| 94| RSA | An integer multiple of 8, ranging from 1024 to 2048 (inclusive)| 18+ | Yes| 95| HMAC | An integer multiple of 8, ranging from 8 to 1024 (inclusive)| 8+ | Yes| 96| <!--DelRow-->ECC | 224 | 8+ | No| 97| ECC | 256, 384, 521| 8+ | Yes| 98| ED25519 | 256 | 8+ | Yes| 99| X25519 | 256 | 8+ | Yes| 100| <!--DelRow-->DSA | An integer multiple of 8, ranging from 512 to 1024 (inclusive) | 8+ | No| 101| DH | 2048 | 8+ | Yes| 102| <!--DelRow-->DH | 3072, 4096| 8+ | No| 103| SM2 | 256 | 9+ | Yes| 104| SM4 | 128 | 9+ | Yes| 105| DES | 64 | 18+ | Yes| 106| 3DES | 128, 192| 18+ | Yes| 107 108**Specifications****<!--RP2--> for mini-system devices<!--RP2End-->** 109 110<!--Del--> 111Before implementing the specifications for mini-system devices, determine whether your device supports the related specifications. 112<!--DelEnd--> 113 114| Algorithm| Supported Key Length (Bit)| API Version| 115| -------- | -------- | -------- | 116| AES | 128, 192, 256| 12+ | 117| DES | 64 | 12+ | 118| 3DES | 128, 192| 12+ | 119| RSA | An integer multiple of 8, ranging from 1024 to 2048 (inclusive)| 12+ | 120| HMAC | An integer multiple of 8, ranging from 8 to 1024 (inclusive)| 12+ | 121| CMAC | 128 | 12+ | 122 123## Key Import Formats 124HUKS supports various types of keys in different formats. The following table lists the key types and key material formats supported by HUKS. 125| Key Type| Algorithm| Import Format| 126| -------- | -------- | -------- | 127| Symmetric key| - | Key in bytes| 128| Asymmetric key pair| - | [Key pair material format](huks-concepts.md#key-pair-material-format)| 129| Public key of an asymmetric key pair| Ed25519, X25519| Key in bytes. For details, see [Importing the Public Key of an X25519 Key Pair](huks-import-key-in-plaintext-arkts.md#importing-the-public-key-of-an-x25519-key-pair).| 130| Public key of an asymmetric key pair| RSA, ECC, ECDH, DSA, DH, SM2| DER format defined in X.509| 131
