| AES/CBC/NoPadding<br>AES/ECB/NoPadding<br>AES/CTR/NoPadding<br>AES/GCM/NoPadding<br>AES/CBC/PKCS7<br>AES/ECB/PKCS7 | 8+ | The initialization vector (IV) is mandatory in CBC, ECB, or CTR mode.<br>The **Nonce**, **AAD**, and **AEAD** parameters are mandatory in GCM mode. |
| HKDF/SHA256<br>HKDF/SHA384<br>HKDF/SHA512 | 8+ | Algorithm: AES, HMAC, and SM4<br>Length: 256, 384, 512 | The derived key can be stored in the HUKS or directly returned in plaintext.|
| PBKDF2/SHA256<br>PBKDF2/SHA384<br>PBKDF2/SHA512 | 8+ | Algorithm: AES, HMAC, and SM4<br>Length: 256, 384, 512 | The derived key can be stored in the HUKS or directly returned in plaintext.|
| RSA | 9+ | Only the keys using the PSS padding are supported. |
| ECC | 9+ | |
| X25519 | 9+ | |
## Key Material Formats
HUKS defines a set of formats for the material of key pairs, public keys, and private keys of different cipher algorithms.
### Key Pair Material
Key pair material = Key pair material header + Original key pair material
The following uses the RSA key as an example. The application needs to apply for a Uint8Array and assign the variables to the corresponding positions based on the memory structure of the RSA key pair material.
**Figure 1** Memory structure of the SRSA key material
The key algorithm is a value of [HuksKeyAlg](../reference/apis/js-apis-huks.md#hukskeyalg).
-**RSA Key Pair Material Format**
| Key Algorithm| Key Size| Modulus n Length L<sub>n</sub>| Public Key Exponent e Length L<sub>e</sub> | Private Key Exponent d Length L<sub>d</sub>| n | e | d |
| Key Algorithm| Key Size| Private Key x Length L<sub>x</sub>| Public Key y Length L<sub>y</sub>| Prime p Length L<sub>p</sub>| Prime Factor q Length L<sub>q</sub>| g length L<sub>g</sub>| x | y | p | q | g |
The private key material is in the same format as the key pair material. When the private key material is encapsulated, the public key length in the header of the key pair material is set to 0 and original key pair material and the private key material are combined.
Private key material = Header of the key pair material + Original private key material
The following uses the RSA private key material as an example:
OpenHarmony Universal KeyStore (HUKS) provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. HUKS also provides APIs for applications to import or generate keys.
OpenHarmony Universal KeyStore (HUKS) provides lifecycle key management capabilities, including key generation, storage, use, and destruction, and provides attestation for the keys stored in the HUKS.
The HUKS provides secure, lifecycle management of keys based on system security capabilities for services. With the HUKS, services do not need to implement key management.
-[Supported Algorithm Types and Parameter Combinations](huks-appendix.md#supported-algorithm-types-and-parameter-combinations)
-[Key Material Formats](huks-appendix.md#key-material-formats)
## Basic Concepts
- HUKS provides key management functions, including encryption and decryption, signing and signature verification, key agreement and derivation, and Hash-based Message Authentication Code (HMAC) calculation.
- HUKS supports the following algorithms: AES and RSA in encryption and decryption, RSA, ECC, DSA, and ED25519 in signing and signature verification, PBKDF2 in key derivation, and DH, ECDH, and X25519 in key agreement.
- HUKS uses the OpenSSL and Mbed TLS algorithm libraries.
Before using the HUKS for development, you are advised to understand the following basic concepts:
- HUKS Core
HUKS Core is a core component that implements functions, including cryptographic calculation of keys, encryption and decryption of plaintext keys, and key access control. Generally, it runs in a secure environment (such as the TEE or security chip) of the device to ensure that the keys in plaintext are always in the HUKS Core.
- Key session
A key session holds information about the key operation date, key information, and access control attributes when a key is used. You need to pass in a key alias to create a session for the key. The HUKS generates a globally unique handle for each session. A general key operation involves creating a session, passing in data and parameters, and finalizing the session (or aborting the session).
## Working Principles
HUKS manages keys through the following APIs in an Init-Update-Finish model:
-**InitSession**: reads the key, creates a session ID, and returns the session ID to the caller.
The security design of the HUKS includes the following:
- Always keep keys in a secure environment.
-**UpdateSession**: updates data by segment based on the session ID obtained by **InitSession()**.
In the lifecycle of a key, the plaintext will never be exposed outside the HUKS Core. For the devices with a Trusted Execution Environment (TEE) or secure chipset, the HUKS Core runs in the TEE or secure chipset. This prevents the key plaintext from being disclosed even if the Rich Execution Environment (REE) is cracked.
- Encrypt keys for storage.
-**FinishSession**: processes all the data transferred to HUKS and then releases resources.
The service keys are encrypted based on the device root key. Some keys can be protected by passwords if the devices support this feature.
- Apply strict access control over keys.
> **NOTICE**<br>
> **AbortSession()** must be called to terminate the use of the key when an error occurs in any of **InitSession()**, **UpdateSession()**, and **FinishSession()**.
Only authorized services can access keys. For security-sensitive services, user identity authentication can be enabled for key access.
- Provide key attestation.
The HUKS provides attestation for hardware-backed key storage. It proves that the key has not been tampered with, is stored in the hardware-backed HUKS Core, and has correct key attributes.
A key session is the basis for key operations in the HUKS. It initializes key information and caches the service data. Cryptographic operations on data and encryption and decryption are performed in the HUKS Core for security purposes.
**Figure 1** HUKS working mechanism
## Constraints
N/A
- Alias-based access
The key material stored in the HUKS can be accessed by alias only. The key alias must be unique for an application. Otherwise, the key with the same alias will be replaced. The length of the key alias cannot exceed 64 bytes.
- Data segment size
All data is transmitted to the HUKS through the IPC channel. Due to the limitation of the IPC buffer size, data greater than 100 KB must be sliced before transmission, and the data segment cannot exceed 100 KB.
- Mandatory parameters
The cipher algorithm, key size, and purpose must be specified when a key is generated or imported. Other parameters (such as the working mode, padding mode, and hash algorithm) are optional. When a key is used, all parameters related to the cipher algorithm must be specified.
- Key material format
When a key (key pair, public key, or private key) is imported or exported, the key material must be in the format required by the HUKS. For details, see [Key Material Formats](huks-appendix.md#key-material-format).
