@@ -23,29 +23,29 @@ Before using the HUKS for development, you are advised to understand the followi
- 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.
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.
- 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).
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).
## Working Principles
The security design of the HUKS includes the following:
-Always keep keys in a secure environment.
-Keys in a secure environment in lifecycle
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.
- Encrypted keys for storage
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.
-Strict access control over keys
Only authorized services can access keys. For security-sensitive services, user identity authentication can be enabled for key access.
-Provide key attestation.
-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.
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.
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.
OpenHarmony Universal KeyStore (HUKS) provides system-level key management capabilities, ensuring secure management and use of keys throughout their lifecycle (generation, storage, use, and destruction). The environment where a key is stored and used is of the most importance to key security. For example, the key in plaintext must be used in a secure environment, such as a Trusted Execution Environment (TEE) or security chip. This document describes how to configure a secure environment based on the HUKS architecture and how to verify the configuration.
OpenHarmony Universal KeyStore (HUKS) provides lifecycle key management from key generation, storage, use to destruction and attestation for the keys stored in the HUKS. In the HUKS hierarchical architecture, the HUKS core layer (HUKS Core) at the bottom implements key management functions and runs in a secure hardware environment, such as a Trusted Execution Environment (TEE) or secure chipset. The implementation of the HUKS core layer varies depending on the secure hardware environment of the vendor. To ensure consistency of the architecture and interfaces between the service layer and application layer, the HUKS core layer defines a set of Hardware Device Interface (HDI) APIs.
HUKS supports key lifecycle management, which covers the following:
This document describes how to develop the HUKS core layer functions using the HUKS HDI APIs.
- Key generation and import
The HUKS core layer is supposed to support the following functions:
-Key storage
-Generation of keys.
-Key use (including encryption and decryption, signing and verification, key derivation and agreement, hash, and key access control)
-Import of keys.
- Key destruction
- Key operations, including encryption and decryption, signing and signature verification, key derivation, key agreement, and generation of message authentication codes (MACs).
### Basic Concepts
- Key access control.
- Key attestation.
-HUKS Service
-Export of the public key from a chipset.
An independent OpenHarmony service that supports key management. It belongs to the huks_service process. Instead of handling key calculation, the HUKS Service depends on the HUKS Core to provide services for the upper layer.
### Basic Concepts
- HUKS Core
HUKS Core is a core component that implements functions, including cryptographic calculation of keys, encryption and decryption, and key access control. Generally, it runs in a secure environment (such as a TEE or secure chipset) of a device to ensure that the keys in plaintext are never exposed outside the HUKS Core.
- Key session
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).
A functional module that provides the key management service. This module must run in a secure environment, and the keys in plaintext must be kept inside the HUKS Core module throughout the lifecycle.
- TEE
A secure area created by isolating software and hardware resources to protect the applications and data in the secure area from unauthorized access. This isolation mechanism yields two execution environments: TEE and Rich Execution Environment (REE). Each execution environment has independent internal data path and memory, protecting the data inside the TEEs from being disclosed. The applications in an REE cannot access resources in a TEE. The applications in a TEE cannot access resources in another TEE without authorization.
A TEE is a secure area created by isolating software and hardware resources to protect the applications and data in the secure area from unauthorized access. This isolation mechanism yields two execution environments: TEE and Rich Execution Environment (REE). Each execution environment has independent internal data path and memory, protecting the data inside the TEE from being disclosed. The applications in an REE cannot access resources in a TEE. The applications in a TEE cannot access resources in another TEE without authorization.
## Working Principles
The HUKS is divided into the following layers:
- Application layer: provides APIs for applications.
- Service layer: processes key management requests from applications and performs key ciphertext management, identity verification, and key session management.
- Core layer: implements core functions, such as key generation, key operations, key access control, and key attestation.
**Update**: operates data by segment and returns the result, or appends data.
- Keys in a secure environment in lifecycle
**Finish**: finalizes the **Update** operation, and returns the result.
In the lifecycle of a key, the plaintext will never be exposed outside the HUKS Core. For the devices with a 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 REE is cracked. That is why the key materials used in all HUKS passthrough HDI APIs are in ciphertext.
### Working Principles
- Encrypted keys for storage
The following uses the key generation process as an example to describe the communication between the HUKS Service and HUKS Core. Other key operations are similar.
The upper-layer application invokes the HUKS Service through the key management SDK. The HUKS Service invokes the HUKS Core, which invokes the key management module to generate a key. The HUKS Core uses a work key derived from the root key to encrypt the generated key and sends the encrypted key to the HUKS Service. The HUKS Service stores the encrypted key in a file.
The service keys are encrypted based on the device root key. If supported by the device, certain keys can be further protected by a password.
- Strict access control over keys
### Constraints
Only authorized services can access keys. For security-critical services, user identity authentication can be enabled for key access.
- Key attestation
* HUKS must be implemented in a TEE for security purposes.
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.
* The certificate chain returned by **HuksHdiAttestKey** must be in the sequence of the application certificate, device certificate, CA certificate, and root certificate, with the certificate length added before each certificate. The certificate chain and its length are assembled in the binary large object (BLOB) format. If you want to define the certificate format, the format must be the same as that parsed by the server.
- Key material format
When a key (key pair, public key, or private key) is imported or exported, the key material format must meet HUKS requirements. For details, see [Key Material Formats](../../application-dev/security/huks-appendix.md#key-material-formats).
- Certificate chain format
* The key returned by the API must be assembled into a **KeyBlob** based on the key storage status. For details about the APIs that must comply with this constraint, see [Available APIs](#available-apis).
The certificate chain returned by **AttestKey()** must be assembled in the sequence of the application certificate, device certificate, CA certificate, and root certificate, with the certificate length added before each certificate. The certificate chain and its length are in the binary large object (BLOB) format. If you want to define the certificate format, the format must be the same as that parsed by the server.
The **KeyBlob** stores both the key and its attributes. The figure below shows the **KeyBlob** structure. For details about how to construct a **KeyBlob**, see [hks_keyblob.c/HksBuildKeyBlob](https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_keyblob.c).
- KeyBlob
## Development Guidelines
The key returned by the APIs must be assembled into a **KeyBlob** based on the key storage status. For details about the APIs that must comply with this constraint, see [Available APIs](#available-apis).
## How to Develop
### When to Use
The HUKS Core provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. If you want to replace the HUKS Core with your own implementation, you need to implement the following APIs:
The HUKS Core provides KeyStore capabilities for applications, including key management and cryptographic operations. If you want to replace the HUKS Core with your own implementation, you need to implement the following APIs.
### Available APIs
**Table 1** Available APIs
| API | Description | Constraints | Corresponding JS API |
| [HuksHdiGenerateKey()](#hukshdigeneratekey) | Generates a key. | The key generated must be in the **KeyBlob** format. |generateKey(keyAlias: string, options: HuksOptions)|
| [HuksHdiImportKey()](#hukshdiimportkey) | Imports a key in plaintext. | The output parameter must be in the **KeyBlob** format. | importKey(keyAlias: string, options: HuksOptions)|
| [HuksHdiImportWrappedKey()](#hukshdiimportwrappedkey) |Imports an encrypted key. | The output parameter must be in the **KeyBlob** format. | importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions)|
| [HuksHdiExportPublicKey()](#hukshdiexportpublickey) | Exports a public key. |– | exportKey(keyAlias: string, options: HuksOptions) |
| [HuksHdiInit()](#hukshdiinit) | Initializes data for a key operation. This API is of the Init-Update-Final model. |– | init(keyAlias: string, options: HuksOptions) |
| [HuksHdiUpdate()](#hukshdiupdate) | Operates data by segment or appends data for the key operation. This API is of the Init-Update-Final model. |The input parameter for signing and signature verification must be the raw data. | update(handle: number, token?: Uint8Array, options: HuksOptions) |
| [HuksHdiFinish()](#hukshdifinish) | Finalizes the key operation. This API is of the Init-Update-Final model. |The input parameter for signing and signature verification must be the signed data. | finish(handle: number, options: HuksOptions) |
| [HuksHdiAttestKey()](#hukshdiattestkey) | Obtains the key certificate. |The output parameter must be in the **certChain** format. | attestKey(keyAlias: string, options: HuksOptions)|
| [HuksHdiExportChipsetPlatformPublicKey()](#hukshdiexportchipsetplatformpublickey) | Exports the public key of a chipset key pair. | The output parameters are the raw data of ECC P-256 x-axis and y-axis values, each of which are of 32 bytes. | –|
| [GenerateKey()](#generatekey) | Generates a key based on the cryptographic algorithm parameters. | The key output must be in the **KeyBlob** format. |generateKey(keyAlias: string, options: HuksOptions)|
| [ImportKey()](#importkey) | Imports a key in plaintext. | The key output must be in the **KeyBlob** format. | importKey(keyAlias: string, options: HuksOptions)|
| [ImportWrappedKey()](#importwrappedkey) |Imports a wrapped (encrypted) key. | The key output must be in the **KeyBlob** format. | importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions)|
| [ExportPublicKey()](#exportpublickey) | Exports the public key of a key pair. |N/A | exportKey(keyAlias: string, options: HuksOptions) |
| [Init()](#init) | Initializes a key session. This API returns a key session handle and an authentication token (optional). |N/A | init(keyAlias: string, options: HuksOptions) |
| [Update()](#update) | Updates key operation data. |The input parameters for signature verification must be the raw data. | update(handle: number, token?: Uint8Array, options: HuksOptions) |
| [Finish()](#finish) | Finishes a key session. |The input parameter for signature verification must be the signed data. | finish(handle: number, options: HuksOptions) |
| [CheckKeyValidity()](#checkkeyvalidity) | Checks the key material (ciphertext) validity. |N/A | N/A|
| [AttestKey()](#attestkey) | Attests a key. |The output parameter must be in the certificate chain format. | attestKey(keyAlias: string, options: HuksOptions)|
| [ExportChipsetPlatformPublicKey()](#exportchipsetplatformpublickey) | Exports the public key of a chipset key pair. | The output parameters are the raw data of ECC P-256 x-axis and y-axis values, each of which are of 32 bytes. | N/A|
| [DeriveKey()](#derivekey) | Derives a key. | N/A | N/A|
| [Mac()](#mac) | Generates a MAC. | N/A | N/A|
- - -
#### HuksHdiModuleInit
#### ModuleInit
**API Description**
Initializes the HUKS Core, including the lock, encryption algorithm library, authtoken key, and root key.
Initializes the HUKS Core. You can use this API to initialize global variables, such as the global thread locks, algorithm library, and the AuthToken key and root key used for access control.
-**HKS_SUCCESS** (the value is **0**): The operation is successful.
- Other value: The operation failed.
- Other values (negative number): The operation fails. For details, see <ahref="https://gitee.com/openharmony/security_huks/blob/master/interfaces/inner_api/huks_standard/main/include/hks_type.h">HksErrorCode</a>.
</details>
- - -
#### HuksHdiRefresh
#### ModuleDestroy
**API Description**
Refreshes the root key.
Destroys the HUKS Core. You can use this API to release global variables including the locks and destroy the AuthToken key and root key in the memory.
Pointer to the alias of the key to import. The value must meet the following requirements:
<strong>struct IHuks *self</strong>
Pointer to the HUKS HDI struct.
<br></br>
<strong>const struct HuksBlob *keyAlias</strong>
Pointer to the alias of the key to import. The alias must meet the following requirements:
1. keyAlias != null
2. keyAlias -> data != null
3. keyAlias -> size != 0
3. keyAlias -> dataLen != 0
<br></br>
<strong>const struct HksBlob *key</strong>
Pointer to the key to import. The value must meet the following requirements:
<strong>const struct HuksBlob *key</strong>
Pointer to the plaintext key material to import. For details about the key material format, see <ahref="../application-dev/security/huks-appendix.md#key-material-formats">Key Material Formats</a>. The value must meet the following requirements:
Pointer to the alias of the key used to encrypt the key to import (it is not the alias of the key to import). The value must meet the following requirements:
Pointer to the key material of the key to import. For details abut the key material format, see <ahref="../../application-dev/security/huks-guidelines.md#importing-a-key-securely">Importing a Key Securely</a>. The value must meet the following requirements:
Pointer to the parameters for exporting the public key. By default, this parameter is left blank.
<br></br>
<strong>struct HksBlob *keyOut</strong>
Pointer to the output parameter, which holds the public key exported.
<strong>struct HuksBlob *keyOut</strong>
Pointer to the public key exported.
</pre>
</details>
<br></br>
...
...
@@ -321,39 +388,51 @@ Exports a public key.
-**HKS_SUCCESS**: The operation is successful.
- Other value: The operation failed.
- Other values: The operation fails.
</details>
- - -
#### HuksHdiInit
#### Init
**API Description**
Initializes data for a key operation. This API is of the Init-Update-Final model.
Initializes a key session. You need to pass in the key material in ciphertext. The HUKS Core decrypts the ciphertext and generates a key session handle and an authentication token (if required).
Pointer to the result of the **Finish** operation.
<strong>const struct HuksBlob *inData</strong>
Pointer to the last data to be passed in.
<br></br>
<strong>struct HuksBlob *outData</strong>
Pointer to the result of the key operation.
</pre>
</details>
<br></br>
...
...
@@ -441,7 +530,9 @@ Finalizes the key operation. This API is of the Init-Update-Final model.
<details>
<summary><strong>Constraints</strong></summary>
1. In signing and signature verification, **inData** must pass in the signature data to be verified. The return value indicates whether the operation is successful.
1. This API must be used with **Init()**, **Update()**, and **Abort()** together.
2. In signature verification, **inData** must pass in the signature data to be verified. The return value indicates whether the signature has passed the verification.
</details>
<br></br>
...
...
@@ -451,30 +542,40 @@ Finalizes the key operation. This API is of the Init-Update-Final model.
-**HKS_SUCCESS**: The operation is successful.
- Other value: The operation failed.
- Other values: The operation fails.
</details>
- - -
#### HuksHdiAbort
#### Abort
**API Description**
Aborts Init-Update-Finish. When an error occurs in any of the **Init**, **Update**, and **Finish** operations, call this API to terminate the use of the key.
Aborts the key session. When an error occurs in any of the **Init**, **Update**, and **Finish** operations, call this API to terminate the key session.
Pointer to the raw data of ECC P-256 x-axis and y-axis values, each of which are of 32 bytes.
</pre>
</details>
<br></br>
<details>
<summary><strong>Constraints</strong></summary>
1. The input parameter **salt** must be of 16 bytes, and the content of the last byte will be ignored and filled by HUKS based on **scene**.
Currently, the chipset key pairs of HUKS are implemented by software. An ECC P-256 key pair is hard-coded, and the **salt** value is ignored. That is, the derived keys are the same regardless of the **salt**. In the hardware-based implementation of chipset key pairs, **salt** is a factor used to derive the key. That is, the key pair derived varies with the **salt** value.
The input parameter **salt** must be of 16 bytes, and the content of the last byte will be ignored and filled by HUKS based on **scene**.
Currently, the chipset key pairs of HUKS are implemented by software. An ECC P-256 key pair is hard-coded, and the **salt** value is ignored. That is, the derived keys are the same regardless of the **salt**. In the hardware-based implementation of chipset key pairs, **salt** is a factor used to derive the key. That is, the key pair derived varies with the **salt** value.
</details>
<br></br>
...
...
@@ -598,31 +710,35 @@ Exports the public key of a chipset key pair.
-**HKS_SUCCESS**: The operation is successful.
- Other value: The operation failed.
- Other values: The operation fails.
</details>
- - -
#### HuksHdiUpgradeKey
#### UpgradeKey
**API Description**
Updates the key file when the key file version is earlier than the latest version.
Pointre to the source data for which the MAC is to be generated.
<br></br>
<strong>struct HuksBlob *mac</strong>
Pointer to the MAC generated.
</pre>
</details>
<br></br>
<details>
<summary><strong>Return Value</strong></summary>
-**HKS_SUCCESS**: The operation is successful.
- Other values: The operation fails.
</details>
- - -
### Development Procedure
The directory structure is as follows:
#### Directory Structure
The code for HDI adaptation is in the following directory.
```undefined
//drivers_peripheral/huks
├── BUILD.gn # Build script.
├── hdi_service # Dependency loaded from libhuks_engine_core_standard.z.so (software implementation of the HUKS Core for reference only) by using dlopen().
├── huks_sa_type.h # Defines the data structs used in the HUKS service layer.
├── huks_sa_hdi_struct.h # Defines the function pointer structs in libhuks_engine_core_standard.z.so.
├── huks_hdi_template.h # Defines the conversion between the data structs of the HUKS service layer and the HDI.
├── huks_hdi_service.c # Implementation of the HUKS passthrough HDI APIs.
└── huks_hdi_passthrough_adapter.c # Adaptation of HUKS passthrough HDI APIs to the HUKS Core.
└── test # Test code for the HUKS HDI APIs.
├── BUILD.gn # Build script.
├── fuzztest # Fuzz test.
└── unittest # Unit test.
```
The code of the HUKS Core software implementation is in the following directory.
<summary><strong>The software implementation of the HUKS Core contains hard-coded sensitive data, including the root key, AuthToken key for access control, key used to encrypt AuthToken, and certificate. You need to replace these code with your own implementation. /summary>
- Root key
The root key is used to encrypt the HUKS service key and is generally derived from the device root key. It is hard-coded in the HUKS Core software implementation. For details, see <a href="https://gitee.com/openharmony/security_huks/blob/master/frameworks/huks_standard/main/crypto_engine/openssl/src/hks_openssl_get_main_key.c">hks_openssl_get_main_key.c</a>.
- Key for generating an HMAC on AuthToken
The key is used to generate an HMAC on AuthToken by the UserIAM for access control. The value is **huks_default_user_auth_token_key** and hard-coded in the HUKS Core software implementation. For details about the code, see <ahref="https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_keyblob.c">hks_keyblob.c</a>.
- Key for encrypting sensitive fields of AuthToken
The key is used to encrypt sensitive fields of AuthToken in access control. The value is **huks_default_user_auth_token_key** and hard-coded in the HUKS Core software implementation. For details about the code, see <ahref="https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_keyblob.c">hks_keyblob.c</a>.
- Root certificate, device CA, and device certificate
The root certificate, device CA, and device certificate are used for key attestation and preset in the secure storage of the hardware device by the device certificate management module. These certificates are hard-coded in the HUKS Core software implementation. For details about the code, see <a href="https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/device_cert_manager/include/dcm_certs_and_key.h">dcm_certs_and_key.h</a>.
Init-Update-Finish must be used to implement HUKS Core APIs. The following provides the development procedure of Init-Update-Finish and sample code of the HUKS Core. You can refer to the following code to implement all HDI APIs.
#### Example
For the code of other HUKS Core APIs, see [hks_core_service.c](https://gitee.com/openharmony/security_huks/blob/master/services/huks_standard/huks_engine/main/core/src/hks_core_service.c).
The following uses the adaptation of the key session APIs **Init**, **Update**, and **Finish** in the HUKS Core as an example. The sample code is for reference only and cannot be used directly. For details about the executable code, see [HUKS source code](https://gitee.com/openharmony/security_huks).
1. Create a handle to enable the information about the operations on a key to be stored in a session. With this handle, multiple operations on the same key can be performed.
1. Create a handle to identify information about key operations in a session. With this handle, multiple operations on the same key can be performed.
HKS_LOG_E("before finish: append auth info failed");
...
...
@@ -863,15 +1335,15 @@ For the code of other HUKS Core APIs, see [hks_core_service.c](https://gitee.com
}
```
### Verification
### Debugging
Use the [HUKS JS APIs](https://gitee.com/openharmony/security_huks/blob/master/interfaces/kits/js/@ohos.security.huks.d.ts) to develop a JavaScript application to verify HUKS capabilities.
Use [HUKS JS APIs](https://gitee.com/openharmony/security_huks/blob/master/interfaces/kits/js/@ohos.security.huks.d.ts) to develop a JavaScript application to verify HUKS capabilities.
The JS API corresponding to each HDI API is provided in [Available APIs](#available-apis). You can invoke the JS APIs to verify the capabilities of the corresponding HDI APIs or perform complete key operations to verify the capabilities of the APIs.
The JS APIs corresponding to HDI APIs are provided in [Available APIs](#available-apis). You can use the JS APIs to verify the capabilities of the corresponding HDI APIs or perform complete key operations to verify the capabilities of the APIs.
The JS test code is as follows. If the entire process is successful, the HDI APIs are functioning. For more information about key operations, see [HUKS Development](../../application-dev/security/huks-guidelines.md).
The following JS test code is for reference only. If the entire process goes properly, the HDI APIs are functioning. For more key operation types and samples, see [huks-guidelines.md](../../application-dev/security/huks-guidelines.md).
**Generating and Encrypting an AES Key**
**Generating an AES Key and Encrypting Data**
1. Import the HUKS module.
...
...
@@ -879,102 +1351,109 @@ The JS test code is as follows. If the entire process is successful, the HDI API
