diff --git a/en/application-dev/reference/apis/js-apis-huks.md b/en/application-dev/reference/apis/js-apis-huks.md index b66ae2d8b74dd4e1fe13cc917269e88b5d088030..1dbbe5893d836b0772c07251bbfc19ac59eb1e1e 100644 --- a/en/application-dev/reference/apis/js-apis-huks.md +++ b/en/application-dev/reference/apis/js-apis-huks.md @@ -4,7 +4,7 @@ > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. -Provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. +The **KUKS** module provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. The keys managed by OpenHarmony Universal KeyStore (HUKS) can be imported by applications or generated by calling the HUKS APIs. ## Modules to Import @@ -59,6 +59,11 @@ Enumerates the error codes. | HUKS_ERROR_NEW_ROOT_KEY_MATERIAL_EXIST | -36 |New root key material exists.| | HUKS_ERROR_UPDATE_ROOT_KEY_MATERIAL_FAIL | -37 |Failed to update the root key material.| | HUKS_ERROR_VERIFICATION_FAILED | -38 |Failed to verify the certificate chain.| +| HUKS_ERROR_GET_USERIAM_SECINFO_FAILED9+ | -40 |Failed to obtain the security attribute information of the current user.| +| HUKS_ERROR_GET_USERIAM_AUTHINFO_FAILED9+ | -41 |Failed to obtain the authentication information of the current user.| +| HUKS_ERROR_USER_AUTH_TYPE_NOT_SUPPORT9+ | -42 |The access control of the current authentication type is not supported.| +| HUKS_ERROR_KEY_AUTH_FAILED9+ | -43 |The access control authentication has failed.| +| HUKS_ERROR_DEVICE_NO_CREDENTIAL9+ | -44 |No credential has been enrolled for the device.| | HUKS_ERROR_CHECK_GET_ALG_FAIL | -100 |Failed to check whether the ALG is obtained. | | HUKS_ERROR_CHECK_GET_KEY_SIZE_FAIL | -101 |Failed to check whether the key size is obtained.| | HUKS_ERROR_CHECK_GET_PADDING_FAIL | -102 |Failed to check whether padding is obtained.| @@ -100,7 +105,7 @@ Enumerates the key purposes. | Name | Value | Description | | ------------------------ | ---- | -------------------------------- | | HUKS_KEY_PURPOSE_ENCRYPT | 1 | Used to encrypt plaintext.| -| HUKS_KEY_PURPOSE_DECRYPT | 2 | Used to decrypt cipher text.| +| HUKS_KEY_PURPOSE_DECRYPT | 2 | Used to decrypt the cipher text.| | HUKS_KEY_PURPOSE_SIGN | 4 | Used to sign data. | | HUKS_KEY_PURPOSE_VERIFY | 8 | Used to verify the signed data. | | HUKS_KEY_PURPOSE_DERIVE | 16 | Used to derive a key. | @@ -149,7 +154,7 @@ Enumerates the cipher modes. | Name | Value | Description | | ------------- | ---- | --------------------- | -| HUKS_MODE_ECB | 1 | Electronic Code Block (ECB) mode| +| HUKS_MODE_ECB | 1 | Electronic Code bLock (ECB) mode| | HUKS_MODE_CBC | 2 | Cipher Block Chaining (CBC) mode| | HUKS_MODE_CTR | 3 | Counter (CTR) mode| | HUKS_MODE_OFB | 4 | Output Feedback (OFB) mode| @@ -278,6 +283,64 @@ Enumerates the types of keys to import. By default, a public key is imported. Th | HUKS_KEY_TYPE_PRIVATE_KEY | 1 | Private key | | HUKS_KEY_TYPE_KEY_PAIR | 2 | Public and private key pair| +## HuksUserAuthType9+ + +Enumerates the user authentication types. + +**System capability**: SystemCapability.Security.Huks + +| Name | Value | Description | +| ------------------------------- | ---- | ------------------------- | +| HUKS_USER_AUTH_TYPE_FINGERPRINT | 1 | Fingerprint authentication. | +| HUKS_USER_AUTH_TYPE_FACE | 2 | Facial authentication.| +| HUKS_USER_AUTH_TYPE_PIN | 4 | PIN authentication.| + +## HuksAuthAccessType9+ + +Enumerates access control types. + +**System capability**: SystemCapability.Security.Huks + +| Name | Value | Description | +| --------------------------------------- | ---- | ------------------------------------------------ | +| HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | 1 | The key is invalid after the password is cleared. | +| HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | 2 | The key is invalid after a new biometric feature is added.| + +## HuksChallengeType9+ + +Enumerates the types of the challenges generated when a key is used. + +**System capability**: SystemCapability.Security.Huks + +| Name | Value | Description | +| ------------------------------- | ---- | ------------------------------ | +| HUKS_CHALLENGE_TYPE_NORMAL | 0 | Normal challenge, which is of 32 bytes by default.| +| HUKS_CHALLENGE_TYPE_CUSTOM | 1 | Custom challenge, which supports only one authentication for multiple keys.| +| HUKS_CHALLENGE_TYPE_NONE | 2 | Challenge is not required.| + +## HuksChallengePosition9+ + +Enumerates the positions of the 8-byte custom challenges. + +**System capability**: SystemCapability.Security.Huks + +| Name | Value | Description | +| ------------------------------- | ---- | ------------------------------ | +| HUKS_CHALLENGE_POS_0 | 0 | Bytes 0 to 7 indicate the valid challenge of the key.| +| HUKS_CHALLENGE_POS_1 | 1 | Bytes 8 to 15 indicate the valid challenge of the key.| +| HUKS_CHALLENGE_POS_2 | 2 | Bytes 16 to 23 indicate the valid challenge of the key.| +| HUKS_CHALLENGE_POS_3 | 3 | Bytes 24 to 31 indicate the valid challenge of the key.| + +## HuksSecureSignType9+ + +Defines the signature type of the key generated or imported. + +**System capability**: SystemCapability.Security.Huks + +| Name | Value | Description | +| ------------------------------ | ---- | ------------------------------------------------------------ | +| HUKS_SECURE_SIGN_WITH_AUTHINFO | 1 | The signature carries authentication information. This field is specified when a key is generated or imported. When the key is used to sign data, the data will be added with the authentication information and then be signed.| + ## HuksTagType Enumerates the tag data types. @@ -287,12 +350,12 @@ Enumerates the tag data types. | Name | Value | Description | | --------------------- | ------- | --------------------------------------- | -| HUKS_TAG_TYPE_INVALID | 0 << 28 | Invalid tag type | -| HUKS_TAG_TYPE_INT | 1 << 28 | Number of the int type | -| HUKS_TAG_TYPE_UINT | 2 << 28 | Number of the uint type| -| HUKS_TAG_TYPE_ULONG | 3 << 28 | BigInt | -| HUKS_TAG_TYPE_BOOL | 4 << 28 | Boolean | -| HUKS_TAG_TYPE_BYTES | 5 << 28 | Uint8Array | +| HUKS_TAG_TYPE_INVALID | 0 << 28 | Invalid tag type. | +| HUKS_TAG_TYPE_INT | 1 << 28 | Number of the int type. | +| HUKS_TAG_TYPE_UINT | 2 << 28 | Number of the uint type.| +| HUKS_TAG_TYPE_ULONG | 3 << 28 | BigInt. | +| HUKS_TAG_TYPE_BOOL | 4 << 28 | Boolean. | +| HUKS_TAG_TYPE_BYTES | 5 << 28 | Uint8Array. | ## HuksTag @@ -336,12 +399,16 @@ Enumerates the tags used to invoke parameters. | HUKS_TAG_ALL_USERS | ksTagType.HUKS_TAG_TYPE_BOOL \| 301 | Reserved. | | HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | Reserved. | | HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | Reserved. | -| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | Reserved. | +| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | User authentication type. For details, see [HuksUserAuthType](#huksuserauthtype9). This parameter must be set together with [HuksAuthAccessType](#huksauthaccesstype9). You can set a maximum of two user authentication types at a time. For example, if **HuksAuthAccessType** is **HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL**, you can set two of **HKS_USER_AUTH_TYPE_FACE**, **HKS_USER_AUTH_TYPE_FINGERPRINT**, and **HKS_USER_AUTH_TYPE_FACE\**.| HKS_USER_AUTH_TYPE_FINGERPRINT | | HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | Reserved. | | HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | Reserved. | +| HUKS_TAG_KEY_AUTH_ACCESS_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 307 | Access control type. For details, see [HuksAuthAccessType](#huksauthaccesstype9). This parameter must be set together with [HuksUserAuthType](#huksuserauthtype9).| +| HUKS_TAG_KEY_SECURE_SIGN_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 308 | Signature type of the key generated or imported.| +| HUKS_TAG_CHALLENGE_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 309 | Type of the challenge generated for a key. For details, see [HuksChallengeType](#hukschallengetype9).| +| HUKS_TAG_CHALLENGE_POS9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 310 | Position of the 8-bypte custom challenge. For details, see [HuksChallengePosition](#hukschallengeposition9).| | HUKS_TAG_ATTESTATION_CHALLENGE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 501 | Challenge value used in the attestation. | | HUKS_TAG_ATTESTATION_APPLICATION_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 502 | Application ID used in the attestation. | -| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | Device brand. | +| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | Brand of the device. | | HUKS_TAG_ATTESTATION_ID_DEVICE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 504 | Device ID. | | HUKS_TAG_ATTESTATION_ID_PRODUCT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 505 | Product name of the device. | | HUKS_TAG_ATTESTATION_ID_SERIAL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 506 | Device SN. | @@ -694,6 +761,144 @@ var huksoptions = { var result = huks.importKey(keyAlias, huksoptions); ``` +## huks.attestkey9+ + +attestKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void + +Obtains the certificate used to verify a key. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Security.Huks + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------------- | ----------------------------------------- | ---- | -------------------------------------------------- | +| keyAlias | string | Yes | Alias of the key. The certificate to be obtained stores the key. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters and data required for obtaining the certificate. | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | Yes | Callback used to return the result. If the operation is successful, **HUKS_SUCCESS** will be returned. If the operation fails, an error code will be returned.| + +**Example** + +```js +let securityLevel = stringToUint8Array('sec_level'); +let challenge = stringToUint8Array('challenge_data'); +let versionInfo = stringToUint8Array('version_info'); +let keyAliasString = "key attest"; + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function printLog(...data) { + console.error(data.toString()); +} + +async function attestKey() { + let aliasString = keyAliasString; + let aliasUint8 = stringToUint8Array(aliasString); + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, + value: securityLevel + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, + value: challenge + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, + value: versionInfo + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, + value: aliasUint8 + }; + let options = { + properties: properties + }; + generateKey(aliasString); + setTimeout(()=>huks.attestKey(aliasString, options, function (err, data) { + printLog(`key attest result : ${JSON.stringify(data)}`); + }), 1000); +} +``` + +## huks.attestkey9+ + +attestKey(keyAlias: string, options: HuksOptions) : Promise\ + +Obtains the certificate used to verify a key. This API uses a promise to return the result. + +**System capability**: SystemCapability.Security.Huks + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------------- | ----------------------------------------- | ---- | -------------------------------------------------- | +| keyAlias | string | Yes | Alias of the key. The certificate to be obtained stores the key. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters and data required for obtaining the certificate. | + +**Return value** + +| Type | Description | +| ----------------------------------- | -------------------------------------------------- | +| Promise\<[HuksResult](#huksresult)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** will be returned. If the operation fails, an error code will be returned.| + +**Example** + +```js +let securityLevel = stringToUint8Array('sec_level'); +let challenge = stringToUint8Array('challenge_data'); +let versionInfo = stringToUint8Array('version_info'); +let keyAliasString = "key attest"; + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function printLog(...data) { + console.error(data.toString()); +} + +async function attestKey() { + let aliasString = keyAliasString; + let aliasUint8 = stringToUint8Array(aliasString); + let properties = new Array(); + properties[0] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO, + value: securityLevel + }; + properties[1] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE, + value: challenge + }; + properties[2] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO, + value: versionInfo + }; + properties[3] = { + tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS, + value: aliasUint8 + }; + let options = { + properties: properties + }; + generateKey(aliasString); + let result = await huks.exportKey(attestKey, options); + printLog(`key attest result : ${result.errorCode}`); +} +``` + ## huks.importWrappedKey9+ importWrappedKey(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback\) : void @@ -1131,41 +1336,94 @@ Initializes a key. This API uses a promise to return the result asynchronously. | promise | Promise\<[HuksHandle](#hukshandle)> | Yes | Promise used to return the handle of the initialization operation.| -## huks.update +## huks.update(deprecated) update(handle: number, token?: Uint8Array, options: HuksOptions, callback: AsyncCallback\) : void Updates a key. This API uses an asynchronous callback to return the result. +> **NOTE**
This API is discarded since API version 9. You are advised to use [huks.update9+]. + **System capability**: SystemCapability.Security.Huks **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | Yes | Handle of the **Update** operation.| -| token | Uint8Array | No| Token of the **Update** operation.| -| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation.| -| callback | AsyncCallback\<[HuksResult](#huksresult)> | Yes| Callback used to return the operation result.| - +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | Yes | Handle of the **Update** operation. | +| token | Uint8Array | No | Token of the **Update** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation. | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | Yes | Callback used to return the operation result.| -## huks.update +## huks.update(deprecated) update(handle: number, token?: Uint8Array, options: HuksOptions) : Promise\ Updates a key. This API uses a promise to return the result asynchronously. +> **NOTE**
This API is discarded since API version 9. You are advised to use [huks.update9+](#huksupdate9). + **System capability**: SystemCapability.Security.Huks **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ---------------------- | ---- | ------------------------------------- | -| handle | number | Yes | Handle of the **Update** operation.| -| token | Uint8Array | No| Token of the **Update** operation.| -| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation.| -| promise | Promise\<[HuksResult](#huksresult)> | Yes| Promise used to return the operation result.| +| Name | Type | Mandatory| Description | +| ------- | ----------------------------------- | ---- | -------------------------------------------- | +| handle | number | Yes | Handle of the **Update** operation. | +| token | Uint8Array | No | Token of the **Update** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation. | +| promise | Promise\<[HuksResult](#huksresult)> | Yes | Callback used to return the operation result.| + +## huks.update9+ + +update(handle: number, options: HuksOptions, callback: AsyncCallback\) : void + +Updates a key. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Security.Huks + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | Yes | Handle of the **Update** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation. | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | Yes | Callback used to return the operation result.| + + +## huks.update9+ + +update(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void + +Updates a key. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Security.Huks +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | Yes | Handle of the **Update** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation. | +| token | Uint8Array | Yes | Token of the **Update** operation. | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | Yes | Callback used to return the operation result.| + +## huks.update9+ + +update(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ + +Updates a key. This API uses a promise to return the result asynchronously. + +**System capability**: SystemCapability.Security.Huks + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ----------------------------------- | ---- | -------------------------------------------- | +| handle | number | Yes | Handle of the **Update** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Update** operation. | +| token | Uint8Array | No | Token of the **Update** operation. | +| promise | Promise\<[HuksResult](#huksresult)> | Yes | Promise used to return the operation result.| ## huks.finish @@ -1198,8 +1456,42 @@ Completes the key operation and releases resources. This API uses a promise to r | -------- | ---------------------- | ---- | ------------------------------------- | | handle | number | Yes | Handle of the **Finish** operation.| | options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Finish** operation.| -| promise | Promise\<[HuksResult](#HuksResult)> | Yes| Promise used to return the operation result.| +| promise | Promise\<[HuksResult](#huksresult)> | Yes| Promise used to return the operation result.| + +## huks.finish9+ + +finish(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback\) : void + +Completes the key operation and releases resources. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Security.Huks + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------- | ---- | -------------------------------------------- | +| handle | number | Yes | Handle of the **Finish** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Finish** operation. | +| token | Uint8Array | Yes | Token for the **Finish** operation. | +| callback | AsyncCallback\<[HuksResult](#huksresult)> | Yes | Callback used to return the operation result.| + + +## huks.finish9+ + +finish(handle: number, options: HuksOptions, token?: Uint8Array) : Promise\ + +Completes the key operation and releases resources. This API uses a promise to return the result asynchronously. + +**System capability**: SystemCapability.Security.Huks + +**Parameters** +| Name | Type | Mandatory| Description | +| ------- | ----------------------------------- | ---- | ----------------------------------- | +| handle | number | Yes | Handle of the **Finish** operation. | +| options | [HuksOptions](#huksoptions) | Yes | Parameters of the **Finish** operation. | +| token | Uint8Array | No | Token for the **Finish** operation. | +| promise | Promise\<[HuksResult](#huksresult)> | Yes | Promise used to return the operation result.| ## huks.abort @@ -1653,9 +1945,9 @@ Defines the **param** in the **properties** array of **options** used in the API **System capability**: SystemCapability.Security.Huks -| Name| Type | Mandatory| Description | -| ------ | ----------------------------------- | ---- | ---------- | -| tag | HuksTag | Yes | Tag. | +| Name| Type | Mandatory| Description | +| ------ | ----------------------------------- | ---- | ------------ | +| tag | [HuksTag](#hukstag) | Yes | Tag. | | value | boolean\|number\|bigint\|Uint8Array | Yes | Value of the tag.| ## HuksOptions @@ -1666,7 +1958,7 @@ Defines the **options** used in the APIs. | Name | Type | Mandatory| Description | | ---------- | ----------------- | ---- | ------------------------ | -| properties | Array\ | No | Array used to hold **HuksParam**.| +| properties | Array\<[HuksParam](#huksparam)> | No | Array used to hold **HuksParam**.| | inData | Uint8Array | No | Input data. | ## HuksHandle @@ -1679,7 +1971,7 @@ Defines the HUKS handle structure. | ---------- | ---------------- | ---- | -------- | | errorCode | number | Yes | Error code.| | handle | number | Yes| Value of the handle.| -| token | Uint8Array | No| Reserved.| +| token | Uint8Array | No| Challenge information obtained after the [init](#huksinit) operation.| ## HuksResult @@ -1690,9 +1982,9 @@ Defines the **HuksResult** structure. -| Name | Type | Mandatory| Description | -| ---------- | ----------------- | ---- | -------- | -| errorCode | number | Yes | Error code. | -| outData | Uint8Array | No | Output data.| -| properties | Array\ | No | Properties. | -| certChains | Array\ | No | Certificate chain. | +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------- | ---- | ---------------- | +| errorCode | number | Yes | Error code. | +| outData | Uint8Array | No | Output data. | +| properties | Array\<[HuksParam](#huksparam)> | No | Property information. | +| certChains | Array\ | No | Certificate chain information.|