@ohos.security.huks (HUKS)

The HUKS 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.

NOTE

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.

Modules to Import

import huks from '@ohos.security.huks'

HuksParam

Defines the param in the properties array of options used in the APIs.

System capability: SystemCapability.Security.Huks.Core

HuksOptions

Defines the options used in the APIs.

System capability: SystemCapability.Security.Huks.Core

HuksSessionHandle⁹⁺

Defines the HUKS handle structure.

System capability: SystemCapability.Security.Huks.Core

HuksReturnResult⁹⁺

Defines the HuksResult struct.

System capability: SystemCapability.Security.Huks.Core

huks.generateKeyItem⁹⁺

generateKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void

Generates a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
/* Generate an ECC key of 256 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyDigest = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let keyAlias: string = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_ECC
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value:
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN |
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY
    },
    {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    },
];
let options: huks.HuksOptions = {
    properties: properties
};
try {
    huks.generateKeyItem(keyAlias, options, (error, data) => {
        if (error) {
            console.error(`callback: generateKeyItem failed`);
        } else {
            console.info(`callback: generateKeyItem key success`);
        }
    });
} catch (error) {
    console.error(`callback: generateKeyItem input arg invalid`);
}

huks.generateKeyItem⁹⁺

generateKeyItem(keyAlias: string, options: HuksOptions) : Promise<void>

Generates a key. This API uses a promise to return the result. Because the key is always protected in a trusted environment (such as a TEE), the promise does not return the key content. It returns only the information indicating whether the API is successfully called.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

/* Generate an ECC key of 256 bits. */
import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyDigest = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_ECC
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value:
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN |
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY
    },
    {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    },
];
let options: huks.HuksOptions = {
    properties: properties
};
try {
    huks.generateKeyItem(keyAlias, options)
        .then((data) => {
            console.info(`promise: generateKeyItem success`);
        })
        .catch((error: BusinessError) => {
            console.error(`promise: generateKeyItem failed`);
        });
} catch (error) {
    console.error(`promise: generateKeyItem input arg invalid`);
}

huks.deleteKeyItem⁹⁺

deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void

Deletes a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
try {
    huks.deleteKeyItem(keyAlias, emptyOptions, (error, data) => {
        if (error) {
            console.error(`callback: deleteKeyItem failed`);
        } else {
            console.info(`callback: deleteKeyItem key success`);
        }
    });
} catch (error) {
    console.error(`callback: deleteKeyItem input arg invalid`);
}

huks.deleteKeyItem⁹⁺

deleteKeyItem(keyAlias: string, options: HuksOptions) : Promise<void>

Deletes a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
try {
    huks.deleteKeyItem(keyAlias, emptyOptions)
        .then ((data) => {
            console.info(`promise: deleteKeyItem key success`);
        })
        .catch((error: BusinessError) => {
            console.error(`promise: deleteKeyItem failed`);
        });
} catch (error) {
    console.error(`promise: deleteKeyItem input arg invalid`);
}

huks.getSdkVersion

getSdkVersion(options: HuksOptions) : string

Obtains the SDK version of the current system.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let emptyOptions: huks.HuksOptions = {
    properties: []
};
let result = huks.getSdkVersion(emptyOptions);

huks.importKeyItem⁹⁺

importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void

Imports a key in plaintext. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
/* Import an AES key of 256 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyPadding |
    huks.HuksCipherMode = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let plainTextSize32 = makeRandomArr(32);
function makeRandomArr(size: number) {
    let arr = new Uint8Array(size);
    for (let i = 0; i < size; i++) {
        arr[i] = Math.floor(Math.random() * 10);
    }
    return arr;
};
let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_AES
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value:
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_PKCS7
    },
    {
        tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
        value: huks.HuksCipherMode.HUKS_MODE_ECB
    }
];
let options: huks.HuksOptions = {
    properties: properties,
    inData: plainTextSize32
};
try {
    huks.importKeyItem(keyAlias, options, (error, data) => {
        if (error) {
            console.error(`callback: importKeyItem failed`);
        } else {
            console.info(`callback: importKeyItem success`);
        }
    });
} catch (error) {
    console.error(`callback: importKeyItem input arg invalid`);
}

huks.importKeyItem⁹⁺

importKeyItem(keyAlias: string, options: HuksOptions) : Promise<void>

Imports a key in plaintext. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* Import an AES key of 128 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyPadding |
    huks.HuksCipherMode = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let plainTextSize32 = makeRandomArr(32);
function makeRandomArr(size: number) {
    let arr = new Uint8Array(size);
    for (let i = 0; i < size; i++) {
        arr[i] = Math.floor(Math.random() * 10);
    }
    return arr;
};
/* Step 1 Generate a key. */
let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_AES
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_PKCS7
    },
    {
        tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
        value: huks.HuksCipherMode.HUKS_MODE_ECB
    }
];
let huksoptions: huks.HuksOptions = {
    properties: properties,
    inData: plainTextSize32
};
try {
    huks.importKeyItem(keyAlias, huksoptions)
        .then((data) => {
            console.info(`promise: importKeyItem success`);
        })
        .catch((error: BusinessError) => {
            console.error(`promise: importKeyItem failed`);
        });
} catch (error) {
    console.error(`promise: importKeyItem input arg invalid`);
}

huks.attestKeyItem⁹⁺

attestKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void

Obtains the certificate used to verify a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyDigest |
    huks.HuksKeyStorageType | huks.HuksKeyPadding | huks.HuksKeyGenerateType |
    huks.HuksCipherMode | Uint8Array = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let securityLevel = stringToUint8Array('sec_level');
let challenge = stringToUint8Array('challenge_data');
let versionInfo = stringToUint8Array('version_info');
let keyAliasString = "key attest";
function stringToUint8Array(str: string) {
    let arr: number[] = [];
    for (let i = 0, j = str.length; i < j; ++i) {
        arr.push(str.charCodeAt(i));
    }
    let tmpUint8Array = new Uint8Array(arr);
    return tmpUint8Array;
}

async function generateKeyThenattestKey(alias: string) {
    let aliasString = keyAliasString;
    let aliasUint8 = stringToUint8Array(aliasString);
    let generateProperties: HuksProperties[] = [
        {
            tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
            value: huks.HuksKeyAlg.HUKS_ALG_RSA
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG,
            value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
            value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PURPOSE,
            value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY
        },
        {
            tag: huks.HuksTag.HUKS_TAG_DIGEST,
            value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PADDING,
            value: huks.HuksKeyPadding.HUKS_PADDING_PSS
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE,
            value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT
        },
        {
            tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
            value: huks.HuksCipherMode.HUKS_MODE_ECB
        }
    ];
    let generateOptions: huks.HuksOptions = {
        properties: generateProperties
    };
    let attestProperties: HuksProperties[] = [
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO,
            value: securityLevel
        },
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE,
            value: challenge
        },
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO,
            value: versionInfo
        },
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS,
            value: aliasUint8
        }
    ];
    let attestOptions: huks.HuksOptions = {
        properties: attestProperties
    };
    try {
        huks.generateKeyItem(alias, generateOptions, (error, data) => {
            if (error) {
                console.error(`callback: generateKeyItem failed`);
            } else {
                console.info(`callback: generateKeyItem success`);
                try {
                    huks.attestKeyItem(aliasString, attestOptions, (error, data) => {
                        if (error) {
                            console.error(`callback: attestKeyItem failed`);
                        } else {
                            console.info(`callback: attestKeyItem success`);
                        }
                    });
                } catch (error) {
                    console.error(`callback: attestKeyItem input arg invalid`);
                }
            }
        });
    } catch (error) {
        console.error(`callback: generateKeyItem input arg invalid`);
    }
}

huks.attestKeyItem⁹⁺

attestKeyItem(keyAlias: string, options: HuksOptions) : Promise<HuksReturnResult>

Obtains the certificate used to verify a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyDigest |
    huks.HuksKeyStorageType | huks.HuksKeyPadding | huks.HuksKeyGenerateType |
    huks.HuksCipherMode | Uint8Array = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let securityLevel = stringToUint8Array('sec_level');
let challenge = stringToUint8Array('challenge_data');
let versionInfo = stringToUint8Array('version_info');
let keyAliasString = "key attest";
function stringToUint8Array(str: string) {
    let arr: number[] = [];
    for (let i = 0, j = str.length; i < j; ++i) {
        arr.push(str.charCodeAt(i));
    }
    let tmpUint8Array = new Uint8Array(arr);
    return tmpUint8Array;
}
async function generateKey(alias: string) {
    let properties: HuksProperties[] = [
        {
            tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
            value: huks.HuksKeyAlg.HUKS_ALG_RSA
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_STORAGE_FLAG,
            value: huks.HuksKeyStorageType.HUKS_STORAGE_PERSISTENT
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
            value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_2048
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PURPOSE,
            value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY
        },
        {
            tag: huks.HuksTag.HUKS_TAG_DIGEST,
            value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PADDING,
            value: huks.HuksKeyPadding.HUKS_PADDING_PSS
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_GENERATE_TYPE,
            value: huks.HuksKeyGenerateType.HUKS_KEY_GENERATE_TYPE_DEFAULT
        },
        {
            tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
            value: huks.HuksCipherMode.HUKS_MODE_ECB
        }
    ];
    let options: huks.HuksOptions = {
        properties: properties
    };
    try {
        await huks.generateKeyItem(alias, options)
            .then((data) => {
                console.info(`promise: generateKeyItem success`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: generateKeyItem failed`);
            });
    } catch (error) {
        console.error(`promise: generateKeyItem input arg invalid`);
    }
}
async function attestKey() {
    let aliasString = keyAliasString;
    let aliasUint8 = stringToUint8Array(aliasString);
    let properties: HuksProperties[] = [
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO,
            value: securityLevel
        },
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_CHALLENGE,
            value: challenge
        },
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_VERSION_INFO,
            value: versionInfo
        },
        {
            tag: huks.HuksTag.HUKS_TAG_ATTESTATION_ID_ALIAS,
            value: aliasUint8
        }
    ];
    let options: huks.HuksOptions = {
        properties: properties
    };
    await generateKey(aliasString);
    try {
        await huks.attestKeyItem(aliasString, options)
            .then((data) => {
                console.info(`promise: attestKeyItem success`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: attestKeyItem failed`);
            });
    } catch (error) {
        console.error(`promise: attestKeyItem input arg invalid`);
    }
}

huks.importWrappedKeyItem⁹⁺

importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions, callback: AsyncCallback<void>) : void

Imports a wrapped key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyDigest | huks.HuksKeyPadding | huks.HuksUnwrapSuite |
    huks.HuksCipherMode | huks.HuksImportKeyType = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let alias1 = "importAlias";
let alias2 = "wrappingKeyAlias";
async function TestGenFunc(alias: string, options: huks.HuksOptions) {
    try {
        await genKey(alias, options)
            .then((data) => {
                console.info(`callback: generateKeyItem success`);
            })
            .catch((error: BusinessError) => {
                console.error(`callback: generateKeyItem failed`);
            });
    } catch (error) {
        console.error(`callback: generateKeyItem input arg invalid`);
    }
}
function genKey(alias: string, options: huks.HuksOptions) {
    return new Promise<void>((resolve, reject) => {
        try {
            huks.generateKeyItem(alias, options, (error, data) => {
                if (error) {
                    reject(error);
                } else {
                    resolve(data);
                }
            });
        } catch (error) {
            throw (new Error(error));
        }
    });
}
async function TestExportFunc(alias: string, options: huks.HuksOptions) {
    try {
        await exportKey(alias, options)
            .then((data) => {
                console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`);
            })
            .catch((error: BusinessError) => {
                console.error(`callback: exportKeyItem failed`);
            });
    } catch (error) {
        console.error(`callback: exportKeyItem input arg invalid`);
    }
}
function exportKey(alias: string, options: huks.HuksOptions) {
    return new Promise<huks.HuksReturnResult>((resolve, reject) => {
        try {
            huks.exportKeyItem(alias, options, (error, data) => {
                if (error) {
                    reject(error);
                } else {
                    resolve(data);
                }
            });
        } catch (error) {
            throw (new Error(error));
        }
    });
}
async function TestImportWrappedFunc(alias: string, wrappingAlias: string, options: huks.HuksOptions) {
    try {
        await importWrappedKey(alias, wrappingAlias, options)
            .then((data) => {
                console.info(`callback: importWrappedKeyItem success`);
            })
            .catch((error: BusinessError) => {
                console.error(`callback: importWrappedKeyItem failed`);
            });
    } catch (error) {
        console.error(`callback: importWrappedKeyItem input arg invalid`);
    }
}
function importWrappedKey(alias: string, wrappingAlias: string, options: huks.HuksOptions) {
    return new Promise<void>((resolve, reject) => {
        try {
            huks.importWrappedKeyItem(alias, wrappingAlias, options, (error, data) => {
                if (error) {
                    reject(error);
                } else {
                    resolve(data);
                }
            });
        } catch (error) {
            throw (new Error(error));
        }
    });
}
async function TestImportWrappedKeyFunc(
        alias: string,
        wrappingAlias: string,
        genOptions: huks.HuksOptions,
        importOptions: huks.HuksOptions
) {
    await TestGenFunc(wrappingAlias, genOptions);
    await TestExportFunc(wrappingAlias, genOptions);

    /*The following operations do not invoke the HUKS APIs, and the specific implementation is not provided here.
     * For example, import **keyA**.
     * 1. Use ECC to generate a public and private key pair **keyB**. The public key is **keyB_pub**, and the private key is **keyB_pri**.
     * 2. Use **keyB_pri** and the public key obtained from **wrappingAlias** to negotiate the shared key **share_key**.
     * 3. Randomly generate a key **kek** and use it to encrypt **keyA** with AES-GCM. During the encryption, record **nonce1**, **aad1**, ciphertext **keyA_enc**, and encrypted **tag1**.
     * 4. Use **share_key** to encrypt **kek** with AES-GCM. During the encryption, record **nonce2**, **aad2**, ciphertext **kek_enc**, and encrypted **tag2**.
     * 5. Generate the **importOptions.inData** field in the following format:
     * keyB_pub length (4 bytes) + keyB_pub + aad2 length (4 bytes) + aad2 +
     * nonce2 length (4 bytes) + nonce2 + tag2 length (4 bytes) + tag2 +
     * kek_enc length (4 bytes) + kek_enc + aad1 length (4 bytes) + aad1 +
     * nonce1 length (4 bytes) + nonce1 + tag1 length (4 bytes) + tag1 +
     * Memory occupied by the keyA length (4 bytes) + keyA length + keyA_enc length (4 bytes) + keyA_enc
     */
    /* The key data imported vary with the sample code given below. The data structure is described in the preceding comments. */
    let inputKey = new Uint8Array([0x02, 0x00, 0x00, 0x00]);
    importOptions.inData = inputKey;
    await TestImportWrappedFunc(alias, wrappingAlias, importOptions);
}
function makeGenerateOptions() {
    let properties: HuksProperties[] = [
        {
            tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
            value: huks.HuksKeyAlg.HUKS_ALG_ECC
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
            value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PURPOSE,
            value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_UNWRAP
        },
        {
            tag: huks.HuksTag.HUKS_TAG_DIGEST,
            value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
        },
        {
            tag: huks.HuksTag.HUKS_TAG_IMPORT_KEY_TYPE,
            value: huks.HuksImportKeyType.HUKS_KEY_TYPE_KEY_PAIR,
        }
    ];
    let options: huks.HuksOptions = {
        properties: properties
    };
    return options;
};
function makeImportOptions() {
    let properties: HuksProperties[] = [
        {
            tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
            value: huks.HuksKeyAlg.HUKS_ALG_AES
        },
        {
            tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
            value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PURPOSE,
            value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
        },
        {
            tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
            value: huks.HuksCipherMode.HUKS_MODE_CBC
        },
        {
            tag: huks.HuksTag.HUKS_TAG_PADDING,
            value: huks.HuksKeyPadding.HUKS_PADDING_NONE
        },
        {
            tag: huks.HuksTag.HUKS_TAG_UNWRAP_ALGORITHM_SUITE,
            value: huks.HuksUnwrapSuite.HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING
        }
    ];
    let options: huks.HuksOptions = {
        properties: properties
    };
    return options;
};
function huksImportWrappedKey() {
    let genOptions = makeGenerateOptions();
    let importOptions = makeImportOptions();
    TestImportWrappedKeyFunc(
        alias1,
        alias2,
        genOptions,
        importOptions
    );
}

huks.importWrappedKeyItem⁹⁺

importWrappedKeyItem(keyAlias: string, wrappingKeyAlias: string, options: HuksOptions) : Promise<void>

Imports a wrapped key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* The process is similar as if a callback is used, except the following:*/
/* The key data imported vary with the sample code given below. The data structure is described in the preceding comments. */
async function TestImportWrappedFunc(alias: string, wrappingAlias: string, options: huks.HuksOptions) {
    try {
        await huks.importWrappedKeyItem(alias, wrappingAlias, options)
            .then ((data) => {
                console.info(`promise: importWrappedKeyItem success`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: importWrappedKeyItem failed`);
            });
    } catch (error) {
        console.error(`promise: importWrappedKeyItem input arg invalid`);
    }
}

huks.exportKeyItem⁹⁺

exportKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void

Exports a key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
try {
    huks.exportKeyItem(keyAlias, emptyOptions, (error, data) => {
        if (error) {
            console.error(`callback: exportKeyItem failed`);
        } else {
            console.info(`callback: exportKeyItem success, data = ${JSON.stringify(data)}`);
        }
    });
} catch (error) {
    console.error(`callback: exportKeyItem input arg invalid`);
}

huks.exportKeyItem⁹⁺

exportKeyItem(keyAlias: string, options: HuksOptions) : Promise<HuksReturnResult>

Exports a key. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
try {
    huks.exportKeyItem(keyAlias, emptyOptions)
        .then ((data) => {
            console.info(`promise: exportKeyItem success, data = ${JSON.stringify(data)}`);
        })
        .catch((error: BusinessError) => {
            console.error(`promise: exportKeyItem failed`);
        });
} catch (error) {
    console.error(`promise: exportKeyItem input arg invalid`);
}

huks.getKeyItemProperties⁹⁺

getKeyItemProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void

Obtains key properties. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
try {
    huks.getKeyItemProperties(keyAlias, emptyOptions, (error, data) => {
        if (error) {
            console.error(`callback: getKeyItemProperties failed`);
        } else {
            console.info(`callback: getKeyItemProperties success, data = ${JSON.stringify(data)}`);
        }
    });
} catch (error) {
    console.error(`callback: getKeyItemProperties input arg invalid`);
}

huks.getKeyItemProperties⁹⁺

getKeyItemProperties(keyAlias: string, options: HuksOptions) : Promise<HuksReturnResult>

Obtains key properties. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
try {
    huks.getKeyItemProperties(keyAlias, emptyOptions)
        .then ((data) => {
            console.info(`promise: getKeyItemProperties success, data = ${JSON.stringify(data)}`);
        })
        .catch((error: BusinessError) => {
            console.error(`promise: getKeyItemProperties failed`);
        });
} catch (error) {
    console.error(`promise: getKeyItemProperties input arg invalid`);
}

huks.isKeyItemExist⁹⁺

isKeyItemExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback<boolean>) : void

Checks whether a key exists. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import promptAction from '@ohos.promptAction';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
huks.isKeyItemExist(keyAlias, emptyOptions, (error, data) => {
    if (data) {
        promptAction.showToast({
            message: "keyAlias: " + keyAlias +"is existed! ",
            duration: 2500,
        })
    } else {
        promptAction.showToast({
            message: "find key failed",
            duration: 2500,
        })
    }
});

huks.isKeyItemExist⁹⁺

isKeyItemExist(keyAlias: string, options: HuksOptions) : Promise<boolean>

Checks whether a key exists. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
import promptAction from '@ohos.promptAction';

/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
huks.isKeyItemExist(keyAlias, emptyOptions).then((data) => {
    promptAction.showToast({
        message: "keyAlias: " + keyAlias +"is existed! ",
        duration: 500,
    })
}).catch((error: BusinessError)=>{
    promptAction.showToast({
        message: "find key failed",
        duration: 6500,
    })
})

huks.initSession⁹⁺

initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksSessionHandle>) : void

Initializes the data for a key operation. This API uses an asynchronous callback to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

huks.initSession⁹⁺

initSession(keyAlias: string, options: HuksOptions) : Promise<HuksSessionHandle>

Initializes the data for a key operation. This API uses a promise to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

huks.updateSession⁹⁺

updateSession(handle: number, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void

Updates the key operation by segment. This API uses an asynchronous callback to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

huks.updateSession⁹⁺

updateSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback<HuksReturnResult>) : void

Updates the key operation by segment. This API uses an asynchronous callback to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

huks.updateSession⁹⁺

updateSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise<HuksReturnResult>

Updates the key operation by segment. This API uses a promise to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

huks.finishSession⁹⁺

finishSession(handle: number, options: HuksOptions, callback: AsyncCallback<HuksReturnResult>) : void

Finishes the key operation to release resources. This API uses an asynchronous callback to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

huks.finishSession⁹⁺

finishSession(handle: number, options: HuksOptions, token: Uint8Array, callback: AsyncCallback<HuksReturnResult>) : void

Finishes the key operation to release resources. This API uses an asynchronous callback to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

huks.finishSession⁹⁺

finishSession(handle: number, options: HuksOptions, token?: Uint8Array) : Promise<HuksReturnResult>

Finishes the key operation to release resources. This API uses a promise to return the result. huks.initSession, huks.updateSession, and huks.finishSession must be used together.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

huks.abortSession⁹⁺

abortSession(handle: number, options: HuksOptions, callback: AsyncCallback<void>) : void

Aborts a key operation. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.Huks.Core

Parameters

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
/* huks.initSession, huks.updateSession, and huks.finishSession must be used together.
 * If an error occurs in any of huks.initSession, huks.updateSession,
 * and huks.finishSession operations,
 * huks.abortSession must be called to terminate the use of the key.
 *
 * The following uses the callback of an RSA1024 key as an example.
 */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose | huks.HuksKeyDigest |
    huks.HuksKeyPadding | huks.HuksCipherMode = huks.HuksKeyAlg.HUKS_ALG_ECC
}
function stringToUint8Array(str: string) {
    let arr: number[] = [];
    for (let i = 0, j = str.length; i < j; ++i) {
        arr.push(str.charCodeAt(i));
    }
    let tmpUint8Array = new Uint8Array(arr);
    return tmpUint8Array;
}
let keyAlias = "HuksDemoRSA";
let properties: HuksProperties[] = []
let options: huks.HuksOptions = {
    properties: properties,
    inData: new Uint8Array(0)
};
let handle: number = 0;
async function generateKey() {
    properties[0] = {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_RSA
    };
    properties[1] = {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024
    };
    properties[2] = {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT
    };
    properties[3] = {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5
    };
    properties[4] = {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    };
    properties[5] = {
        tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
        value: huks.HuksCipherMode.HUKS_MODE_ECB,
    }
    try {
        await huks.generateKeyItem(keyAlias, options, (error, data) => {
            if (error) {
                console.error(`callback: generateKeyItem failed`);
            } else {
                console.info(`callback: generateKeyItem success`);
            }
        });
    } catch (error) {
        console.error(`callback: generateKeyItem input arg invalid`);
    }
}
async function huksInit() {
    console.log('enter huksInit');
    try {
        huks.initSession(keyAlias, options, (error, data) => {
            if (error) {
                console.error(`callback: initSession failed`);
            } else {
                console.info(`callback: initSession success, data = ${JSON.stringify(data)}`);
                handle = data.handle;
            }
        });
    } catch (error) {
        console.error(`callback: initSession input arg invalid`);
    }
}
async function huksUpdate() {
    console.log('enter huksUpdate');
    options.inData = stringToUint8Array("huksHmacTest");
    try {
        huks.updateSession(handle, options, (error, data) => {
            if (error) {
                console.error(`callback: updateSession failed`);
            } else {
                console.info(`callback: updateSession success, data = ${JSON.stringify(data)}`);
            }
        });
    } catch (error) {
        console.error(`callback: updateSession input arg invalid`);
    }
}
async function huksFinish() {
    console.log('enter huksFinish');
    options.inData = new Uint8Array(0);
    try {
        huks.finishSession(handle, options, (error, data) => {
            if (error) {
                console.error(`callback: finishSession failed`);
            } else {
                console.info(`callback: finishSession success, data = ${JSON.stringify(data)}`);
            }
        });
    } catch (error) {
        console.error(`callback: finishSession input arg invalid`);
    }
}
async function huksAbort() {
    console.log('enter huksAbort');
    try {
        huks.abortSession(handle, options, (error, data) => {
            if (error) {
                console.error(`callback: abortSession failed`);
            } else {
                console.info(`callback: abortSession success`);
            }
        });
    } catch (error) {
        console.error(`callback: abortSession input arg invalid`);
    }
}

huks.abortSession⁹⁺

abortSession(handle: number, options: HuksOptions) : Promise<void>;

Aborts a key operation. This API uses a promise to return the result.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Error codes

For details about the error codes, see HUKS Error Codes.

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* huks.initSession, huks.updateSession, and huks.finishSession must be used together.
 * If an error occurs in any of huks.initSession, huks.updateSession,
 * and huks.finishSession operations,
 * huks.abortSession must be called to terminate the use of the key.
 *
 * The following uses the callback of an RSA1024 key as an example.
 */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyDigest | huks.HuksKeyPadding | huks.HuksKeyGenerateType |
    huks.HuksCipherMode = huks.HuksKeyAlg.HUKS_ALG_ECC
}

function stringToUint8Array(str: string) {
    let arr: number[] = [];
    for (let i = 0, j = str.length; i < j; ++i) {
        arr.push(str.charCodeAt(i));
    }
    let tmpUint8Array = new Uint8Array(arr);
    return tmpUint8Array;
}

let keyAlias = "HuksDemoRSA";
let properties: HuksProperties[] = []
let options: huks.HuksOptions = {
    properties: properties,
    inData: new Uint8Array(0)
};
let handle: number = 0;

async function generateKey() {
    properties[0] = {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_RSA
    };
    properties[1] = {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024
    };
    properties[2] = {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT
    };
    properties[3] = {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_PKCS1_V1_5
    };
    properties[4] = {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    };
    properties[5] = {
        tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
        value: huks.HuksCipherMode.HUKS_MODE_ECB,
    }

    try {
        await huks.generateKeyItem(keyAlias, options)
            .then((data) => {
                console.info(`promise: generateKeyItem success`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: generateKeyItem failed`);
            });
    } catch (error) {
        console.error(`promise: generateKeyItem input arg invalid`);
    }
}

async function huksInit() {
    console.log('enter huksInit');
    try {
        await huks.initSession(keyAlias, options)
            .then((data) => {
                console.info(`promise: initSession success, data = ${JSON.stringify(data)}`);
                handle = data.handle;
            })
            .catch((error: BusinessError) => {
                console.error(`promise: initSession key failed`);
            });
    } catch (error) {
        console.error(`promise: initSession input arg invalid`);
    }
}

async function huksUpdate() {
    console.log('enter huksUpdate');
    options.inData = stringToUint8Array("huksHmacTest");
    try {
        await huks.updateSession(handle, options)
            .then((data) => {
                console.info(`promise: updateSession success, data = ${JSON.stringify(data)}`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: updateSession failed`);
            });
    } catch (error) {
        console.error(`promise: updateSession input arg invalid`);
    }
}

async function huksFinish() {
    console.log('enter huksFinish');
    options.inData = new Uint8Array(0);
    try {
        await huks.finishSession(handle, options)
            .then((data) => {
                console.info(`promise: finishSession success, data = ${JSON.stringify(data)}`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: finishSession failed`);
            });
    } catch (error) {
        console.error(`promise: finishSession input arg invalid`);
    }
}

async function huksAbort() {
    console.log('enter huksAbort');
    try {
        await huks.abortSession(handle, options)
            .then((data) => {
                console.info(`promise: abortSession success`);
            })
            .catch((error: BusinessError) => {
                console.error(`promise: abortSession failed`);
            });
    } catch (error) {
        console.error(`promise: abortSession input arg invalid`);
    }
}

HuksExceptionErrCode⁹⁺

Enumerates the error codes.

For details about the error codes, see KUKS Error Codes.

System capability: SystemCapability.Security.Huks.Core

HuksKeyPurpose

Enumerates the key purposes.

System capability: SystemCapability.Security.Huks.Core

HuksKeyDigest

Enumerates the digest algorithms.

System capability: SystemCapability.Security.Huks.Extension

HuksKeyPadding

Enumerates the padding algorithms.

System capability: SystemCapability.Security.Huks.Core

HuksCipherMode

Enumerates the cipher modes.

System capability: SystemCapability.Security.Huks.Core

HuksKeySize

Enumerates the key sizes.

System capability: SystemCapability.Security.Huks.Core

HuksKeyAlg

Enumerates the key algorithms.

System capability: SystemCapability.Security.Huks.Core

HuksKeyGenerateType

Enumerates the key generation types.

System capability: SystemCapability.Security.Huks.Extension

HuksKeyFlag

Enumerates the key generation modes.

System capability: SystemCapability.Security.Huks.Core

HuksKeyStorageType

Enumerates the key storage modes.

System capability: SystemCapability.Security.Huks.Core

HuksSendType

Enumerates the tag transfer modes.

System capability: SystemCapability.Security.Huks.Extension

HuksUnwrapSuite⁹⁺

Enumerates the algorithm suites used for importing a wrapped key.

System capability: SystemCapability.Security.Huks.Extension

HuksImportKeyType⁹⁺

Enumerates the types of keys to import. By default, a public key is imported. This field is not required when a symmetric key is imported.

System capability: SystemCapability.Security.Huks.Extension

HuksRsaPssSaltLenType¹⁰⁺

Enumerates the salt_len types to set when PSS padding is used in RSA signing or signature verification.

System capability: SystemCapability.Security.Huks.Extension

HuksUserAuthType⁹⁺

Enumerates the user authentication types.

System capability: SystemCapability.Security.Huks.Extension

HuksAuthAccessType⁹⁺

Enumerates the access control types.

System capability: SystemCapability.Security.Huks.Extension

HuksChallengeType⁹⁺

Enumerates the types of the challenges generated when a key is used.

System capability: SystemCapability.Security.Huks.Extension

HuksChallengePosition⁹⁺

Enumerates the positions of the 8-byte valid value in a custom challenge generated.

System capability: SystemCapability.Security.Huks.Extension

HuksSecureSignType⁹⁺

Defines the signature type of the key generated or imported.

System capability: SystemCapability.Security.Huks.Extension

HuksTagType

Enumerates the tag data types.

System capability: SystemCapability.Security.Huks.Core

HuksTag

Enumerates the tags used to invoke parameters.

System capability: SystemCapability.Security.Huks.Core

huks.generateKey^(deprecated)

generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Generates a key. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.generateKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
/* Generate an RSA key of 512 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyDigest | huks.HuksKeyPadding = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_RSA
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_512
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value:
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT |
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_OAEP
    },
    {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    }
];
let options: huks.HuksOptions = {
    properties: properties
};
huks.generateKey(keyAlias, options, (err, data) => {
});

huks.generateKey^(deprecated)

generateKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Generates a key. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.generateKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Generate an ECC key of 256 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyDigest = huks.HuksKeyAlg.HUKS_ALG_ECC
}

let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_ECC
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_256
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value:
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_SIGN |
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_VERIFY
    },
    {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    }
];
let options: huks.HuksOptions = {
    properties: properties
};
let result = huks.generateKey(keyAlias, options);

huks.deleteKey^(deprecated)

deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Deletes a key. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.deleteKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
huks.deleteKey(keyAlias, emptyOptions, (err, data) => {
});

huks.deleteKey^(deprecated)

deleteKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Deletes a key. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.deleteKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
let result = huks.deleteKey(keyAlias, emptyOptions);

huks.importKey^(deprecated)

importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Imports a key in plaintext. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.importKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
/* Import an AES key of 256 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyPadding | huks.HuksCipherMode = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let plainTextSize32 = makeRandomArr(32);
function makeRandomArr(size: number) {
    let arr = new Uint8Array(size);
    for (let i = 0; i < size; i++) {
        arr[i] = Math.floor(Math.random() * 10);
    }
    return arr;
};
let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_AES
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_256
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value:
        huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_PKCS7
    },
    {
        tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
        value: huks.HuksCipherMode.HUKS_MODE_ECB
    }
];
let options: huks.HuksOptions = {
    properties: properties,
    inData: plainTextSize32
};
huks.importKey(keyAlias, options, (err, data) => {
});

huks.importKey^(deprecated)

importKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Imports a key in plaintext. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.importKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Import an AES key of 128 bits. */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyPadding | huks.HuksCipherMode = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let plainTextSize32 = makeRandomArr(32);
function makeRandomArr(size: number) {
    let arr = new Uint8Array(size);
    for (let i = 0; i < size; i++) {
        arr[i] = Math.floor(Math.random() * 10);
    }
    return arr;
};
/* Step 1 Generate a key. */
let keyAlias = 'keyAlias';
let properties: HuksProperties[] = [
    {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_AES
    },
    {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_AES_KEY_SIZE_128
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT | huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT
    },
    {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_PKCS7
    },
    {
        tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE,
        value: huks.HuksCipherMode.HUKS_MODE_ECB
    }
];
let huksoptions: huks.HuksOptions = {
    properties: properties,
    inData: plainTextSize32
};
let result = huks.importKey(keyAlias, huksoptions);

huks.exportKey^(deprecated)

exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Exports a key. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.exportKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
huks.exportKey(keyAlias, emptyOptions, (err, data) => {
});

huks.exportKey^(deprecated)

exportKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Exports a key. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.exportKeyItem⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
let result = huks.exportKey(keyAlias, emptyOptions);

huks.getKeyProperties^(deprecated)

getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Obtains key properties. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.getKeyItemProperties⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
huks.getKeyProperties(keyAlias, emptyOptions, (err, data) => {
});

huks.getKeyProperties^(deprecated)

getKeyProperties(keyAlias: string, options: HuksOptions) : Promise<HuksResult>

Obtains key properties. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.getKeyItemProperties⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
let result = huks.getKeyProperties(keyAlias, emptyOptions);

huks.isKeyExist^(deprecated)

isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback<boolean>) : void

Checks whether a key exists. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.isKeyItemExist⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
huks.isKeyExist(keyAlias, emptyOptions, (err, data) => {
});

huks.isKeyExist^(deprecated)

isKeyExist(keyAlias: string, options: HuksOptions) : Promise<boolean>

Checks whether a key exists. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.isKeyItemExist⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
/* Set options to emptyOptions. */
let keyAlias = 'keyAlias';
let emptyOptions: huks.HuksOptions = {
    properties: []
};
let result = huks.isKeyExist(keyAlias, emptyOptions);

huks.init^(deprecated)

init(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksHandle>) : void

Initializes the data for a key operation. This API uses an asynchronous callback to return the result. huks.init, huks.update, and huks.finish must be used together.

NOTE

This API is deprecated since API version 9. You are advised to use huks.initSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

huks.init^(deprecated)

init(keyAlias: string, options: HuksOptions) : Promise<HuksHandle>

Initializes the data for a key operation. This API uses a promise to return the result. huks.init, huks.update, and huks.finish must be used together.

NOTE

This API is deprecated since API version 9. You are advised to use huks.initSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

huks.update^(deprecated)

update(handle: number, token?: Uint8Array, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Updates the key operation by segment. This API uses an asynchronous callback to return the result. huks.init, huks.update, and huks.finish must be used together.

NOTE

This API is deprecated since API version 9. You are advised to use huks.updateSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

huks.update^(deprecated)

update(handle: number, token?: Uint8Array, options: HuksOptions) : Promise<HuksResult>;

Updates the key operation by segment. This API uses a promise to return the result. huks.init, huks.update, and huks.finish must be used together.

NOTE

This API is deprecated since API version 9. You are advised to use huks.updateSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

huks.finish^(deprecated)

finish(handle: number, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Finishes the key operation to release resources. This API uses an asynchronous callback to return the result. huks.init, huks.update, and huks.finish must be used together.

NOTE

This API is deprecated since API version 9. You are advised to use huks.finishSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

huks.finish^(deprecated)

finish(handle: number, options: HuksOptions) : Promise<HuksResult>

Finishes the key operation to release resources. This API uses a promise to return the result. huks.init, huks.update, and huks.finish must be used together.

NOTE

This API is deprecated since API version 9. You are advised to use huks.finishSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

huks.abort^(deprecated)

abort(handle: number, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void

Aborts the use of the key. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.abortSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* huks.init, huks.update, and huks.finish must be used together.
 * If an error occurs in any of them, huks.abort must be called to terminate the use of the key.
 *
 * The following uses the callback of an RSA 1024 key as an example.
 */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyDigest | huks.HuksKeyPadding = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let keyalias = "HuksDemoRSA";
let properties: HuksProperties[] = [];
let options: huks.HuksOptions = {
    properties: properties,
    inData: new Uint8Array(0)
};
let handle: number = 0;
let resultMessage = "";
async function generateKey() {
    properties[0] = {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_RSA
    };
    properties[1] = {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024
    };
    properties[2] = {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT
    };
    properties[3] = {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_OAEP
    };
    properties[4] = {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    };
    huks.generateKey(keyalias, options);
}
function stringToUint8Array(str: string) {
    let arr: number[] = [];
    for (let i = 0, j = str.length; i < j; ++i) {
        arr.push(str.charCodeAt(i));
    }
    let tmpUint8Array = new Uint8Array(arr);
    return tmpUint8Array;
}
async function huksInit() {
    await huks.init(keyalias, options).then((data) => {
        console.log(`test init data: ${JSON.stringify(data)}`);
        handle = data.handle;
    }).catch((err: BusinessError) => {
        console.log("test init err information: " + JSON.stringify(err))
    })
}
async function huksUpdate() {
    options.inData = stringToUint8Array("huksHmacTest");
    await huks.update(handle, options.inData, options).then((data) => {
        if (data.errorCode === 0) {
            resultMessage += "update success!";
        } else {
            resultMessage += "update fail!";
        }
    });
    console.log(resultMessage);
}
function huksFinish() {
    options.inData = stringToUint8Array("HuksDemoHMAC");
    huks.finish(handle, options).then((data) => {
        if (data.errorCode === 0) {
            resultMessage = "finish success!";
        } else {
            resultMessage = "finish fail errorCode: " + data.errorCode;
        }
    }).catch((err: BusinessError) => {
        resultMessage = "Failed to complete the key operation. catch errorMessage:" + JSON.stringify(err)
    });
    console.log(resultMessage);
}
async function huksAbort() {
    new Promise<huks.HuksResult>((resolve, reject) => {
        huks.abort(handle, options, (err, data) => {
            console.log(`Huks_Demo hmac huksAbort1 data ${JSON.stringify(data)}`);
            console.log(`Huks_Demo hmac huksAbort1 err ${JSON.stringify(err)}`);
        });
    });
}

huks.abort^(deprecated)

abort(handle: number, options: HuksOptions) : Promise<HuksResult>;

Aborts the use of the key. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use huks.abortSession⁹⁺.

System capability: SystemCapability.Security.Huks.Extension

Parameters

Return value

Example

import huks from '@ohos.security.huks';
import { BusinessError } from '@ohos.base';
/* huks.init, huks.update, and huks.finish must be used together.
 * If an error occurs in any of them, huks.abort must be called to terminate the use of the key.
 *
 * The following uses the promise of an RSA 1024-bit key as an example.
 */
class HuksProperties {
    tag: huks.HuksTag = huks.HuksTag.HUKS_TAG_ALGORITHM
    value: huks.HuksKeyAlg | huks.HuksKeySize | huks.HuksKeyPurpose |
    huks.HuksKeyPadding | huks.HuksKeyDigest = huks.HuksKeyAlg.HUKS_ALG_ECC
}
let keyalias = "HuksDemoRSA";
let properties: HuksProperties[] = [];
let options: huks.HuksOptions = {
    properties: properties,
    inData: new Uint8Array(0)
};
let handle: number = 0;
let resultMessage = "";

function stringToUint8Array(str: string) {
    let arr: number[] = [];
    for (let i = 0, j = str.length; i < j; ++i) {
        arr.push(str.charCodeAt(i));
    }
    let tmpUint8Array = new Uint8Array(arr);
    return tmpUint8Array;
}

async function generateKey() {
    properties[0] = {
        tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
        value: huks.HuksKeyAlg.HUKS_ALG_RSA
    };
    properties[1] = {
        tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
        value: huks.HuksKeySize.HUKS_RSA_KEY_SIZE_1024
    };
    properties[2] = {
        tag: huks.HuksTag.HUKS_TAG_PURPOSE,
        value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT
    };
    properties[3] = {
        tag: huks.HuksTag.HUKS_TAG_PADDING,
        value: huks.HuksKeyPadding.HUKS_PADDING_OAEP
    };
    properties[4] = {
        tag: huks.HuksTag.HUKS_TAG_DIGEST,
        value: huks.HuksKeyDigest.HUKS_DIGEST_SHA256
    };
    huks.generateKey(keyalias, options, (err, data) => {
    });
}

async function huksInit() {
    return new Promise<huks.HuksHandle>((resolve, reject) => {
        huks.init(keyalias, options, async (err, data) => {
            if (data.errorCode === 0) {
                resultMessage = "init success!"
                handle = data.handle;
            } else {
                resultMessage = "init fail errorCode: " + data.errorCode
            }
        });
    });
}

async function huksUpdate() {
    options.inData = stringToUint8Array("huksHmacTest");
    new Promise<huks.HuksResult>((resolve, reject) => {
        huks.update(handle, options.inData, options, (err, data) => {
            if (data.errorCode === 0) {
                resultMessage += "update success!";
            } else {
                resultMessage += "update fail!";
            }
        });
    });
    console.log(resultMessage);

}

async function huksFinish() {
    options.inData = stringToUint8Array("0");
    new Promise<huks.HuksResult>((resolve, reject) => {
        huks.finish(handle, options, (err, data) => {
            if (data.errorCode === 0) {
                resultMessage = "finish success!";
            } else {
                resultMessage = "finish fail errorCode: " + data.errorCode;
            }
        });
    });
}

function huksAbort() {
    huks.abort(handle, options).then((data) => {
        if (data.errorCode === 0) {
            resultMessage = "abort success!";
        } else {
            resultMessage = "abort fail errorCode: " + data.errorCode;
        }
    }).catch((err: BusinessError) => {
        resultMessage = "Failed to abort the use of the key. catch errorMessage:" + JSON.stringify(err)
    });
    console.log(resultMessage);
}

HuksHandle^(deprecated)

Defines the HUKS handle structure.

System capability: SystemCapability.Security.Huks.Extension

NOTE

This API is deprecated since API version 9. You are advised to use HuksSessionHandle⁹⁺.

HuksResult^(deprecated)

Defines the HuksResult struct.

System capability: SystemCapability.Security.Huks.Extension

NOTE

• This API is deprecated since API version 9. You are advised to use HuksReturnResult⁹⁺.
• For details about the error codes, see HUKS Error Codes.

HuksErrorCode^(deprecated)

Enumerates the error codes.

System capability: SystemCapability.Security.Huks.Extension

NOTE

This API is deprecated since API version 9. You are advised to use HuksExceptionErrCode⁹⁺.