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.
| generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void| Generates a key. This method uses an asynchronous callback to return the result. |
| generateKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>| Generates a key. This method uses a promise to return the result. |
| exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void| Exports the public key. This method uses an asynchronous callback to return the result. |
| exportKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>| Exports the public key. This method uses a promise to return the result. |
| isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback<boolean>) : void | Checks whether a key exists. This method uses an asynchronous callback to return the result.|
| isKeyExist(keyAlias: string, options: HuksOptions) : Promise<boolean> | Checks whether a key exists. This method uses a promise to return the result.|
| deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void| Deletes a key. This method uses an asynchronous callback to return the result. |
| deleteKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>| Deletes a key. This method uses a promise to return the result. |
## How to Develop
## JS-based Development
1. Import the HUKS module.
...
...
@@ -28,9 +14,9 @@
2. Call **generateKey()** to generate a key.
**keyAlias** indicates the alias of the key generated. **options** indicates the parameters used for generating the key. Set **options** based on the actual situation.
**keyAlias** indicates the alias of the key generated. **options** indicates the parameters used for generating the key. Set **options** based on the algorithms to be used.
The value returned indicates whether the key is successfully generated.
The return value indicates whether the key is successfully generated.
```js
varalias='testAlias';
...
...
@@ -57,11 +43,11 @@
varresultA=huks.generateKey(alias,options);
```
3. Call **Init()** to initialize the key.
3. Call **Init()** to initialize data for a key operation.
**Alias** indicates the alias of the key to initialize, and **options** indicates the parameters used for initializing the key. Set **options** based on the actual situation.
**Alias** indicates the alias of the key, and **options** indicates the parameters used for initialization. Set **options** based on the algorithms to be used.
The value returned indicates whether the **Init** operation is successful.
The return value indicates whether the **Init** operation is successful.
```js
varalias='test001'
...
...
@@ -89,12 +75,12 @@
}
})
```
4. Call **update()** to update the key.
**handle** indicates the session ID for updating the key. **options** indicates the parameters used for updating the key. Set **options** based on the actual situation.
4. Call **update()** to add data for the key operation by segment.
**handle** indicates the session ID for the **update** operation. **options** indicates the parameters used for the **update** operation. Set **options** based on the algorithms to be used.
The value returned indicates whether the **Update** operation is successful.
The return value indicates whether the **update** operation is successful.
```js
varproperties=newArray();
...
...
@@ -115,12 +101,12 @@
};
varresult=huks.update(handle,options)
```
5. Call **finish()** to complete the operation.
**handle** indicates the session ID of the **Finish** operation. **options** indicates the parameters used for this operation. Set **options** based on the actual situation.
**handle** indicates the session ID of the **finish** operation. **options** indicates the parameters used for this operation. Set **options** based on the algorithms to be used.
The value returned indicates whether the **Finish** operation is successful.
The return value indicates whether the **finish** operation is successful.
```js
varproperties=newArray();
...
...
@@ -141,3 +127,1804 @@
};
varresult=huks.finish(handle,options)
```
## TS-based Development
### Key Import and Export
The **HUKS** module allows an application to export the public key of its own asymmetric keys (public/private key pairs) based on the key alias.
The **HUKS** module also supports import of external keys. Except the public keys of asymmetric keys, the keys imported into the HUKS cannot be exported in their lifecycle. If the alias of the key to be imported already exists in HUKS, the newly imported key will overwrite the existing one.
The service invoker and HUKS negotiate a shared symmetric key to encrypt and decrypt the intermediate key and the key to be imported. After the encrypted key is imported, it is decrypted and saved in HUKS. The keys in plaintext can be processed in HUKS only.
The development procedure is as follows:
1. Generate a key pair in HUKS. The key pair is used to encrypt the key to import.
2. Export the public key of the key pair and obtain a shared key through key agreement.
3. Generate intermediate key materials and encrypt the key.
> - When generating a public key, set **HUKS_TAG_PURPOSE = HUKS_KEY_PURPOSE_UNWRAP**.
> - Set **HUKS_TAG_IMPORT_KEY_TYPE = HUKS_KEY_TYPE_KEY_PAIR**.
> - When importing a key in secure mode, add **HUKS_TAG_UNWRAP_ALGORITHM_SUITE** with value set to **HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING** or **HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING**.
> - The key alias cannot exceed 64 bytes.
Before you get started, understand the following variables:
Use the symmetric or asymmetric key stored in HUKS to encrypt or decrypt data based on the specified alias. The keys in plaintext must be in a secure environment during the encryption and decryption process.
The data to be sent can be signed with a unique signature for security purposes. Then, the receiver needs to verify the signature when receiving the data.
The development procedure is as follows:
1. Generate a key.
2. Use the key to sign the data to be sent.
3. Export the signature key.
4. Import the signature key.
5. Verify the signature.
**Supported key types**:
Only **HksInit()** has requirements on parameters in **paramSet**. The other Init-Update-Finish APIs have no requirements on **paramSet**.
The signing and signature verification using Ed25519 involves a hash operation in the algorithm engine. Therefore, the Init-Update-Finish processing is special.
In the **update()** process, **inData** is sent to HUKS Core and recorded in a .ctx file, without performing hash operation. The signing and signature verification calculations are performed on the combined **inData** in the **finish()** operation.
A message authentication code (MAC) is a hash-based value used for authenticating a message. It is used to check whether the message comes from the stated sender and has not been changed.
The development procedure is as follows:
1. Generate a key.
2. Generate a MAC.
**Supported key types**:
Only **HksInit()** has requirements on parameters in **paramSet**. The other Init-Update-Finish APIs have no requirements on **paramSet**.
After an application generates an asymmetric key, the certificate chain can be obtained through ID attestation. ID attestation supports the following device: brand, device, product, serial number, IMEI, MEID, manufacturer, model, SOC ID, and UDID.
The application can also obtain the certificate chain through key attestation.
ID attestation and key attestation are available only for devices in a trusted execution Environment (TEE).
printLog(`key attest result : ${JSON.stringify(data)}`);
});
}
```
### AttestKey
After an application generates an asymmetric key, the certificate chain can be obtained by key attestation. You can also use ID attestation to obtain the certificate chain. The public certificate contains information such as the device ID.
ID attestation and key attestation are available only for devices in a trusted execution Environment (TEE).
