# HUKS Development ## Key Generation The HUKS provides the capability of randomly generating keys for services. For a key generated by the HUKS, its plaintext will never be exposed outside throughout the lifecycle. This ensures that no one can access the plaintext of the key. Even the service that generates the key can call APIs provided by the HUKS to perform key operations and obtain the operation result, rather than accessing the key. **How to Develop** Use [huks.generateKeyItem(keyAlias,options,callback)](../reference/apis/js-apis-huks.md#huksgeneratekeyitem9) to generate a key. You need to pass in the key alias in **keyAlias**, a key attribute set in **options**, and **callback** to result the result asynchronously. For details about the APIs, see [HUKS](../reference/apis/js-apis-huks.md). 1. Determine the key alias. 2. Initialize the key attributes.
Use [HuksParam](../reference/apis/js-apis-huks.md#huksparam) to encapsulate key attributes. Use a **HuksParam** array to assign values to the **properties** field of [HuksOptions](../reference/apis/js-apis-huks.md#huksoptions). The parameters [HuksKeyAlg](../reference/apis/js-apis-huks.md#hukskeyalg), [HuksKeySize](../reference/apis/js-apis-huks.md#hukskeysize), and [HuksKeyPurpose](../reference/apis/js-apis-huks.md#hukskeypurpose) are mandatory. 3. Pass in the key alias and key parameter set to generate a key. > **NOTE** > > The key alias cannot exceed 64 bytes. **Sample code** ```ts /* * Generate a DH key and return the result by a callback. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let keyAlias = 'dh_key'; let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_DH } properties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE } properties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_DH_KEY_SIZE_2048 } properties[3] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 } let huksOptions = { properties: properties, inData: new Uint8Array(new Array()) } /* * Generate a key. */ function generateKeyItem(keyAlias: string, huksOptions: huks.HuksOptions) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throw (error); } }); } async function publicGenKeyFunc(keyAlias: string, huksOptions: huks.HuksOptions) { console.info(`enter callback generateKeyItem`); try { await generateKeyItem(keyAlias, huksOptions) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function TestGenKey() { await publicGenKeyFunc(keyAlias, huksOptions); } ``` ## Key Import If the key is generated outside the HUKS (for example, generated through key agreement or by a server), the application can import the key to the HUKS for management. The HUKS supports import of keys in plaintext. However, if keys are imported in plaintext, the keys are exposed in the REE memory. This operation applies to lightweight devices or security-insensitive services. For security-sensitive services, use the secure import provided by the HUKS. Secure import allows the keys generate keys by services to be transferred to the HUKS through an end-to-end encrypted transmission channel. Once a key is imported to the HUKS, its plaintext will not be exposed outside the HUKS throughout the lifecycle of the key. ### Importing a Key in Plaintext Use [huks.importKeyItem(keyAlias,options,callback)](../reference/apis/js-apis-huks.md#huksimportkeyitem9) to import a key in plaintext. You need to pass in the key alias in **keyAlias**, key material and attribute set in **options**, and **callback** to return the result asynchronously. For details about the APIs, see [HUKS](../reference/apis/js-apis-huks.md). 1. Determine the key alias. 2. Encapsulate the key material and key attribute set.
The key material must comply with [HUKS key material formats](./huks-appendix.md#key-material-formats). The **inData** value of [HuksOptions](../reference/apis/js-apis-huks.md#huksoptions) must be in the Uint8Array form. Encapsulate key attributes in [HuksParam](../reference/apis/js-apis-huks.md#huksparam), and use a **HuksParam** array to assign values to the **properties** field. The key attribute set must contain [HuksKeyAlg](../reference/apis/js-apis-huks.md#hukskeyalg), [HuksKeySize](../reference/apis/js-apis-huks.md#hukskeysize), and [HuksKeyPurpose](../reference/apis/js-apis-huks.md#hukskeypurpose). 3. Import the key. **Sample code** ```ts /* /* Import an AES key of 256 bits. */ */ /* Key */ let plainTextSize32 = new Uint8Array([ 0xfb, 0x8b, 0x9f, 0x12, 0xa0, 0x83, 0x19, 0xbe, 0x6a, 0x6f, 0x63, 0x2a, 0x7c, 0x86, 0xba, 0xca, 0x64, 0x0b, 0x88, 0x96, 0xe2, 0xfa, 0x77, 0xbc, 0x71, 0xe3, 0x0f, 0x0f, 0x9e, 0x3c, 0xe5, 0xf9 ]); /* * Determine the key alias. */ let keyAlias = 'AES256Alias_sample'; /* * Encapsulate the key attribute set and key material. */ let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES }; properties[1] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 }; properties[2] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT }; let options = { properties: properties, inData: plainTextSize32 }; /* * Import the key. */ try { huks.importKeyItem(keyAlias, options, function (error, data) { if (error) { console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); } else { console.info(`callback: importKeyItem success`); } }); } catch (error) { console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` **Verification** Check whether the key exists. If yes, the key is imported successfully. **Sample code** ```ts import huks from '@ohos.security.huks'; let keyAlias = 'AES256Alias_sample'; let isKeyExist; let keyProperties = new Array(); keyProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES, } let huksOptions = { properties: keyProperties, // It cannot be empty. inData: new Uint8Array(new Array()) // It cannot be empty. } try { huks.isKeyItemExist(keyAlias, huksOptions, function (error, data) { if (error) { console.error(`callback: isKeyItemExist failed, code: ${error.code}, msg: ${error.message}`); } else { if (data !== null && data.valueOf() !== null) { isKeyExist = data.valueOf(); console.info(`callback: isKeyItemExist success, isKeyExist = ${isKeyExist}`); } } }); } catch (error) { console.error(`callback: isKeyItemExist input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` ### Importing a Wrapped Key Compared with import of plaintext, secure import has complex key material and operations. The following figure illustrates the development process of secure import. **Figure 1** Development process of secure import ![huks_import_wrapped_key](figures/huks_import_wrapped_key.png) **Available APIs** You need to use the APIs for generating a key, exporting a public key, importing a wrapped key, and deleting a key in sequence. **Table 1** APIs for secure import | API | Description | | -------------------------------------- | ----------------------------| |generateKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void| Generates a key.| |exportKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void| Exports the public key of a key pair.| |importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback) : void|Imports a wrapped key.| |deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback) : void|Deletes a key.| >**NOTE**
The public key plaintext material returned by **exportKeyItem()** is encapsulated in X.509 format, and the key material to be imported by **importWrappedKeyItem()** must be encapsulated in **LengthData-Data** format. Specifically, the application needs to apply for a Uint8Array and encapsulate the Uint8Array in the sequence listed in the following table. **Table 2** Format of the wrapped key material | Content| Public Key Length (Lpk2)| Public Key pk2| k2 AAD2 Length LAAD2| k2 Encryption Parameter AAD2| k2 Nonce2 Length LNonce2| k2 Encryption Parameter Nonce2| | :--: |:----:|:----: |:----: | :----: | :----:|:----:| |Length| 4 bytes|Lpk2 bytes| 4 bytes| LAAD2 bytes| 4 bytes| LNonce2 bytes| | Content| k2 AEAD2 Length LAEAD2| k2 Encryption Parameter AEAD2| k3 Ciphertext Length Lk3_enc| k3 Ciphertext k3_enc| k3 AAD3 Length LAAD3| k3 Encryption Parameter AAD3| |Length| 4 bytes|LAEAD2 bytes| 4 bytes| Lk3_enc bytes| 4 bytes| LAAD3 bytes| | Content| k3 Nonce3 Length LNonce3| k3 Encryption Parameter Nonce3| k3 AEAD3 Length LAEAD3| k3 Encryption Parameter AEAD3| Length of **k1'_size** Lk1'_size| Key Plaintext Material Length k1'_size| |Length| 4 bytes|LNonce3 bytes| 4 bytes| LAEAD3 bytes| 4 bytes| Lk1'_size bytes| |Content|k1' Ciphertext Length Lk1'_enc| k1' ciphertext k1'_enc| | | | | |Length| 4 bytes|Lk1'_enc bytes| | | | | **How to Develop** The following example provides the development involving HUKS APIs (using the ECDH key agreement suite). The operations performed by the service are not included. 1. Convert the key material to the HUKS format. 2. Generate a wrapping key (a key used for secure import). 3. Export the public key material. 4. Wrap the key material to be imported. 5. Import the wrapped key material. 6. Delete the wrapping key. **Sample code** ```ts /* * Import an SM2 key and return the result by a callback. */ import huks from '@ohos.security.huks'; /* * Determine the key alias. */ let importAlias = "importAlias"; let wrapAlias = "wrappingKeyAlias"; let exportKey; /* * Convert the key material into a HUKS ECC-P-256 key pair for secure import. */ let inputEccPair = new Uint8Array([ 0x02, 0x00, 0x00, 0x00, // key algorithm: huks.HuksKeyAlg.HUKS_ALG_ECC = 2 0x00, 0x01, 0x00, 0x00, // key size: 256 bits 0x20, 0x00, 0x00, 0x00, // Coordinate x length: 32 bytes 0x20, 0x00, 0x00, 0x00, // Coordinate y length: 32 bytes 0x20, 0x00, 0x00, 0x00, // Coordinate z length: 32 bytes // Coordinate x 0xa5, 0xb8, 0xa3, 0x78, 0x1d, 0x6d, 0x76, 0xe0, 0xb3, 0xf5, 0x6f, 0x43, 0x9d, 0xcf, 0x60, 0xf6, 0x0b, 0x3f, 0x64, 0x45, 0xa8, 0x3f, 0x1a, 0x96, 0xf1, 0xa1, 0xa4, 0x5d, 0x3e, 0x2c, 0x3f, 0x13, // Coordinate y 0xd7, 0x81, 0xf7, 0x2a, 0xb5, 0x8d, 0x19, 0x3d, 0x9b, 0x96, 0xc7, 0x6a, 0x10, 0xf0, 0xaa, 0xbc, 0x91, 0x6f, 0x4d, 0xa7, 0x09, 0xb3, 0x57, 0x88, 0x19, 0x6f, 0x00, 0x4b, 0xad, 0xee, 0x34, 0x35, // Coordinate z 0xfb, 0x8b, 0x9f, 0x12, 0xa0, 0x83, 0x19, 0xbe, 0x6a, 0x6f, 0x63, 0x2a, 0x7c, 0x86, 0xba, 0xca, 0x64, 0x0b, 0x88, 0x96, 0xe2, 0xfa, 0x77, 0xbc, 0x71, 0xe3, 0x0f, 0x0f, 0x9e, 0x3c, 0xe5, 0xf9 ]); /* * Encapsulate the key attribute set. */ // Attribute set for the wrapping key. let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_ECC }; properties[1] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256 }; properties[2] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_UNWRAP }; properties[3] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 }; properties[4] = { tag: huks.HuksTag.HUKS_TAG_IMPORT_KEY_TYPE, value: huks.HuksImportKeyType.HUKS_KEY_TYPE_KEY_PAIR, }; let huksOptions = { properties: properties, inData: inputEccPair }; // Attribute set of the AES256 key to be imported. let importProperties = new Array(); importProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES }; importProperties[1] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256 }; importProperties[2] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT }; importProperties[3] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC }; importProperties[4] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE }; importProperties[5] = { tag: huks.HuksTag.HUKS_TAG_UNWRAP_ALGORITHM_SUITE, value: huks.HuksUnwrapSuite.HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING // Use the ECDH+AES256GCM suite. }; let importOptions = { properties: importProperties, inData: new Uint8Array(new Array()) }; // Export the public key of the key pair. function exportKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.exportKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicExportKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback export`); let throwObject = {isThrow: false}; try { await exportKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); exportKey = data.outData; }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } // Generate a wrapping key (the key is imported here). function importKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.importKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicImportKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter promise importKeyItem`); let throwObject = {isThrow: false}; try { await importKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: importKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } // Perform secure import. async function publicImportWrappedKey(keyAlias:string, wrappingKeyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback importWrappedKeyItem`); var throwObject = {isThrow: false}; try { await importWrappedKeyItem(keyAlias, wrappingKeyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: importWrappedKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: importWrappedKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: importWrappedKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function importWrappedKeyItem(keyAlias:string, wrappingKeyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.importWrappedKeyItem(keyAlias, wrappingKeyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } // Delete the wrapping key. function deleteKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.deleteKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicDeleteKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback deleteKeyItem`); let throwObject = {isThrow: false}; try { await deleteKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: deleteKeyItem key success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: deletKeeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function ImportWrappedKeyNormalTest() { console.info(`enter ImportWrapKey test`); /* * Generate a wrapping key (the key is imported here). */ await publicImportKeyFunc(wrapAlias, huksOptions); /* * Export the public key material of the wrapping key. */ await publicExportKeyFunc(wrapAlias, huksOptions); /*---------------------------------------------------------------------------------------------- * The processes of generating an ECC key pair, performing ECDH key agreement, generating a k3, and encrypting k1' and k3 on the service side are omitted. *----------------------------------------------------------------------------------------------*/ /* Encapsulate the key material to be imported. * Create the importOptions.inData field in the following format: * pk2 length (4 bytes) + pk2 data + AAD2 length (4 bytes) + AAD2 data + * Nonce2 length (4 bytes) + Nonce2 data + AEAD2 length (4 bytes) + AEAD2 data + * k3 ciphertext length (4 bytes) + k3 data + AAD3 length (4 bytes) + AAD3 data + * Nonce3 length (4 bytes) +Nonce3 data + AEAD3 length (4 bytes) + AEAD3 data + * k1'_size length (4 bytes) + k1'_size + k1'_enc length (4 bytes) + k1'_enc data */ let inputKey = new Uint8Array([ 0x5b, 0x00, 0x00, 0x00, // ECC-P-256 public key length (DER format defined in X.509): 91 // ECC-P-256 public key 0x30, 0x59, 0x30, 0x13, 0x06, 0x07, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01, 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07, 0x03, 0x42, 0x00, 0x04, 0xc0, 0xfe, 0x1c, 0x67, 0xde, 0x86, 0x0e, 0xfb, 0xaf, 0xb5, 0x85, 0x52, 0xb4, 0x0e, 0x1f, 0x6c, 0x6c, 0xaa, 0xc5, 0xd9, 0xd2, 0x4d, 0xb0, 0x8a, 0x72, 0x24, 0xa1, 0x99, 0xaf, 0xfc, 0x3e, 0x55, 0x5a, 0xac, 0x99, 0x3d, 0xe8, 0x34, 0x72, 0xb9, 0x47, 0x9c, 0xa6, 0xd8, 0xfb, 0x00, 0xa0, 0x1f, 0x9f, 0x7a, 0x41, 0xe5, 0x44, 0x3e, 0xb2, 0x76, 0x08, 0xa2, 0xbd, 0xe9, 0x41, 0xd5, 0x2b, 0x9e, 0x10, 0x00, 0x00, 0x00, // AAD2 length: 16 // AAD2 0xbf, 0xf9, 0x69, 0x41, 0xf5, 0x49, 0x85, 0x31, 0x35, 0x14, 0x69, 0x12, 0x57, 0x9c, 0xc8, 0xb7, 0x10, 0x00, 0x00, 0x00, // Nonce2 length: 16 // Nonce2 0x2d, 0xb7, 0xf1, 0x5a, 0x0f, 0xb8, 0x20, 0xc5, 0x90, 0xe5, 0xca, 0x45, 0x84, 0x5c, 0x08, 0x08, 0x10, 0x00, 0x00, 0x00, // AEAD2 length: 16 // AEAD2 0x43, 0x25, 0x1b, 0x2f, 0x5b, 0x86, 0xd8, 0x87, 0x04, 0x4d, 0x38, 0xc2, 0x65, 0xcc, 0x9e, 0xb7, 0x20, 0x00, 0x00, 0x00, // k3 ciphertext length: 32 // k3 ciphertext 0xf4, 0xe8, 0x93, 0x28, 0x0c, 0xfa, 0x4e, 0x11, 0x6b, 0xe8, 0xbd, 0xa8, 0xe9, 0x3f, 0xa7, 0x8f, 0x2f, 0xe3, 0xb3, 0xbf, 0xaf, 0xce, 0xe5, 0x06, 0x2d, 0xe6, 0x45, 0x5d, 0x19, 0x26, 0x09, 0xe7, 0x10, 0x00, 0x00, 0x00, // AAD3 length: 16 // AAD3 0xf4, 0x1e, 0x7b, 0x01, 0x7a, 0x84, 0x36, 0xa4, 0xa8, 0x1c, 0x0d, 0x3d, 0xde, 0x57, 0x66, 0x73, 0x10, 0x00, 0x00, 0x00, // Nonce3 length: 16 // Nonce3 0xe3, 0xff, 0x29, 0x97, 0xad, 0xb3, 0x4a, 0x2c, 0x50, 0x08, 0xb5, 0x68, 0xe1, 0x90, 0x5a, 0xdc, 0x10, 0x00, 0x00, 0x00, // AEAD3 length: 16 // AEAD3 0x26, 0xae, 0xdc, 0x4e, 0xa5, 0x6e, 0xb1, 0x38, 0x14, 0x24, 0x47, 0x1c, 0x41, 0x89, 0x63, 0x11, 0x04, 0x00, 0x00, 0x00, // Length of k1_size: 4 bytes // k1_size: 32 bytes 0x20, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, // Ciphertext length of the key to be imported: 32 bytes // Ciphertext of the key to be imported 0x0b, 0xcb, 0xa9, 0xa8, 0x5f, 0x5a, 0x9d, 0xbf, 0xa1, 0xfc, 0x72, 0x74, 0x87, 0x79, 0xf2, 0xf4, 0x22, 0x0c, 0x8a, 0x4d, 0xd8, 0x7e, 0x10, 0xc8, 0x44, 0x17, 0x95, 0xab, 0x3b, 0xd2, 0x8f, 0x0a ]); importOptions.inData = inputKey; /* * Import the wrapped key material. */ await publicImportWrappedKey(importAlias, wrapAlias, importOptions); /* * Delete the wrapping key. */ await publicDeleteKeyFunc(wrapAlias, huksOptions); } ``` **Verification** Check whether the key exists. If yes, the key is imported successfully. **Sample code** ```ts import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let keyAlias = 'importAlias'; let isKeyExist; let keyProperties = new Array(); keyProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES, } let huksOptions = { properties: keyProperties, // It cannot be empty. inData: new Uint8Array(new Array()) // It cannot be empty. } try { huks.isKeyItemExist(keyAlias, huksOptions, function (error, data) { if (error) { console.error(`callback: isKeyItemExist failed, code: ${error.code}, msg: ${error.message}`); } else { if (data !== null && data.valueOf() !== null) { isKeyExist = data.valueOf(); console.info(`callback: isKeyItemExist success, isKeyExist = ${isKeyExist}`); } } }); } catch (error) { console.error(`callback: isKeyItemExist input arg invalid, code: ${error.code}, msg: ${error.message}`); } ``` ## Common Key Operations **When to Use** To ensure data confidentiality and integrity, you may need to encrypt or decrypt data, generate or verify a signature, perform key agreement, and derive a key. The following describes common key operations. The following examples do not involve secondary identity access control. If secondary identity access control is involved, see [Key Access Control](#key-access-control). **General Development Process** The HUKS operates data based on key sessions. The general process is as follows: 1. (Mandatory) Use [huks.initSession()](../reference/apis/js-apis-huks.md#huksinitsession9) to initialize a key session.
You need to pass in the key alias and key operation parameters to initialize a key session, and obtain the session handle. The key operation parameters must contain the parameters required by the cipher algorithm, including the cipher algorithm, key size, key purpose, working mode, padding mode, hash mode, IV, nonce, and AAD. If access control is set for the key, other parameters are required. For details, see [Key Access Control](#key-access-control). 2. (Optional) Use [huks.updateSession()](../reference/apis/js-apis-huks.md#huksupdatesession9) to pass in data by segment.
Perform this step only if the data exceeds 100 KB or the cipher algorithm requires operations by data segment. Otherwise, skip this step. 3. (Mandatory) Use [huks.finishSession()](../reference/apis/js-apis-huks.md#huksfinishsession9) to finalize the key session operation.
Pass in the last data segment and perform the key session operation. If an error occurs during the process or the data passed in is not required, use [huks.abortSession()](../reference/apis/js-apis-huks.md#huksabortsession9) to abort the session. ### Encryption and Decryption ```ts /* * Encrypt and decrypt data using an SM4 128-bit key and return the result in a callback. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let srcKeyAlias = 'sm4_Key'; let IV = '0000000000000000'; let cipherInData = 'Hks_SM4_Cipher_Test_101010101010101010110_string'; let encryptUpdateResult = new Array(); let handle; let updateResult = new Array(); let finishOutData; /* Configure the key generation parameter set and key encryption parameter set. */ let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM4, } properties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, } properties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, } properties[3] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC, } properties[4] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } let huksOptions = { properties: properties, inData: new Uint8Array(new Array()) } let propertiesEncrypt = new Array(); propertiesEncrypt[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM4, } propertiesEncrypt[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT, } propertiesEncrypt[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, } propertiesEncrypt[3] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } propertiesEncrypt[4] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC, } propertiesEncrypt[5] = { tag: huks.HuksTag.HUKS_TAG_IV, value: StringToUint8Array(IV), } let encryptOptions = { properties: propertiesEncrypt, inData: new Uint8Array(new Array()) } /* Modify the key encryption parameter set to the decryption parameter set. */ propertiesEncrypt.splice(1, 1, { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, }); let decryptOptions = { properties: propertiesEncrypt, inData: new Uint8Array(new Array()) } function StringToUint8Array(str) { let arr = []; for (let i = 0, j = str.length; i < j; ++i) { arr.push(str.charCodeAt(i)); } return new Uint8Array(arr); } function Uint8ArrayToString(fileData) { let dataString = ''; for (let i = 0; i < fileData.length; i++) { dataString += String.fromCharCode(fileData[i]); } return dataString; } function generateKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicGenKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback generateKeyItem`); let throwObject = {isThrow: false}; try { await generateKeyItem(keyAlias, huksOptions, throwObject) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function initSession(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.initSession(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicInitFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback doInit`); let throwObject = {isThrow: false}; try { await initSession(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: doInit success, data = ${JSON.stringify(data)}`); handle = data.handle; }) .catch((error) => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doInit failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doInit input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function updateSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.updateSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicUpdateFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doUpdate`); let throwObject = {isThrow: false}; try { await updateSession(handle, huksOptions, throwObject) .then ((data) => { console.info(`callback: doUpdate success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doUpdate failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doUpdate input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function finishSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.finishSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicFinishFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doFinish`); let throwObject = {isThrow: false}; try { await finishSession(handle, huksOptions, throwObject) .then ((data) => { finishOutData = data.outData; console.info(`callback: doFinish success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doFinish failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doFinish input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function deleteKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.deleteKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicDeleteKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback deleteKeyItem`); let throwObject = {isThrow: false}; try { await deleteKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: deleteKeyItem key success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: deletKeeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function testSm4Cipher() { /* Generate a key. */ await publicGenKeyFunc(srcKeyAlias, huksOptions); /* Encrypt the key. */ await publicInitFunc(srcKeyAlias, encryptOptions); encryptOptions.inData = StringToUint8Array(cipherInData); await publicUpdateFunc(handle, encryptOptions); encryptUpdateResult = updateResult; encryptOptions.inData = new Uint8Array(new Array()); await publicFinishFunc(handle, encryptOptions); if (finishOutData === cipherInData) { console.info('test finish encrypt err '); } else { console.info('test finish encrypt success'); } /* Decrypt the key. */ await publicInitFunc(srcKeyAlias, decryptOptions); decryptOptions.inData = new Uint8Array(encryptUpdateResult); await publicUpdateFunc(handle, decryptOptions); decryptOptions.inData = new Uint8Array(new Array()); await publicFinishFunc(handle, decryptOptions); if (finishOutData === cipherInData) { console.info('test finish decrypt success '); } else { console.info('test finish decrypt err'); } await publicDeleteKeyFunc(srcKeyAlias, huksOptions); } ``` ### Signing and Signature Verification ```ts /* * Generate and verify a signature using an SM2 key and return the result in a callback. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let generateKeyAlias = 'sm2_Key'; let importKeyAlias = 'importKeyAlias'; let signVerifyInData = 'signVerifyInDataForTest'; let handle; let exportKey; let finishOutData; /* Configure the parameter set used for generating the key. */ let generateKeyProperties = new Array(); generateKeyProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM2, } generateKeyProperties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY, } generateKeyProperties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM2_KEY_SIZE_256, } generateKeyProperties[3] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SM3, } let genrateKeyOptions = { properties: generateKeyProperties, inData: new Uint8Array(new Array()) } /* Configure the parameter set used for signing. */ let signProperties = new Array(); signProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM2, } signProperties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN } signProperties[2] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SM3, } signProperties[3] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM2_KEY_SIZE_256, } let signOptions = { properties: signProperties, inData: new Uint8Array(new Array()) } /* Configure the parameter set used for signature verification. */ let verifyProperties = new Array(); verifyProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM2, } verifyProperties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY } verifyProperties[2] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SM3, } verifyProperties[3] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM2_KEY_SIZE_256, } let verifyOptions = { properties: verifyProperties, inData: new Uint8Array(new Array()) } function StringToUint8Array(str) { let arr = []; for (let i = 0, j = str.length; i < j; ++i) { arr.push(str.charCodeAt(i)); } return new Uint8Array(arr); } function generateKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicGenKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback generateKeyItem`); let throwObject = {isThrow: false}; try { await generateKeyItem(keyAlias, huksOptions, throwObject) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function initSession(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.initSession(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicInitFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback doInit`); let throwObject = {isThrow: false}; try { await initSession(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: doInit success, data = ${JSON.stringify(data)}`); handle = data.handle; }) .catch((error) => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doInit failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doInit input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function updateSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.updateSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicUpdateFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doUpdate`); let throwObject = {isThrow: false}; try { await updateSession(handle, huksOptions, throwObject) .then ((data) => { console.info(`callback: doUpdate success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doUpdate failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doUpdate input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function finishSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.finishSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicFinishFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doFinish`); let throwObject = {isThrow: false}; try { await finishSession(handle, huksOptions, throwObject) .then ((data) => { finishOutData = data.outData; console.info(`callback: doFinish success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doFinish failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doFinish input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function exportKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.exportKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicExportKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback export`); let throwObject = {isThrow: false}; try { await exportKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); exportKey = data.outData; }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function importKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.importKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicImportKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter promise importKeyItem`); let throwObject = {isThrow: false}; try { await importKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: importKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: importKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: importKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function deleteKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.deleteKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicDeleteKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback deleteKeyItem`); let throwObject = {isThrow: false}; try { await deleteKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: deleteKeyItem key success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: deletKeeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function testSm2SignVerify() { /* Generate a key. */ await publicGenKeyFunc(generateKeyAlias, genrateKeyOptions); /* Generate a signature. */ let signHandle; let signFinishOutData; await publicInitFunc(generateKeyAlias, signOptions); signHandle = handle; signOptions.inData = StringToUint8Array(signVerifyInData) await publicUpdateFunc(signHandle, signOptions); signOptions.inData = new Uint8Array(new Array()); await publicFinishFunc(signHandle, signOptions); signFinishOutData = finishOutData; /* Export the key. */ await publicExportKeyFunc(generateKeyAlias, genrateKeyOptions); /* Import the key. */ verifyOptions.inData = exportKey; await publicImportKeyFunc(importKeyAlias, verifyOptions); /* Verify the signature. */ let verifyHandle; await publicInitFunc(importKeyAlias, verifyOptions); verifyHandle = handle; verifyOptions.inData = StringToUint8Array(signVerifyInData) await publicUpdateFunc(verifyHandle, verifyOptions); verifyOptions.inData = signFinishOutData; await publicFinishFunc(verifyHandle, verifyOptions); await publicDeleteKeyFunc(generateKeyAlias, genrateKeyOptions); await publicDeleteKeyFunc(importKeyAlias, genrateKeyOptions); } ``` ### Key Agreement ```ts /* * Perform key agreement using an X25519 256-bit TEMP key and return the result in a callback. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let srcKeyAliasFirst = "AgreeX25519KeyFirstAlias"; let srcKeyAliasSecond = "AgreeX25519KeySecondAlias"; let agreeX25519InData = 'AgreeX25519TestIndata'; let finishOutData; let handle; let exportKey; let exportKeyFrist; let exportKeySecond; /* Configure the parameter set used for generating the key. */ let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_X25519, } properties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE, } properties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_CURVE25519_KEY_SIZE_256, } properties[3] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_NONE, } properties[4] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } properties[5] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC, } let HuksOptions = { properties: properties, inData: new Uint8Array(new Array()) } /* Configure parameters for the first key agreement. */ let finishProperties = new Array(); finishProperties[0] = { tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, value: huks.HuksKeyStorageType.HUKS_STORAGE_TEMP, } finishProperties[1] = { tag: huks.HuksTag.HUKS_TAG_IS_KEY_ALIAS, value: true } finishProperties[2] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES, } finishProperties[3] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256, } finishProperties[4] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, } finishProperties[5] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_NONE, } finishProperties[6] = { tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS, value: StringToUint8Array(srcKeyAliasFirst+ 'final'), } finishProperties[7] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } finishProperties[8] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_ECB, } let finishOptionsFrist = { properties: finishProperties, inData: StringToUint8Array(agreeX25519InData) } /* Configure parameters for the second key agreement. */ let finishOptionsSecond = { properties: finishProperties, inData: StringToUint8Array(agreeX25519InData) } finishOptionsSecond.properties.splice(6, 1, { tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS, value: StringToUint8Array(srcKeyAliasSecond + 'final'), }) function StringToUint8Array(str) { let arr = []; for (let i = 0, j = str.length; i < j; ++i) { arr.push(str.charCodeAt(i)); } return new Uint8Array(arr); } function generateKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicGenKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback generateKeyItem`); let throwObject = {isThrow: false}; try { await generateKeyItem(keyAlias, huksOptions, throwObject) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function initSession(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.initSession(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicInitFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback doInit`); let throwObject = {isThrow: false}; try { await initSession(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: doInit success, data = ${JSON.stringify(data)}`); handle = data.handle; }) .catch((error) => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doInit failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doInit input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function updateSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.updateSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicUpdateFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doUpdate`); let throwObject = {isThrow: false}; try { await updateSession(handle, huksOptions, throwObject) .then ((data) => { console.info(`callback: doUpdate success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doUpdate failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doUpdate input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function finishSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.finishSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicFinishFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doFinish`); let throwObject = {isThrow: false}; try { await finishSession(handle, huksOptions, throwObject) .then ((data) => { finishOutData = data.outData; console.info(`callback: doFinish success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doFinish failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doFinish input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function exportKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.exportKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicExportKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback export`); let throwObject = {isThrow: false}; try { await exportKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`); exportKey = data.outData; }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: exportKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: exportKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function deleteKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.deleteKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicDeleteKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback deleteKeyItem`); let throwObject = {isThrow: false}; try { await deleteKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: deleteKeyItem key success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: deletKeeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function testAgree() { /* 1. Generate two keys and export them. */ await publicGenKeyFunc(srcKeyAliasFirst, HuksOptions); await publicGenKeyFunc(srcKeyAliasSecond, HuksOptions); await publicExportKeyFunc(srcKeyAliasFirst, HuksOptions); exportKeyFrist = exportKey; await publicExportKeyFunc(srcKeyAliasFirst, HuksOptions); exportKeySecond = exportKey; /* Perform key agreement for the first. */ await publicInitFunc(srcKeyAliasFirst, HuksOptions); HuksOptions.inData = exportKeySecond; await publicUpdateFunc(handle, HuksOptions); await publicFinishFunc(handle, finishOptionsFrist); /* Perform key agreement for the second key. */ await publicInitFunc(srcKeyAliasSecond, HuksOptions); HuksOptions.inData = exportKeyFrist; await publicUpdateFunc(handle, HuksOptions); await publicFinishFunc(handle, finishOptionsSecond); await publicDeleteKeyFunc(srcKeyAliasFirst, HuksOptions); await publicDeleteKeyFunc(srcKeyAliasSecond, HuksOptions); } ``` ### Key Derivation ```ts /* * The following uses the Promise() operation of an HKDF256 key as an example. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let srcKeyAlias = "hkdf_Key"; let deriveHkdfInData = "deriveHkdfTestIndata"; let handle; let finishOutData; let HuksKeyDeriveKeySize = 32; /* Configure the parameter set used for generating the key. */ let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES, } properties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DERIVE, } properties[2] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256, } properties[3] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128, } let huksOptions = { properties: properties, inData: new Uint8Array(new Array()) } /* Configure the parameter set used for init(). */ let initProperties = new Array(); initProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_HKDF, } initProperties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DERIVE, } initProperties[2] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256, } initProperties[3] = { tag: huks.HuksTag.HUKS_TAG_DERIVE_KEY_SIZE, value: HuksKeyDeriveKeySize, } let initOptions = { properties: initProperties, inData: new Uint8Array(new Array()) } /* Configure the parameter set used for finish(). */ let finishProperties = new Array(); finishProperties[0] = { tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT, } finishProperties[1] = { tag: huks.HuksTag.HUKS_TAG_IS_KEY_ALIAS, value: true, } finishProperties[2] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES, } finishProperties[3] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256, } finishProperties[4] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, } finishProperties[5] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_NONE, } finishProperties[6] = { tag: huks.HuksTag.HUKS_TAG_KEY_ALIAS, value: StringToUint8Array(srcKeyAlias), } finishProperties[7] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } finishProperties[8] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_ECB, } let finishOptions = { properties: finishProperties, inData: new Uint8Array(new Array()) } function StringToUint8Array(str) { let arr = []; for (let i = 0, j = str.length; i < j; ++i) { arr.push(str.charCodeAt(i)); } return new Uint8Array(arr); } function generateKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicGenKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback generateKeyItem`); let throwObject = {isThrow: false}; try { await generateKeyItem(keyAlias, huksOptions, throwObject) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function initSession(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.initSession(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicInitFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback doInit`); let throwObject = {isThrow: false}; try { await initSession(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: doInit success, data = ${JSON.stringify(data)}`); handle = data.handle; }) .catch((error) => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doInit failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doInit input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function updateSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.updateSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicUpdateFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doUpdate`); let throwObject = {isThrow: false}; try { await updateSession(handle, huksOptions, throwObject) .then ((data) => { console.info(`callback: doUpdate success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doUpdate failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doUpdate input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function finishSession(handle:number, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.finishSession(handle, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicFinishFunc(handle:number, huksOptions:huks.HuksOptions) { console.info(`enter callback doFinish`); let throwObject = {isThrow: false}; try { await finishSession(handle, huksOptions, throwObject) .then ((data) => { finishOutData = data.outData; console.info(`callback: doFinish success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doFinish failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doFinish input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function deleteKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.deleteKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicDeleteKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback deleteKeyItem`); let throwObject = {isThrow: false}; try { await deleteKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: deleteKeyItem key success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: deleteKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: deletKeeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function testDerive() { /* Generate a key. */ await publicGenKeyFunc(srcKeyAlias, huksOptions); /* Derive a key. */ await publicInitFunc(srcKeyAlias, initOptions); initOptions.inData = StringToUint8Array(deriveHkdfInData); await publicUpdateFunc(handle, initOptions); await publicFinishFunc(handle, finishOptions); await publicDeleteKeyFunc(srcKeyAlias, huksOptions); } ``` ## Key Access Control The HUKS provides comprehensive key access control to prevent unauthorized access. Services can access only their own keys, that is, the keys generated or imported through HUKS. In addition, the HUKS supports user identity authentication for security-sensitive services. Users can use the service keys only after the authentication (PIN or biometric authentication) is successful. The HUKS also restricts the key usage. For example, the AES keys can only be used for encryption and decryption, and the RSA keys can only be used for signing and signature verification. **User Identity Authentication** When generating or importing a key, you can enable user identity authentication for the key use. You can specify a subset of credentials (lock screen password, fingerprint, and face) for user identity authentication. After a key is generated or imported, unauthorized key access can be prevented even if the application process is attacked. Key access control applies to security-sensitive scenarios, such as password-free login, password-free payment, and automatic password filling. In addition to user identity authentication, the authorized key access type (key expiration condition) must be either of the following types: - Invalidate the key when the screen lock password is cleared.
This type takes effect only when a screen lock password has been set. If the screen lock password is cleared, the key becomes invalid permanently. The key will not be invalidated if the screen lock password is modified. Use this type for user-related data protection or access based on screen lock passwords. - Invalidate the key when new biometric enrollments are added.
This type takes effect only when at least one biometric feature (such as fingerprint) has been enrolled. The key becomes invalid permanently once a new biometric feature is enrolled. The key will not be invalidated if the biometric feature is deleted. You can use this type for scenarios, such as password-free login or payment. To ensure the validity of the user authentication result, the HUKS supports challenge value verification. Before user identity authentication, obtain the challenge (in the [HuksSessionHandle](../reference/apis/js-apis-huks.md#hukssessionhandle9) returned by [huks.initSession()](../reference/apis/js-apis-huks.md#huksinitsession9)) from the HUKS and pass in the challenge in [userIAM_userAuth.getAuthInstance](../reference/apis/js-apis-useriam-userauth.md#authinstance9). The challenge value of the authentication token is then verified during key operations. **How to Develop** If secondary user identity authentication is enabled for a key, initialize the key session and obtain the challenge value. Then, pass the challenge value to **userIAM_userAuth.getAuthInstance()** for user identity authentication. After the authentication is successful, an authentication token is obtained. The authentication token can be used to perform key operations. ![huks_key_user_auth_work_flow](./figures/huks_key_user_auth_work_flow.png) **Available APIs** 1. [HuksUserAuthType](../reference/apis/js-apis-huks.md#huksuserauthtype9), [HuksAuthAccessType](../reference/apis/js-apis-huks.md#huksauthaccesstype9), and [HuksChallengeType](../reference/apis/js-apis-huks.md#hukschallengetype9) in the key attribute set are mandatory for key generation/import. **Table 3** User authentication types | Name | Value | Description | | ------------------------------- |---|------------------------ | | HUKS_USER_AUTH_TYPE_FINGERPRINT |0x0001 | Fingerprint authentication. | | HUKS_USER_AUTH_TYPE_FACE |0x0002 | Facial authentication. | | HUKS_USER_AUTH_TYPE_PIN |0x0004 | PIN authentication. | > **NOTE** > > You can specify any or a combination of the three authentication types. **Table 4** Secure access types | Name | Value | Description | | --------------------------------------- | ----- | ------------------------------------------------------------ | | HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | 1 | Invalidates the key after the screen lock password is cleared. | | HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | 2 | Invalidates the key after a biometric enrollment is added. The user authentication types must include the biometric authentication. | | | | | > **NOTE** > > **HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD** and **HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL** are mutually exclusive. **Table 5** Challenge types | Name | Value | Description | | ------------------------------- | ---- | ------------------------------ | | HUKS_CHALLENGE_TYPE_NORMAL | 0 | Normal challenge, which requires an independent user authentication for each use of the key.| | HUKS_CHALLENGE_TYPE_CUSTOM | 1 | Custom challenge, which supports only one user authentication for multiple keys.| | HUKS_CHALLENGE_TYPE_NONE | 2 | No challenge is required during user authentication.| > **NOTICE** > > The three challenge types are mutually exclusive. > > If the challenge type is **HUKS_CHALLENGE_TYPE_NONE**, no challenge is required. However, the key can be accessed only within a specified time period (set by **HUKS_TAG_AUTH_TIMEOUT**) after a successful authentication. The maximum value of **HUKS_TAG_AUTH_TIMEOUT** is 60 seconds. 2. To use a key, initialize the key session, and determine whether a challenge is required based on the challenge type specified when the key is generated or imported. **Table 6** APIs for using a key | API | Description | | -------------------------------------- | ----------------------------| |initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void| Initializes the key session and obtains the challenge value.| |updateSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void| Operates data by segment and passes the authentication token.| |finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void| Finalizes the key session.| **How to Develop** 1. Generate a key and specify user authentication attributes. ```ts import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let keyAlias = 'dh_key_fingerprint_access'; let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM4, } properties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, } properties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, } properties[3] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC, } properties[4] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } // Enable fingerprint authentication. properties[5] = { tag: huks.HuksTag.HUKS_TAG_USER_AUTH_TYPE, value: huks.HuksUserAuthType.HUKS_USER_AUTH_TYPE_FINGERPRINT } // Set the key expiration type. Invalidate the key when a new biometric feature (fingerprint) is enrolled. properties[6] = { tag: huks.HuksTag.HUKS_TAG_KEY_AUTH_ACCESS_TYPE, value: huks.HuksAuthAccessType.HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL } // Use the default challenge type. properties[7] = { tag: huks.HuksTag.HUKS_TAG_CHALLENGE_TYPE, value: huks.HuksChallengeType.HUKS_CHALLENGE_TYPE_NORMAL } let huksOptions = { properties: properties, inData: new Uint8Array(new Array()) } /* * Generate a key. */ function generateKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicGenKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback generateKeyItem`); let throwObject = {isThrow: false}; try { await generateKeyItem(keyAlias, huksOptions, throwObject) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function TestGenKeyForFingerprintAccessControl() { await publicGenKeyFunc(keyAlias, huksOptions); } ``` 2. Initialize the key session to obtain a challenge, and initiate fingerprint authentication to obtain an authentication token. ```ts import huks from '@ohos.security.huks'; import userIAM_userAuth from '@ohos.userIAM.userAuth'; /* * Determine the key alias and encapsulate the key attribute set. */ let srcKeyAlias = 'sm4_key_fingerprint_access'; let handle; let challenge; let fingerAuthToken; let authType = userIAM_userAuth.UserAuthType.FINGERPRINT; let authTrustLevel = userIAM_userAuth.AuthTrustLevel.ATL1; /* Configure the key generation parameter set and key encryption parameter set. */ let properties = new Array(); properties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM4, } properties[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT, } properties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, } properties[3] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC, } properties[4] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } let huksOptions = { properties: properties, inData: new Uint8Array(new Array()) } function initSession(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.initSession(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicInitFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback doInit`); let throwObject = {isThrow: false}; try { await initSession(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: doInit success, data = ${JSON.stringify(data)}`); handle = data.handle; challenge = data.challenge; }) .catch((error) => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doInit failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doInit input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function userIAMAuthFinger(huksChallenge:Uint8Array) { // Obtain an authentication object. let auth; try { auth = userIAM_userAuth.getAuthInstance(huksChallenge, authType, authTrustLevel); console.log("get auth instance success"); } catch (error) { console.log("get auth instance failed" + error); } // Subscribe to the authentication result. try { auth.on("result", { callback: (result: userIAM_userAuth.AuthResultInfo) => { /* The authentication is successful, and the authentication token is obtained. */ fingerAuthToken = result.token; } }); console.log("subscribe authentication event success"); } catch (error) { console.log("subscribe authentication event failed " + error); } // Start user authentication. try { auth.start(); console.info("authV9 start auth success"); } catch (error) { console.info("authV9 start auth failed, error = " + error); } } async function testInitAndAuthFinger() { /* Initialize the key session to obtain a challenge. */ await publicInitFunc(srcKeyAlias, huksOptions); /* Invoke userIAM to perform user identity authentication. */ userIAMAuthFinger(challenge); } ``` 3. Pass in the authentication token to perform data operations. ```ts /* * The following uses an SM4 128-bit key and callback-based APIs as an example. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let srcKeyAlias = 'sm4_key_fingerprint_access'; let IV = '1234567890123456'; let cipherInData = 'Hks_SM4_Cipher_Test_101010101010101010110_string'; let handle; let fingerAuthToken; let updateResult = new Array(); let finishOutData; /* Configure the key generation parameter set and key encryption parameter set. */ let propertiesEncrypt = new Array(); propertiesEncrypt[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_SM4, } propertiesEncrypt[1] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT, } propertiesEncrypt[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128, } propertiesEncrypt[3] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE, } propertiesEncrypt[4] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_CBC, } propertiesEncrypt[5] = { tag: huks.HuksTag.HUKS_TAG_IV, value: StringToUint8Array(IV), } let encryptOptions = { properties: propertiesEncrypt, inData: new Uint8Array(new Array()) } function StringToUint8Array(str) { let arr = []; for (let i = 0, j = str.length; i < j; ++i) { arr.push(str.charCodeAt(i)); } return new Uint8Array(arr); } function updateSession(handle:number, huksOptions:huks.HuksOptions, token:Uint8Array, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.updateSession(handle, huksOptions, token, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicUpdateFunc(handle:number, token:Uint8Array, huksOptions:huks.HuksOptions) { console.info(`enter callback doUpdate`); let throwObject = {isThrow: false}; try { await updateSession(handle, huksOptions, token, throwObject) .then ((data) => { console.info(`callback: doUpdate success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doUpdate failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doUpdate input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function finishSession(handle:number, huksOptions:huks.HuksOptions, token:Uint8Array, throwObject) : Promise { return new Promise((resolve, reject) => { try { huks.finishSession(handle, huksOptions, token, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicFinishFunc(handle:number, token:Uint8Array, huksOptions:huks.HuksOptions) { console.info(`enter callback doFinish`); let throwObject = {isThrow: false}; try { await finishSession(handle, huksOptions, token, throwObject) .then ((data) => { finishOutData = data.outData; console.info(`callback: doFinish success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: doFinish failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: doFinish input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function testSm4Cipher() { encryptOptions.inData = StringToUint8Array(cipherInData); /* Pass in the authentication token. */ await publicUpdateFunc(handle, fingerAuthToken, encryptOptions); encryptUpdateResult = updateResult; encryptOptions.inData = new Uint8Array(new Array()); /* Pass in the authentication token. */ await publicFinishFunc(handle, fingerAuthToken, encryptOptions); if (finishOutData === cipherInData) { console.info('test finish encrypt err '); } else { console.info('test finish encrypt success'); } } ``` ## Key Attestation The HUKS provides attestation for the public keys of asymmetric key pairs. The HUKS can issue a certificate for the public key of an asymmetric key pair stored in the HUKS using the public key infrastructure (PKI) certificate chain technology. The certificate can prove the validity of the public key. The service can use the root CA certificate provided by the OpenHarmony to verify the key certificate issued by the HUKS level by level to ensure that the public key and private key in the certificate are from a trusted hardware device and stored in the HUKS. **How to Develop** 1. Pass in the key alias and the attribute tag of the key to be attested. 2. Call a HUKS API to generate an X.509 certificate chain, which consists of the root CA certificate, device CA certificate, device certificate, and key certificate in sequence, for the application. 3. Send the certificate chain to a trusted server. The server parses and verifies the validity of the certificate chain and whether a single certificate is revoked. **Available APIs** **Table 7** APIs for key attestation | API | Description | | -------------------------------------- | ----------------------------| |attestKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void| Attests a key.| **How to Develop** ```ts /* * Attest a key and return the result in a callback. */ import huks from '@ohos.security.huks'; /* * Determine the key alias and encapsulate the key attribute set. */ let keyAliasString = "key attest"; let aliasString = keyAliasString; let aliasUint8 = StringToUint8Array(keyAliasString); let securityLevel = StringToUint8Array('sec_level'); let challenge = StringToUint8Array('challenge_data'); let versionInfo = StringToUint8Array('version_info'); let attestCertChain; let genKeyProperties = new Array(); genKeyProperties[0] = { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_RSA }; genKeyProperties[1] = { tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG, value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT }; genKeyProperties[2] = { tag: huks.HuksTag.HUKS_TAG_KEY_SIZE, value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048 }; genKeyProperties[3] = { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY }; genKeyProperties[4] = { tag: huks.HuksTag.HUKS_TAG_DIGEST, value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256 }; genKeyProperties[5] = { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_PSS }; genKeyProperties[6] = { tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE, value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT }; genKeyProperties[7] = { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_ECB }; let genOptions = { properties: genKeyProperties }; let attestKeyproperties = new Array(); attestKeyproperties[0] = { tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, value: securityLevel }; attestKeyproperties[1] = { tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, value: challenge }; attestKeyproperties[2] = { tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, value: versionInfo }; attestKeyproperties[3] = { tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, value: aliasUint8 }; let huksOptions = { properties: attestKeyproperties }; function StringToUint8Array(str) { let arr = []; for (let i = 0, j = str.length; i < j; ++i) { arr.push(str.charCodeAt(i)); } return new Uint8Array(arr); } function generateKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) { return new Promise((resolve, reject) => { try { huks.generateKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicGenKeyFunc(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback generateKeyItem`); let throwObject = {isThrow: false}; try { await generateKeyItem(keyAlias, huksOptions, throwObject) .then((data) => { console.info(`callback: generateKeyItem success, data = ${JSON.stringify(data)}`); }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: generateKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: generateKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } function attestKeyItem(keyAlias:string, huksOptions:huks.HuksOptions, throwObject) : Promise{ return new Promise((resolve, reject) => { try { huks.attestKeyItem(keyAlias, huksOptions, function (error, data) { if (error) { reject(error); } else { resolve(data); } }); } catch (error) { throwObject.isThrow = true; throw(error); } }); } async function publicAttestKey(keyAlias:string, huksOptions:huks.HuksOptions) { console.info(`enter callback attestKeyItem`); let throwObject = {isThrow: false}; try { await attestKeyItem(keyAlias, huksOptions, throwObject) .then ((data) => { console.info(`callback: attestKeyItem success, data = ${JSON.stringify(data)}`); if (data !== null && data.certChains !== null) { attestCertChain = data.certChains; } }) .catch(error => { if (throwObject.isThrow) { throw(error); } else { console.error(`callback: attestKeyItem failed, code: ${error.code}, msg: ${error.message}`); } }); } catch (error) { console.error(`callback: attestKeyItem input arg invalid, code: ${error.code}, msg: ${error.message}`); } } async function AttestKeyTest() { await publicGenKeyFunc(aliasString, genOptions); await publicAttestKey(aliasString, huksOptions); console.info('attest certChain data: ' + attestCertChain) } ``` ## FAQs ### Cannot find name 'huks'. **security.huks.d.ts** is not imported. To solve the problem, add **import huks from '@ohos.security.huks'**. ### Property 'finishSession' does not exist on type 'typeof huks'. Did you mean 'finish'? **finishSession()** is supported from API version 9. Update the SDK version or use the latest **security.huks.d.ts** file.