Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 9cd0ecfc 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!17427 [翻译完成】#I6RY4N 

Merge pull request !17427 from Annie_wang/PR16764
上级 b46f6a42 a2162864
隐藏空白更改
内联 并排
Showing with 102 addition and 58 deletion
en/device-dev/subsystems/subsys-security-huks-guide.md
浏览文件 @ 9cd0ecfc
...@@ -24,7 +24,7 @@ HUKS supports key lifecycle management, which covers the following: ...@@ -24,7 +24,7 @@ HUKS supports key lifecycle management, which covers the following:
- HUKS Core - HUKS Core
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 their lifecycle. 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 - TEE
...@@ -32,15 +32,15 @@ HUKS supports key lifecycle management, which covers the following: ...@@ -32,15 +32,15 @@ HUKS supports key lifecycle management, which covers the following:
- Init-Update-Finish - Init-Update-Finish
**Init**: initializes data for a key operation. **Init**: initializes data for a key operation.
**Update**: operates data by segment and returns the result, or appends data. **Update**: operates data by segment and returns the result, or appends data.
**Finish**: finalizes the **Update** operation, and returns the result. **Finish**: finalizes the **Update** operation, and returns the result.
### Working Principles ### Working Principles
The following uses the key generation process as an example to describe communication between the HUKS Service and HUKS Core. Other key operations are similar. 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 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.
![](figures/HUKS-GenerateKey1.png) ![](figures/HUKS-GenerateKey1.png)
...@@ -84,55 +84,57 @@ The HUKS Core provides KeyStore (KS) capabilities for applications, including ke ...@@ -84,55 +84,57 @@ The HUKS Core provides KeyStore (KS) capabilities for applications, including ke
| [HuksHdiGetKeyProperties()](#hukshdigetkeyproperties) | Obtains key properties. |– | getKeyProperties(keyAlias: string, options: HuksOptions)| | [HuksHdiGetKeyProperties()](#hukshdigetkeyproperties) | Obtains key properties. |– | getKeyProperties(keyAlias: string, options: HuksOptions)|
| [HuksHdiAttestKey()](#hukshdiattestkey) | Obtains the key certificate. |The output parameter must be in the **certChain** format. | attestKey(keyAlias: string, 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. | –| | [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. | –|
| [HuksHdiUpgradeKey()](#hukshdiupgradekey) | Updates the key file. | – | –|
- - - - - -
#### HuksHdiModuleInit #### HuksHdiModuleInit
**API description** **API Description**
Initializes the HUKS Core, including the lock, encryption algorithm library, authtoken key, and root key. Initializes the HUKS Core, including the lock, encryption algorithm library, authtoken key, and root key.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiModuleInit();</code></pre> <pre><code>int32_t HuksHdiModuleInit();</code></pre>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - -
#### HuksHdiRefresh #### HuksHdiRefresh
**API description** **API Description**
Refreshes the root key. Refreshes the root key.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiRefresh();</code></pre> <pre><code>int32_t HuksHdiRefresh();</code></pre>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - -
#### HuksHdiGenerateKey #### HuksHdiGenerateKey
**API description** **API Description**
Generates a key based on **paramSet**. Generates a key based on **paramSet**.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiGenerateKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet, const struct HksBlob *keyIn, struct HksBlob *keyOut);</code></pre> <pre><code>int32_t HuksHdiGenerateKey(const struct HksBlob *keyAlias, const struct HksParamSet *paramSet, const struct HksBlob *keyIn, struct HksBlob *keyOut);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -165,24 +167,24 @@ Generates a key based on **paramSet**. ...@@ -165,24 +167,24 @@ Generates a key based on **paramSet**.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - -
#### HuksHdiImportKey #### HuksHdiImportKey
**API description** **API Description**
Imports a key in plaintext. Imports a key in plaintext.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiImportKey(const struct HksBlob *keyAlias, const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);</code></pre> <pre><code>int32_t HuksHdiImportKey(const struct HksBlob *keyAlias, const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -219,23 +221,24 @@ Imports a key in plaintext. ...@@ -219,23 +221,24 @@ Imports a key in plaintext.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiImportWrappedKey #### HuksHdiImportWrappedKey
**API description** **API Description**
Imports an encrypted key. Imports an encrypted key.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiImportWrappedKey(const struct HksBlob *keyAlias, const struct HksBlob *wrappingUsedkey, const struct HksBlob *wrappedKeyData, const struct HksParamSet *paramSet, struct HksBlob *keyOut);</code></pre> <pre><code>int32_t HuksHdiImportWrappedKey(const struct HksBlob *keyAlias, const struct HksBlob *wrappingUsedkey, const struct HksBlob *wrappedKeyData, const struct HksParamSet *paramSet, struct HksBlob *keyOut);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -277,23 +280,24 @@ Imports an encrypted key. ...@@ -277,23 +280,24 @@ Imports an encrypted key.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiExportPublicKey #### HuksHdiExportPublicKey
**API description** **API Description**
Exports a public key. Exports a public key.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiExportPublicKey(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);</code></pre> <pre><code>int32_t HuksHdiExportPublicKey(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *keyOut);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -313,23 +317,24 @@ Exports a public key. ...@@ -313,23 +317,24 @@ Exports a public key.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiInit #### HuksHdiInit
**API description** **API Description**
Initializes data for a key operation. This API is of the Init-Update-Final model. Initializes data for a key operation. This API is of the Init-Update-Final model.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiInit(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *handle, struct HksBlob *token);</code></pre> <pre><code>int32_t HuksHdiInit(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *handle, struct HksBlob *token);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -352,23 +357,24 @@ Initializes data for a key operation. This API is of the Init-Update-Final model ...@@ -352,23 +357,24 @@ Initializes data for a key operation. This API is of the Init-Update-Final model
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiUpdate #### HuksHdiUpdate
**API description** **API Description**
Operates data by segment or appends data for the key operation. This API is of the Init-Update-Final model. Operates data by segment or appends data for the key operation. This API is of the Init-Update-Final model.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);</code></pre> <pre><code>int32_t HuksHdiUpdate(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -396,23 +402,24 @@ Operates data by segment or appends data for the key operation. This API is of t ...@@ -396,23 +402,24 @@ Operates data by segment or appends data for the key operation. This API is of t
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiFinish #### HuksHdiFinish
**API description** **API Description**
Finalizes the key operation. This API is of the Init-Update-Final model. Finalizes the key operation. This API is of the Init-Update-Final model.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);</code></pre> <pre><code>int32_t HuksHdiFinish(const struct HksBlob *handle, const struct HksParamSet *paramSet, const struct HksBlob *inData, struct HksBlob *outData);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -440,23 +447,24 @@ Finalizes the key operation. This API is of the Init-Update-Final model. ...@@ -440,23 +447,24 @@ Finalizes the key operation. This API is of the Init-Update-Final model.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiAbort #### HuksHdiAbort
**API description** **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 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.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiAbort(const struct HksBlob *handle, const struct HksParamSet *paramSet);</code></pre> <pre><code>int32_t HuksHdiAbort(const struct HksBlob *handle, const struct HksParamSet *paramSet);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -470,23 +478,24 @@ Aborts Init-Update-Finish. When an error occurs in any of the **Init**, **Update ...@@ -470,23 +478,24 @@ Aborts Init-Update-Finish. When an error occurs in any of the **Init**, **Update
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiGetKeyProperties #### HuksHdiGetKeyProperties
**API description** **API Description**
Obtains key properties. Obtains key properties.
**Prototype** **Prototype**
<pre><code>int32_t HuksHdiGetKeyProperties(const struct HksParamSet *paramSet, const struct HksBlob *key);</code></pre> <pre><code>int32_t HuksHdiGetKeyProperties(const struct HksParamSet *paramSet, const struct HksBlob *key);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -500,23 +509,24 @@ Obtains key properties. ...@@ -500,23 +509,24 @@ Obtains key properties.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiAttestKey #### HuksHdiAttestKey
**API description** **API Description**
Obtains the key certificate. Obtains the key certificate.
**Prototype** **Prototype**
<pre><code>int32_t (*HuksHdiAttestKey)(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *certChain);</code></pre> <pre><code>int32_t (*HuksHdiAttestKey)(const struct HksBlob *key, const struct HksParamSet *paramSet, struct HksBlob *certChain);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -541,23 +551,24 @@ Obtains the key certificate. ...@@ -541,23 +551,24 @@ Obtains the key certificate.
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
#### HuksHdiExportChipsetPlatformPublicKey #### HuksHdiExportChipsetPlatformPublicKey
**API description** **API Description**
Exports the public key of a chipset key pair. Exports the public key of a chipset key pair.
**Prototype** **Prototype**
<pre><code>int32_t (*HuksHdiExportChipsetPlatformPublicKey)(const struct HksBlob *salt, enum HksChipsetPlatformDecryptScene scene, struct HksBlob *publicKey);</code></pre> <pre><code>int32_t (*HuksHdiExportChipsetPlatformPublicKey)(const struct HksBlob *salt, enum HksChipsetPlatformDecryptScene scene, struct HksBlob *publicKey);</code></pre>
<details> <details>
<summary><strong>Parameters</strong></summary> <summary><strong>Parameters</strong></summary>
<pre> <pre>
...@@ -577,18 +588,51 @@ Exports the public key of a chipset key pair. ...@@ -577,18 +588,51 @@ Exports the public key of a chipset key pair.
<summary><strong>Constraints</strong></summary> <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**. 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.
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>
<details>
<summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful.
- Other value: The operation failed.
</details>
- - -
#### HuksHdiUpgradeKey
**API Description**
Updates the key file when the key file version is earlier than the latest version.
**Prototype**
<pre><code>int32_t (*HuksHdiUpgradeKey)(const struct HksBlob *oldKey, const struct HksParamSet *paramSet, struct HksBlob *newKey);</code></pre>
<details>
<summary><strong>Parameters</strong></summary>
<pre>
<strong>const struct HksBlob *oldKey</strong>
Key file data to update.
<br></br>
<strong>const struct HksParamSet *paramSet</strong>
Parameters for updating the key file data.
<br></br>
<strong>struct HksBlob *newKey</strong>
New key file data.
</pre>
</details> </details>
<br></br> <br></br>
<details> <details>
<summary><strong>Return value</strong></summary> <summary><strong>Return Value</strong></summary>
- **HKS_SUCCESS**: The operation is successful. - **HKS_SUCCESS**: The operation is successful.
- Other value: The operation fails. - Other value: The operation failed.
</details> </details>
- - - - - -
...@@ -599,15 +643,15 @@ The directory structure is as follows: ...@@ -599,15 +643,15 @@ The directory structure is as follows:
```undefined ```undefined
// base/security/user_auth/services/huks_standard/huks_engine/main // base/security/user_auth/services/huks_standard/huks_engine/main
├── BUILD.gn # Build script ├── BUILD.gn # Build script
├── core_dependency # Dependencies of the implementation ├── core_dependency # Dependencies of the implementation
└── core # Software implementation of the HUKS Core └── core # Software implementation of the HUKS Core
├── BUILD.gn # Build script ├── BUILD.gn # Build script
├── include ├── include
└── src └── src
├── hks_core_interfaces.c # Adaptation of the HDI to the HUKS Core ├── hks_core_interfaces.c # Adaptation of the HDI to the HUKS Core
└── hks_core_service.c # Specific implementation └── hks_core_service.c # Specific implementation
└── ... # Other function code └── ... # Other function code
``` ```
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. 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.
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或