1# HUKS Overview 2 3## Introduction 4 5OpenHarmony 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. 6The 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. 7 8 9The HUKS provides the following functions: 10 11- [Key Generation](huks-guidelines.md#key-generation) 12- [Key Import](huks-guidelines.md#key-import) 13- [Common Key Operations](huks-guidelines.md#common-key-operations) 14- [Key Access Control](huks-guidelines.md#key-access-control) 15- [Key Attestation](huks-guidelines.md#key-attestation) 16- [Supported Algorithm Types and Parameter Combinations](huks-appendix.md#supported-algorithm-types-and-parameter-combinations) 17- [Key Material Formats](huks-appendix.md#key-material-formats) 18 19 20## Basic Concepts 21 22Before using the HUKS for development, you are advised to understand the following basic concepts: 23 24- HUKS Core 25 26 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 a Trusted Execution Environment (TEE) or a secure chipset of the device to ensure that the keys in plaintext are always in the HUKS Core. 27 28- Key session 29 30 A key session holds the key information, including the key operation data, key properties, 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 finishing the session (or aborting the session). 31 32 33## Working Principles 34 35 36The security design of the HUKS includes the following: 37- Keys in a secure environment in lifecycle 38 39 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. 40- Encrypted keys for storage 41 42 The service keys are encrypted based on the device root key. Some keys can be protected by passwords if the devices support this feature. 43- Strict access control over keys 44 45 Only authorized services can access keys. For security-sensitive services, user identity authentication can be enabled for key access. 46- Key attestation 47 48 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 properties. 49 50 51A 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. 52 53**Figure 1** HUKS working mechanism 54 55 56 57## Constraints 58 59 - Alias-based access 60 61 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. 62 63 - Data segment size 64 65 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. 66 67 - Mandatory parameters 68 69 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. 70 71 - Key material format 72 73 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). 74
