@ohos.security.cryptoFramework (Crypto Framework)

The cryptoFramework module shields underlying hardware and algorithm libraries and provides unified APIs for cryptographic operations.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import cryptoFramework from "@ohos.security.cryptoFramework";

Result

Enumerates the operation results.

System capability: SystemCapability.Security.CryptoFramework

DataBlob

Defines a buffer array of the Binary Large Object (BLOB) type.

System capability: SystemCapability.Security.CryptoFramework

NOTE

The Uint8Array typed array represents an array of 8-bit unsigned integers.

ParamsSpec

Encapsulates the parameters used for encryption or decryption. You need to construct its child class object and pass it to init() for symmetric encryption or decryption.

It applies to the symmetric cipher modes that require parameters such as the initialization vector (IV). If the IV is not required (for example, the ECB mode), pass in null to init().

System capability: SystemCapability.Security.CryptoFramework

NOTE

The params parameter in init() is of the ParamsSpec type (parent class). However, a child class object (such as IvParamsSpec) needs to be passed in. When constructing the child class object, you need to set algName for its parent class ParamsSpec to specify the child class object to be passed to init().

IvParamsSpec

Defines the child class of ParamsSpec. It is a parameter of init() for symmetric encryption or decryption.

IvParamsSpec applies to the cipher modes such as CBC, CTR, OFB, and CFB, which use only the IV.

System capability: SystemCapability.Security.CryptoFramework

NOTE

Before passing IvParamsSpec to init(), specify algName for its parent class ParamsSpec.

GcmParamsSpec

Defines the child class of ParamsSpec. It is a parameter of init() for symmetric encryption or decryption.

GcmParamsSpec applies to the GCM mode.

System capability: SystemCapability.Security.CryptoFramework

NOTE

• Before passing GcmParamsSpec to init(), specify algName for its parent class ParamsSpec.
• The IV to use is not length bound. However, the operation result depends on whether the underlying OpenSSL supports the IV.
• If aad is not required or the length of aad is 0, you can set aad to an empty Uint8Array, that is, aad: { data: new Uint8Array() }.

CcmParamsSpec

Defines the child class of ParamsSpec. It is a parameter of init() for symmetric encryption or decryption.

CcmParamsSpec applies to the CCM mode.

System capability: SystemCapability.Security.CryptoFramework

NOTE

Before passing CcmParamsSpec to init(), specify algName for its parent class ParamsSpec.

CryptoMode

Enumerates the cryptographic operations.

System capability: SystemCapability.Security.CryptoFramework

AsyKeySpecItem¹⁰⁺

Enumerates the asymmetric key parameters.

System capability: SystemCapability.Security.CryptoFramework

AsyKeySpecType¹⁰⁺

Enumerates the key parameter types.

System capability: SystemCapability.Security.CryptoFramework

CipherSpecItem¹⁰⁺

Enumerates the cipher parameters. You can use setCipherSpec to set cipher parameters, and use getCipherSpec to obtain cipher parameters.

Currently, only RSA and SM2 are supported. Since API version 11, the SM2_MD_NAME_STR parameter is supported. For details, see Asymmetric Key Encryption and Decryption Algorithm Specifications.

System capability: SystemCapability.Security.CryptoFramework

SignSpecItem¹⁰⁺

Enumerates the parameters for signing and signature verification. You can use setSignSpec and setVerifySpec to set these parameters, and use getSignSpec and getVerifySpec to obtain the parameters.

Currently, only RSA and SM2 are supported. Since API version 11, the SM2_USER_ID_UINT8ARR parameter is supported. For details, see Signing and Signature Verification Overview and Algorithm Specifications.

System capability: SystemCapability.Security.CryptoFramework

AsyKeySpec¹⁰⁺

Defines the asymmetric key parameters for creating a key generator. You need to construct a child class object and pass it to createAsyKeyGeneratorBySpec() to create a key generator. When constructing the child class object, all the parameters of the bigint type must be positive numbers in big-endian format.

System capability: SystemCapability.Security.CryptoFramework

DSACommonParamsSpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the common parameters of the public and private keys in the DSA algorithm. It can be used to randomly generate a public or private key.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

DSAPubKeySpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public key in the DSA algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

DSAKeyPairSpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify full parameters of the public and private keys in the DSA algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ECField¹⁰⁺

Defines an elliptic curve field. Currently, only the Fp field is supported.

System capability: SystemCapability.Security.CryptoFramework

ECFieldFp¹⁰⁺

Defines the prime field of the elliptic curve. It is a child class of ECField.

System capability: SystemCapability.Security.CryptoFramework

Point¹⁰⁺

Defines a point on the elliptic curve.

System capability: SystemCapability.Security.CryptoFramework

ECCCommonParamsSpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the common parameters of the public and private keys in the ECC algorithm. It can be used to randomly generate a public or private key.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ECCPriKeySpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the parameters of the private key in the ECC algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ECCPubKeySpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public key in the ECC algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ECCKeyPairSpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify full parameters of the public and private keys in the ECC algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

RSACommonParamsSpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the common parameters of the public and private keys in the RSA algorithm. It can be used to randomly generate a public or private key.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

RSAPubKeySpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public key in the RSA algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

RSAKeyPairSpec¹⁰⁺

Defines a child class of AsyKeySpec used to specify full parameters of the public and private keys in the RSA algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ED25519PriKeySpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the private key in the Ed25519 algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ED25519PubKeySpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public key in the Ed25519 algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

ED25519KeyPairSpec¹¹⁺

Defines a child class of AsyKeySpec used to specify full parameters of the public and private keys in the Ed25519 algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

X25519PriKeySpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the private key in the X25519 algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

X25519PubKeySpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public key in the X25519 algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

X25519KeyPairSpec¹¹⁺

Defines a child class of AsyKeySpec used to specify full parameters of the public and private keys in the X25519 algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

DHCommonParamsSpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public and private keys in the DH algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

DHPriKeySpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the private key in the DH algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

DHPubKeySpec¹¹⁺

Defines a child class of AsyKeySpec used to specify the parameters of the public key in the DH algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

DHKeyPairSpec¹¹⁺

Defines a child class of AsyKeySpec used to specify full parameters of the public and private keys in the DH algorithm.

To generate a key based on key parameters, pass it to createAsyKeyGeneratorBySpec() to create a key generator.

System capability: SystemCapability.Security.CryptoFramework

KdfSpec¹¹⁺

Defines the parameters of the key derivation function. When the key derivation function is used to derive a key, you need to construct and pass in a child class object of KdfSpec.

System capability: SystemCapability.Security.CryptoFramework

PBKDF2Spec¹¹⁺

Defines the child class of KdfSpec. It is used as a parameter for PBKDF2 key derivation.

System capability: SystemCapability.Security.CryptoFramework

NOTE

password specifies the original password. If password is of the string type, pass in the data used for key derivation rather than a string of the HexString or Base64 type. In addition, the string must be in utf-8 format. Otherwise, the key derived may be different from the one expected.

Key

Provides APIs for key operations. Before performing cryptographic operations (such as encryption and decryption), you need to construct a child class object of Key and pass it to init() of the Cipher instance.

Keys can be generated by a key generator.

Attributes

System capability: SystemCapability.Security.CryptoFramework

getEncoded

getEncoded(): DataBlob

Obtains the byte stream of the key data. This API returns the result synchronously. The key can be a symmetric key, public key, or private key. The public key must be in DER encoding format and comply with the ASN.1 syntax and X.509 specifications. The private key must be in DER encoding format and comply with the ASN.1 syntax and PKCS#8 specifications.

NOTE

When a key parameter is used to generate an RSA private key, the private key object does not support getEncoded().

System capability: SystemCapability.Security.CryptoFramework

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from '@ohos.security.cryptoFramework';

async function testGenerateAesKey() {
  let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256');
  let symKey = await symKeyGenerator.generateSymKey();
  let encodedKey = symKey.getEncoded();
  console.info('key hex:' + encodedKey.data);
}

SymKey

Provides APIs for symmetric key operations. It is a child class of Key. Its objects need to be passed to init() of the Cipher instance in symmetric encryption and decryption.

Symmetric keys can be generated by a SymKeyGenerator.

clearMem

clearMem(): void

Clears the keys in the memory. This API returns the result synchronously. You are advised to use this API when symmetric key instances are no longer used.

System capability: SystemCapability.Security.CryptoFramework

Example

let key: cryptoFramework.SymKey;    // The key is generated by a symKeyGenerator. The generation process is omitted here.
let encodedKey = key.getEncoded();
console.info('key blob: '+ encodedKey.data);    // Display key content.
key.clearMem();
encodedKey = key.getEncoded();
console.info('key blob: ' + encodedKey.data);  // Display all 0s.

PubKey

Provides APIs for public key operations. PubKey is a child class of Key. It needs to be passed in during asymmetric encryption and decryption, signature verification, and key agreement.

The public key can be generated by using the asymmetric key generator AsyKeyGenerator or AsyKeyGeneratorBySpec.

getAsyKeySpec¹⁰⁺

getAsyKeySpec(itemType: AsyKeySpecItem): bigint | string | number

Obtains a key parameter. This API returns the result synchronously.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let key: cryptoFramework.PubKey; // key is a public key object. The generation process is omitted here.
let p = key.getAsyKeySpec(cryptoFramework.AsyKeySpecItem.ECC_FP_P_BN);
console.info('ecc item --- p: ' + p.toString(16));

PriKey

Provides APIs for private key operations. PriKey is a child class of Key. It needs to be passed in during asymmetric encryption and decryption, signing, and key agreement.

The private key can be generated by using the asymmetric key generator AsyKeyGenerator or AsyKeyGeneratorBySpec.

clearMem

clearMem(): void

Clears the keys in the memory. This API returns the result synchronously.

System capability: SystemCapability.Security.CryptoFramework

Example

let key: cryptoFramework.PriKey; // The key is a private key generated by the asymmetric key generator. The generation process is omitted here.
key.clearMem(); // For the asymmetric private key, clearMem() releases the internal key struct. After clearMem is executed, getEncoded() is not supported.

getAsyKeySpec¹⁰⁺

getAsyKeySpec(itemType: AsyKeySpecItem): bigint | string | number

Obtains a key parameter. This API returns the result synchronously.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let key: cryptoFramework.PriKey; // key is a private key object. The generation process is omitted here.
let p = key.getAsyKeySpec(cryptoFramework.AsyKeySpecItem.ECC_FP_P_BN);
console.info('ecc item --- p: ' + p.toString(16));

KeyPair

Defines an asymmetric key pair, which includes a public key and a private key.

The asymmetric key pair can be generated by using the asymmetric key generator AsyKeyGenerator or AsyKeyGeneratorBySpec.

NOTE

The pubKey and priKey objects in the KeyPair object exist as one parameter in the KeyPair object. When KeyPair leaves the scope, its internal objects can be destructed.

The service must reference the KeyPair object instead of the internal pubKey or priKey object.

Attributes

System capability: SystemCapability.Security.CryptoFramework

cryptoFramework.createSymKeyGenerator

createSymKeyGenerator(algName: string): SymKeyGenerator

Creates a symKeyGenerator instance based on the specified algorithm.

For details about the supported specifications, see Symmetric Key Generation and Conversion Specifications.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

For details about the error codes, see Crypto Framework Error Codes.

Example

let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');

SymKeyGenerator

Provides APIs for using the symKeyGenerator.

Before using any API of the SymKeyGenerator class, you must create a SymKeyGenerator instance by using createSymKeyGenerator.

Attributes

System capability: SystemCapability.Security.CryptoFramework

generateSymKey

generateSymKey(callback: AsyncCallback<SymKey>): void

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

This API can be used only after a symKeyGenerator instance is created by using createSymKeyGenerator.

RAND_priv_bytes() of OpenSSL can be used to generate random keys.

NOTE

For the symmetric key used with the HMAC algorithm, if the hash algorithm (for example, HMAC|SHA256) is specified when the symmetric key generator is created, a binary key with the same length as the hash value will be randomly generated. For example, if HMAC|SHA256 is specified, a 256-bit key will be randomly generated.
If no hash algorithm is specified when the symmetric key generator is created (for example, only HMAC is specified), symmetric key data cannot be randomly generated. In this case, you can use convertKey to generate symmetric key data.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from '@ohos.security.cryptoFramework';

let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
  symKeyGenerator.generateSymKey((err, symKey) => {
    console.info('Generate symKey success, algName: ' + symKey.algName);
  });

generateSymKey

generateSymKey(): Promise<SymKey>

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

This API can be used only after a symKeyGenerator instance is created by using createSymKeyGenerator.

RAND_priv_bytes() of OpenSSL can be used to generate random keys.

System capability: SystemCapability.Security.CryptoFramework

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

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

let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES128');
  symKeyGenerator.generateSymKey()
    .then(symKey => {
      console.info('Generate symKey success, algName: ' + symKey.algName);
    }).catch((error: BusinessError) => {
      console.error(`Generate symKey failed, ${error.code}, ${error.message}`);
    });

convertKey

convertKey(key: DataBlob, callback: AsyncCallback<SymKey>): void

Converts data into a symmetric key. This API uses an asynchronous callback to return the result.

This API can be used only after a symKeyGenerator instance is created by using createSymKeyGenerator.

NOTE

For the symmetric key used with the HMAC algorithm, if the hash algorithm (for example, HMAC|SHA256) is specified when the symmetric key generator is created, the binary key data to be passed in must be of the same length as the hash. For example, if HMAC|SHA256 is specified, a 256-bit key must be passed in.
If no hash algorithm is specified when the symmetric key generator is created (for example, only HMAC is specified), the length of the binary key data is in the range of [1,4096], in bytes.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from '@ohos.security.cryptoFramework';

function genKeyMaterialBlob(): cryptoFramework.DataBlob {
  let arr = [
    0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
    0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
    0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes)
  let keyMaterial = new Uint8Array(arr);
  return { data: keyMaterial };
}

function testConvertKey() {
  let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
  let keyMaterialBlob = genKeyMaterialBlob();
  symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => {
    console.info('Convert symKey success, algName: ' + symKey.algName);
  });
}

convertKey

convertKey(key: DataBlob): Promise<SymKey>

Converts data into a symmetric key. This API uses a promise to return the result.

This API can be used only after a symKeyGenerator instance is created by using createSymKeyGenerator.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

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

function genKeyMaterialBlob(): cryptoFramework.DataBlob {
  let arr = [
    0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56,
    0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c,
    0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes)
  let keyMaterial = new Uint8Array(arr);
  return { data: keyMaterial };
}

function testConvertKey() {
  let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192');
  let keyMaterialBlob = genKeyMaterialBlob();
  symKeyGenerator.convertKey(keyMaterialBlob)
    .then(symKey => {
      console.info('Convert symKey success, algName: ' + symKey.algName);
    }).catch((error: BusinessError) => {
      console.error(`Convert symKey failed, ${error.code}, ${error.message}`);
    });
}

cryptoFramework.createAsyKeyGenerator

createAsyKeyGenerator(algName: string): AsyKeyGenerator

Creates an AsyKeyGenerator instance based on the specified algorithm.

For details about the supported specifications, see Asymmetric Key Generation and Conversion Specifications.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');

AsyKeyGenerator

Provides APIs for using the AsKeyGenerator. Before using any API of the AsKeyGenerator class, you must create an AsyKeyGenerator instance by using createAsyKeyGenerator().

Attributes

System capability: SystemCapability.Security.CryptoFramework

generateKeyPair

generateKeyPair(callback: AsyncCallback<KeyPair>): void

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

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from '@ohos.security.cryptoFramework';

let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');
asyKeyGenerator.generateKeyPair((err, keyPair) => {
  if (err) {
    console.error("generateKeyPair: error.");
    return;
  }
  console.info('generateKeyPair: success.');
})

generateKeyPair

generateKeyPair(): Promise<KeyPair>

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

System capability: SystemCapability.Security.CryptoFramework

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import { BusinessError } from '@ohos.base';

let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');
let keyGenPromise = asyKeyGenerator.generateKeyPair();
keyGenPromise.then(keyPair => {
  console.info('generateKeyPair success.');
}).catch((error: BusinessError) => {
  console.error("generateKeyPair error.");
});

convertKey

convertKey(pubKey: DataBlob | null, priKey: DataBlob | null, callback: AsyncCallback<KeyPair>): void

Converts data into an asymmetric key. This API uses an asynchronous callback to return the result. For details, see Key Conversion.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from '@ohos.security.cryptoFramework';

let pubKeyArray = new Uint8Array([48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7, 3, 66, 0, 4, 83, 96, 142, 9, 86, 214, 126, 106, 247, 233, 92, 125, 4, 128, 138, 105, 246, 162, 215, 71, 81, 58, 202, 121, 26, 105, 211, 55, 130, 45, 236, 143, 55, 16, 248, 75, 167, 160, 167, 106, 2, 152, 243, 44, 68, 66, 0, 167, 99, 92, 235, 215, 159, 239, 28, 106, 124, 171, 34, 145, 124, 174, 57, 92]);
let priKeyArray = new Uint8Array([48, 49, 2, 1, 1, 4, 32, 115, 56, 137, 35, 207, 0, 60, 191, 90, 61, 136, 105, 210, 16, 27, 4, 171, 57, 10, 61, 123, 40, 189, 28, 34, 207, 236, 22, 45, 223, 10, 189, 160, 10, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7]);
let pubKeyBlob: cryptoFramework.DataBlob = { data: pubKeyArray }; // Binary data of the public key.
let priKeyBlob: cryptoFramework.DataBlob = { data: priKeyArray }; // Binary data of the private key.
let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');
asyKeyGenerator.convertKey(pubKeyBlob, priKeyBlob, (err, keyPair) => {
  if (err) {
    console.error("convertKey: error.");
    return;
  }
  console.info('convertKey: success.');
});

convertKey

convertKey(pubKey: DataBlob | null, priKey: DataBlob | null): Promise<KeyPair>

Converts data into an asymmetric key. This API uses a promise to return the result. For details, see Key Conversion.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import { BusinessError } from '@ohos.base';

let pubKeyArray = new Uint8Array([48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7, 3, 66, 0, 4, 83, 96, 142, 9, 86, 214, 126, 106, 247, 233, 92, 125, 4, 128, 138, 105, 246, 162, 215, 71, 81, 58, 202, 121, 26, 105, 211, 55, 130, 45, 236, 143, 55, 16, 248, 75, 167, 160, 167, 106, 2, 152, 243, 44, 68, 66, 0, 167, 99, 92, 235, 215, 159, 239, 28, 106, 124, 171, 34, 145, 124, 174, 57, 92]);
let priKeyArray = new Uint8Array([48, 49, 2, 1, 1, 4, 32, 115, 56, 137, 35, 207, 0, 60, 191, 90, 61, 136, 105, 210, 16, 27, 4, 171, 57, 10, 61, 123, 40, 189, 28, 34, 207, 236, 22, 45, 223, 10, 189, 160, 10, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7]);
let pubKeyBlob: cryptoFramework.DataBlob = { data: pubKeyArray }; // Binary data of the public key.
let priKeyBlob: cryptoFramework.DataBlob = { data: priKeyArray }; // Binary data of the private key.
let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator('ECC256');
let keyGenPromise = asyKeyGenerator.convertKey(pubKeyBlob, priKeyBlob);
keyGenPromise.then(keyPair => {
  console.info('convertKey success.');
}).catch((error: BusinessError) => {
  console.error("convertKey error.");
});

Key Conversion

1. After getEncoded() is called for the asymmetric (RSA, ECC, or DSA) public and private keys, binary data in X.509 format and binary data in PKCS #8 format are returned, respectively. The binary data can be used for cross-application transfer or persistent storage.
2. The public key returned by convertKey() must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format, and the private key must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
3. In convertKey(), you can pass in either pubKey or priKey, or both of them. If one of them is passed in, the returned KeyPair instance contains only the key converted from the data you passed in.

cryptoFramework.createAsyKeyGeneratorBySpec¹⁰⁺

createAsyKeyGeneratorBySpec(asyKeySpec: AsyKeySpec): AsyKeyGeneratorBySpec

Creates an AsyKeyGenerator instance based on the specified key parameter.

For details about the supported specifications, see Asymmetric Key Generation and Conversion Specifications.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

// Set the common parameters of the DSA1024 public and private keys.
function genDsa1024CommonSpecBigE() {
  let dsaCommonSpec: cryptoFramework.DSACommonParamsSpec = {
    algName: "DSA",
    specType: cryptoFramework.AsyKeySpecType.COMMON_PARAMS_SPEC,
    p: BigInt("0xed1501551b8ab3547f6355ffdc2913856ddeca198833dbd04f020e5f25e47c50e0b3894f7690a0d2ea5ed3a7be25c54292a698e1f086eb3a97deb4dbf04fcad2dafd94a9f35c3ae338ab35477e16981ded6a5b13d5ff20bf55f1b262303ad3a80af71aa6aa2354d20e9c82647664bdb6b333b7bea0a5f49d55ca40bc312a1729"),
    q: BigInt("0xd23304044019d5d382cfeabf351636c7ab219694ac845051f60b047b"),
    g: BigInt("0x2cc266d8bd33c3009bd67f285a257ba74f0c3a7e12b722864632a0ac3f2c17c91c2f3f67eb2d57071ef47aaa8f8e17a21ad2c1072ee1ce281362aad01dcbcd3876455cd17e1dd55d4ed36fa011db40f0bbb8cba01d066f392b5eaa9404bfcb775f2196a6bc20eeec3db32d54e94d87ecdb7a0310a5a017c5cdb8ac78597778bd"),
  }
  return dsaCommonSpec;
}

// Set full parameters of the DSA1024 key pair.
function genDsa1024KeyPairSpecBigE() {
  let dsaCommonSpec = genDsa1024CommonSpecBigE();
  let dsaKeyPairSpec: cryptoFramework.DSAKeyPairSpec = {
    algName: "DSA",
    specType: cryptoFramework.AsyKeySpecType.KEY_PAIR_SPEC,
    params: dsaCommonSpec,
    sk: BigInt("0xa2dd2adb2d11392c2541930f61f1165c370aabd2d78d00342e0a2fd9"),
    pk: BigInt("0xae6b5d5042e758f3fc9a02d009d896df115811a75b5f7b382d8526270dbb3c029403fafb8573ba4ef0314ea86f09d01e82a14d1ebb67b0c331f41049bd6b1842658b0592e706a5e4d20c14b67977e17df7bdd464cce14b5f13bae6607760fcdf394e0b73ac70aaf141fa4dafd736bd0364b1d6e6c0d7683a5de6b9221e7f2d6b"),
  }
  return dsaKeyPairSpec;
}

let asyKeyPairSpec = genDsa1024KeyPairSpecBigE(); // The JS input must be a positive number in big-endian format.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);

AsyKeyGeneratorBySpec¹⁰⁺

Provides APIs for using the AsKeyGenerator. Before using the APIs of this class, you need to use createAsyKeyGeneratorBySpec() to create an AsyKeyGeneratorBySpec instance.

Attributes

System capability: SystemCapability.Security.CryptoFramework

generateKeyPair

generateKeyPair(callback: AsyncCallback<KeyPair>): void

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

If a key parameter of the COMMON_PARAMS_SPEC type is used to create the key generator, a key pair will be randomly generated. If a key parameter of the KEY_PAIR_SPEC type is used to create the key generator, you can obtain a key pair that is consistent with the specified key parameters.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // Use DSA as an example. asyKeyPairSpec specifies full parameters of the private and public keys. The generation process is omitted here.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
asyKeyGeneratorBySpec.generateKeyPair((err, keyPair) => {
  if (err) {
    console.error("generateKeyPair: error.");
    return;
  }
  console.info('generateKeyPair: success.');
})

generateKeyPair

generateKeyPair(): Promise<KeyPair>

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

If a key parameter of the COMMON_PARAMS_SPEC type is used to create the key generator, a key pair will be randomly generated. If a key parameter of the KEY_PAIR_SPEC type is used to create the key generator, you can obtain a key pair that is consistent with the specified key parameters.

System capability: SystemCapability.Security.CryptoFramework

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import { BusinessError } from '@ohos.base';

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // Use DSA as an example. asyKeyPairSpec specifies full parameters of the private and public keys. The generation process is omitted here.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
let keyGenPromise = asyKeyGeneratorBySpec.generateKeyPair();
keyGenPromise.then(keyPair => {
  console.info('generateKeyPair success.');
}).catch((error: BusinessError) => {
  console.error("generateKeyPair error.");
});

generatePriKey

generatePriKey(callback: AsyncCallback<PriKey>): void

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

If a key parameter of the PRIVATE_KEY_SPEC type is used to create the key generator, the specified private key can be obtained. If a key parameter of the KEY_PAIR_SPEC type is used to create the key generator, you can obtain the specified private key from the key pair generated.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // Use DSA as an example. asyKeyPairSpec specifies full parameters of the private and public keys. The generation process is omitted here.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
asyKeyGeneratorBySpec.generatePriKey((err, prikey) => {
  if (err) {
    console.error("generatePriKey: error.");
    return;
  }
  console.info('generatePriKey: success.');
})

generatePriKey

generatePriKey(): Promise<PriKey>

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

If a key parameter of the PRIVATE_KEY_SPEC type is used to create the key generator, the specified private key can be obtained. If a key parameter of the KEY_PAIR_SPEC type is used to create the key generator, you can obtain the specified private key from the key pair generated.

System capability: SystemCapability.Security.CryptoFramework

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import { BusinessError } from '@ohos.base';

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // Use DSA as an example. asyKeyPairSpec specifies full parameters of the private and public keys. The generation process is omitted here.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
let keyGenPromise = asyKeyGeneratorBySpec.generatePriKey();
keyGenPromise.then(priKey => {
  console.info('generatePriKey success.');
}).catch((error: BusinessError) => {
  console.error("generatePriKey error.");
});

generatePubKey

generatePubKey(callback: AsyncCallback<PubKey>): void

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

If a key parameter of the PUBLIC_KEY_SPEC type is used to create the key generator, the specified public key can be obtained. If a key parameter of the KEY_PAIR_SPEC type is used to create the key generator, you can obtain the specified public key from the key pair generated.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // Use DSA as an example. asyKeyPairSpec specifies full parameters of the private and public keys. The generation process is omitted here.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
asyKeyGeneratorBySpec.generatePubKey((err, pubKey) => {
  if (err) {
    console.error("generatePubKey: error.");
    return;
  }
  console.info('generatePubKey: success.');
})

generatePubKey

generatePubKey(): Promise<PubKey>

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

If a key parameter of the PUBLIC_KEY_SPEC type is used to create the key generator, the specified public key can be obtained. If a key parameter of the KEY_PAIR_SPEC type is used to create the key generator, you can obtain the specified public key from the key pair generated.

System capability: SystemCapability.Security.CryptoFramework

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import { BusinessError } from '@ohos.base';

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // Use DSA as an example. asyKeyPairSpec specifies full parameters of the private and public keys. The generation process is omitted here.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
let keyGenPromise = asyKeyGeneratorBySpec.generatePubKey();
keyGenPromise.then(pubKey => {
  console.info('generatePubKey success.');
}).catch((error: BusinessError) => {
  console.error("generatePubKey error.");
});

ECCKeyUtil¹¹⁺

Provides APIs for generating common parameters for an asymmetric key pair based on the elliptic curve name.

genECCCommonParamsSpec¹¹⁺

static genECCCommonParamsSpec(curveName: string): ECCCommonParamsSpec

Generates common parameters for an asymmetric key pair based on the specified name identifier (NID) of an elliptic curve. For details, see ECC and SM2.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from "@ohos.security.cryptoFramework";
import { BusinessError } from '@ohos.base';
try {
    let ECCCommonParamsSpec = cryptoFramework.ECCKeyUtil.genECCCommonParamsSpec('NID_brainpoolP160r1');
    console.info('genECCCommonParamsSpec success');
} catch (err) {
    let e: BusinessError = err as BusinessError;
    console.error(`genECCCommonParamsSpec error, ${e.code}, ${e.message}`);
}

DHKeyUtil¹¹⁺

Provides APIs for generating common parameters for a DH key based on the prime p length and the private key length.

genDHCommonParamsSpec¹¹⁺

static genDHCommonParamsSpec(pLen: number, skLen?: number): DHCommonParamsSpec

Generates common parameters for a DH key based on the prime p length and the private key length. For details, see DH.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import cryptoFramework from "@ohos.security.cryptoFramework";
import { BusinessError } from '@ohos.base';
try {
    let DHCommonParamsSpec = cryptoFramework.DHKeyUtil.genDHCommonParamsSpec(2048);
    console.info('genDHCommonParamsSpec success');
} catch (err) {
    let e: BusinessError = err as BusinessError;
    console.error(`genDHCommonParamsSpec error, ${e.code}, ${e.message}`);
}

cryptoFramework.createCipher

createCipher(transformation: string): Cipher

Creates a Cipher instance based on the specified algorithm.

For details about the supported specifications, see Symmetric Key Encryption and Decryption Algorithm Specifications and Asymmetric Key Encryption and Decryption Algorithm Specifications.

System capability: SystemCapability.Security.CryptoFramework

Parameters

NOTE

1. In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. noPadding indicates that no padding is performed.
   You need to understand the differences between different block cipher modes and use the correct parameter specifications. For example, padding is required for ECB and CBC. Otherwise, ensure that the plaintext length is an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
2. When RSA or SM2 is used for asymmetric encryption and decryption, create a Cipher instance for encryption and decryption respectively. Do not use the same Cipher instance for encryption and decryption. For symmetric encryption and decryption, one cipher object can be used to perform both encryption and decryption as long as the algorithm specifications are the same.

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

import { BusinessError } from '@ohos.base';

let cipherAlgName = '3DES192|ECB|PKCS7';
try {
  let cipher = cryptoFramework.createCipher(cipherAlgName);
  console.info('cipher algName: ' + cipher.algName);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`sync error, ${e.code}, ${e.message}`);
}

Cipher

Provides APIs for cipher operations. The init(), update(), and doFinal() APIs in this class are called in sequence to implement symmetric encryption or decryption and asymmetric encryption or decryption.

For details about the encryption and decryption process, see Encryption and Decryption Overview.

A complete symmetric encryption/decryption process is slightly different from the asymmetric encryption/decryption process.

• Symmetric encryption and decryption: init() and doFinal() are mandatory. update() is optional and can be called multiple times to encrypt or decrypt big data. After doFinal() is called to complete an encryption or decryption operation, init() can be called to start a new encryption or decryption operation.
• RSA or SM2 asymmetric encryption and decryption: init() and doFinal() are mandatory, and update() is not supported. doFinal() can be called multiple times to encrypt or decrypt big data. init() cannot be called repeatedly. If the encryption/decryption mode or padding mode is changed, a new Cipher object must be created.

Attributes

System capability: SystemCapability.Security.CryptoFramework

init

init(opMode: CryptoMode, key: Key, params: ParamsSpec | null, callback: AsyncCallback<void>): void

Initializes a cipher instance. This API uses an asynchronous callback to return the result. init, update, and doFinal must be used together. init and doFinal are mandatory, and update is optional.

This API can be used only after a Cipher instance is created by using createCipher.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

init

init(opMode: CryptoMode, key: Key, params: ParamsSpec | null): Promise<void>

Initializes a cipher instance. This API uses a promise to return the result. init, update, and doFinal must be used together. init and doFinal are mandatory, and update is optional.

This API can be used only after a Cipher instance is created by using createCipher.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

update

update(data: DataBlob, callback: AsyncCallback<DataBlob>): void

Updates the data to encrypt or decrypt by segment. This API uses an asynchronous callback to return the encrypted or decrypted data.

This API can be called only after the Cipher instance is initialized by using init().

NOTE

1. The update and doFinal operation results vary with the block mode used. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each update and doFinal is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext.
   For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by update is an integer multiple of the block length, and the encryption/decryption block result generated by this update is output. That is, encrypted/decrypted data is returned as long as the data passed in by update reaches the size of a block. Otherwise, null is returned and the data will be retained until a block is formed in the next update/doFinal.
   When doFinal is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in createCipher to an integer multiple of the block length, and then encrypted or decrypted.
   For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
2. You can use update multiple times or do not use it (use doFinal after init), depending on the data volume.
   The amount of the data to be passed in by update (one-time or accumulative) is not limited. If there is a large amount of data, you are advised to call update() multiple times to pass in the data by segment.
   For details about the sample code for calling update multiple times, see Encryption and Decryption by Segment with an AES Symmetric Key (GCM Mode).
3. RSA or SM2 asymmetric encryption and decryption do not support update.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

update

update(data: DataBlob): Promise<DataBlob>

Updates the data to encrypt or decrypt by segment. This API uses a promise to return the encrypted or decrypted data.

This API can be called only after the Cipher instance is initialized by using init().

NOTE

1. The update and doFinal operation results vary with the block mode used. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each update and doFinal is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext.
   
   For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by update() is an integer multiple of the block length, and the encryption/decryption block result generated by this update() is output.
   That is, encrypted/decrypted data is returned as long as the data passed in by update() reaches the size of a block. Otherwise, null is returned and the data will be retained until a block is formed in the next update()/doFinal().
   When doFinal() is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in createCipher to an integer multiple of the block length, and then encrypted or decrypted.
   For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
2. You can call update multiple times or do not use it (use doFinal after init), depending on the data volume.
   The amount of the data to be passed in by update (one-time or accumulative) is not limited. If there is a large amount of data, you are advised to call update multiple times to pass in the data by segment.
   For details about the sample code for calling update multiple times, see Encryption and Decryption by Segment with an AES Symmetric Key (GCM Mode).
3. RSA or SM2 asymmetric encryption and decryption do not support update.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

doFinal

doFinal(data: DataBlob | null, callback: AsyncCallback<DataBlob>): void

(1) Encrypts or decrypts the remaining data (generated by the block cipher mode) and the data passed in by doFinal() to finalize the symmetric encryption or decryption. This API uses an asynchronous callback to return the encrypted or decrypted data.
If a small amount of data needs to be encrypted or decrypted, you can use doFinal() to pass in data without using update(). If all the data has been passed in by update(), you can pass in null in data of doFinal().
The output of doFinal() varies with the symmetric encryption/decryption mode in use.

• Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and authTag (the last 16 bytes for GCM and the last 12 bytes for CCM). If data in doFinal is null, the result of doFinal is authTag. authTag must be GcmParamsSpec or CcmParamsSpec used for decryption. The ciphertext is the data passed in for decryption.
• Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.

(2) Encrypts or decrypts the input data for RSA or SM2 asymmetric encryption/decryption. This API uses an asynchronous callback to return the result. If a large amount of data needs to be encrypted/decrypted, call doFinal() multiple times and concatenate the result of each doFinal() to obtain the complete plaintext/ciphertext.

NOTE

1. In symmetric encryption and decryption, after doFinal is called, the encryption and decryption process is complete and the Cipher instance is cleared. When a new encryption and decryption process is started, init() must be called with a complete parameter list for initialization.
   Even if the same symmetric key is used to encrypt and decrypt the same Cipher instance, the params parameter must be set when init is called during decryption.
2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in init(). For the GCM mode, check whether the authTag obtained after encryption is obtained from the GcmParamsSpec for decryption.
3. The result of doFinal may be null. To avoid exceptions, determine whether the result is null before using the .data field to access the doFinal result.
4. For details about the sample code for calling doFinal multiple times in asymmetric encryption and decryption, see Encryption and Decryption by Segment with an RSA Asymmetric Key Pair. The operations are similar for SM2 and RSA.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Encryption with AES GCM (example)

For more encryption and decryption examples, see Encryption and Decryption with an AES Symmetric Key (GCM Mode).

import cryptoFramework from '@ohos.security.cryptoFramework';
import buffer from '@ohos.buffer';

function genGcmParamsSpec() {
  let arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
  let dataIv = new Uint8Array(arr);
  let ivBlob: cryptoFramework.DataBlob = { data: dataIv };
  arr = [0, 0, 0, 0, 0, 0, 0, 0];
  let dataAad = new Uint8Array(arr);
  let aadBlob: cryptoFramework.DataBlob = { data: dataAad };
  arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
  let dataTag = new Uint8Array(arr);
  let tagBlob: cryptoFramework.DataBlob = {
    data: dataTag
  };
  let gcmParamsSpec: cryptoFramework.GcmParamsSpec = {
    iv: ivBlob,
    aad: aadBlob,
    authTag: tagBlob,
    algName: "GcmParamsSpec"
  };
  return gcmParamsSpec;
}

function cipherByCallback() {
  let gcmParams = genGcmParamsSpec();
  let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES128');
  let cipher = cryptoFramework.createCipher('AES128|GCM|PKCS7');
  symKeyGenerator.generateSymKey((err, symKey) => {
    cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, gcmParams, (err,) => {
      let message = "This is a test";
      let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
      cipher.update(plainText, (err, encryptUpdate) => {
        cipher.doFinal(null, (err, tag) => {
          gcmParams.authTag = tag;
          console.info('encryptUpdate plainText: ' + encryptUpdate.data);
        });
      });
    });
  });
}

doFinal

doFinal(data: DataBlob | null): Promise<DataBlob>

(1) Encrypts or decrypts the remaining data (generated by the block cipher mode) and the data passed in by doFinal() to finalize the symmetric encryption or decryption. This API uses a promise to return the encrypted or decrypted data.
If a small amount of data needs to be encrypted or decrypted, you can use doFinal() to pass in data without using update(). If all the data has been passed in by update(), you can pass in null in data of doFinal().
The output of doFinal() varies with the symmetric encryption/decryption mode in use.

• Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and authTag (the last 16 bytes for GCM and the last 12 bytes for CCM). If data in doFinal is null, the result of doFinal is authTag.
  Set authTag to GcmParamsSpec or CcmParamsSpec for decryption. The ciphertext is used as the input parameter data for decryption.
• Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.

(2) Encrypts or decrypts the input data for RSA or SM2 asymmetric encryption/decryption. This API uses a promise to return the result. If a large amount of data needs to be encrypted/decrypted, call doFinal() multiple times and concatenate the result of each doFinal() to obtain the complete plaintext/ciphertext.

NOTE

1. In symmetric encryption and decryption, after doFinal is called, the encryption and decryption process is complete and the Cipher instance is cleared. When a new encryption and decryption process is started, init() must be called with a complete parameter list for initialization.
   Even if the same symmetric key is used to encrypt and decrypt the same Cipher instance, the params parameter must be set when init is called during decryption.
2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in init(). For the GCM mode, check whether the authTag obtained after encryption is obtained from the GcmParamsSpec for decryption.
3. The result of doFinal may be null. To avoid exceptions, determine whether the result is null before using the .data field to access the doFinal result.
4. For details about the sample code for calling doFinal multiple times in asymmetric encryption and decryption, see Encryption and Decryption by Segment with an RSA Asymmetric Key Pair. The operations are similar for SM2 and RSA.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Encryption with AES GCM (example)

For more encryption and decryption examples, see Encryption and Decryption with an AES Symmetric Key (GCM Mode).

import cryptoFramework from '@ohos.security.cryptoFramework';
import buffer from '@ohos.buffer';

function genGcmParamsSpec() {
  let arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
  let dataIv = new Uint8Array(arr);
  let ivBlob: cryptoFramework.DataBlob = { data: dataIv };
  arr = [0, 0, 0, 0, 0, 0, 0, 0];
  let dataAad = new Uint8Array(arr);
  let aadBlob: cryptoFramework.DataBlob = { data: dataAad };
  arr = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
  let dataTag = new Uint8Array(arr);
  let tagBlob: cryptoFramework.DataBlob = {
    data: dataTag
  };
  let gcmParamsSpec: cryptoFramework.GcmParamsSpec = {
    iv: ivBlob,
    aad: aadBlob,
    authTag: tagBlob,
    algName: "GcmParamsSpec"
  };
  return gcmParamsSpec;
}

async function cipherByPromise() {
  let gcmParams = genGcmParamsSpec();
  let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES128');
  let cipher = cryptoFramework.createCipher('AES128|GCM|PKCS7');
  let symKey = await symKeyGenerator.generateSymKey();
  await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, gcmParams);
  let message = "This is a test";
  let plainText: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from(message, 'utf-8').buffer) };
  let encryptUpdate = await cipher.update(plainText);
  gcmParams.authTag = await cipher.doFinal(null);
  console.info('encryptUpdate plainText: ' + encryptUpdate.data);
}

setCipherSpec¹⁰⁺

setCipherSpec(itemType: CipherSpecItem, itemValue: Uint8Array): void

Sets cipher specifications. You can use this API to set cipher specifications that cannot be set by createCipher. Currently, only RSA is supported.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let cipher: cryptoFramework.Cipher; // The process of generating the Cipher instance is omitted here.
let pSource = new Uint8Array([1,2,3,4]);
cipher.setCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MGF1_PSRC_UINT8ARR, pSource);

getCipherSpec¹⁰⁺

getCipherSpec(itemType: CipherSpecItem): string | Uint8Array

Obtains cipher specifications. Currently, only RSA and SM2 (available since API version 11) are supported.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let cipher: cryptoFramework.Cipher; // The process of generating the Cipher instance is omitted here.
let mdName = cipher.getCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MD_NAME_STR);

cryptoFramework.createSign

createSign(algName: string): Sign

Creates a Sign instance.

For details about the supported specifications, see Signing and Signature Verification Overview and Algorithm Specifications.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let signer1 = cryptoFramework.createSign('RSA1024|PKCS1|SHA256');

let signer2 = cryptoFramework.createSign('RSA1024|PSS|SHA256|MGF1_SHA256');

let signer3 = cryptoFramework.createSign('ECC224|SHA256');

let signer4 = cryptoFramework.createSign('DSA2048|SHA256');

Sign

Provides APIs for signing. Before using any API of the Sign class, you must create a Sign instance by using createSign(algName: string): Sign. Invoke init(), update(), and sign() in this class in sequence to complete the signing operation. For details about the sample code, see Signing and Signature Verification with an RSA Key Pair (PKCS1 Mode).

The Sign class does not support repeated initialization. When a new key is used for signing, you must create a new Sign instance and call init() for initialization.

The signing mode is determined in createSign(), and the key is set by init().

If the data to be signed is short, you can directly call sign() to pass in the original data for signing after init(). That is, you do not need to use update().

If the data to be signed is long, you can use update() to pass in the data by segment, and then use sign() to sign the entire data.

When update() is used, the sign() API supports only DataBlob in versions earlier than API version 10 and starts to support null since API version 10. After all the data is passed in by using update(), sign() can be called to sign the data.

Attributes

System capability: SystemCapability.Security.CryptoFramework

init

init(priKey: PriKey, callback: AsyncCallback<void>): void

Initializes the Sign instance with a private key. This API uses an asynchronous callback to return the result. init, update, and sign must be used together. init and sign are mandatory, and update is optional.

The Sign class does not support repeated use of init().

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

init

init(priKey: PriKey): Promise<void>

Initializes the Sign instance with a private key. This API uses a promise to return the result. init, update, and sign must be used together. init and sign are mandatory, and update is optional.

The Sign class does not support repeated use of init().

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

update

update(data: DataBlob, callback: AsyncCallback<void>): void

Updates the data to be signed. This API uses an asynchronous callback to return the result.

This API can be called only after the Sign instance is initialized by using init().

NOTE

You can call update multiple times or do not use update (call sign after init), depending on the data volume.
The amount of the data to be passed in by update (one-time or accumulative) is not limited. If there is a large amount of data, you are advised to call update multiple times to pass in the data by segment. This prevents too much memory from being requested at a time.
For details about the sample code for calling update multiple times in signing, see Signing and Signature Verification by Segment with an RSA Key Pair (PKCS1 Mode). The operations of other algorithms are similar.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

update

update(data: DataBlob): Promise<void>

Updates the data to be signed. This API uses a promise to return the result.

This API can be called only after the Sign instance is initialized by using init().

NOTE

You can call update multiple times or do not use update (call sign after init), depending on the data volume.
The amount of the data to be passed in by update (one-time or accumulative) is not limited. If there is a large amount of data, you are advised to call update multiple times to pass in the data by segment. This prevents too much memory from being requested at a time.
For details about the sample code for calling update multiple times in signing, see Signing and Signature Verification by Segment with an RSA Key Pair (PKCS1 Mode). The operations of other algorithms are similar.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

sign

sign(data: DataBlob | null, callback: AsyncCallback<DataBlob>): void

Signs the data. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

sign

sign(data: DataBlob | null): Promise<DataBlob>

Signs the data. This API uses a promise to return the result.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Callback example:

For more examples of signing and signature verification, see Signing and Signature Verification with an RSA Key Pair (PKCS1 Mode).

import cryptoFramework from '@ohos.security.cryptoFramework';
import buffer from '@ohos.buffer';

function signByCallback() {
  let inputUpdate: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from("This is Sign test plan1", 'utf-8').buffer) };
  let inputVerify: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from("This is Sign test plan2", 'utf-8').buffer) };
  let pkData = new Uint8Array([48, 129, 159, 48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0, 3, 129, 141, 0, 48, 129, 137, 2, 129, 129, 0, 214, 179, 23, 198, 183, 139, 148, 8, 173, 74, 56, 160, 15, 248, 244, 166, 209, 250, 142, 74, 216, 58, 117, 215, 178, 247, 254, 39, 180, 227, 85, 201, 59, 133, 209, 221, 26, 9, 116, 31, 172, 151, 252, 185, 123, 20, 25, 7, 92, 129, 5, 196, 239, 214, 126, 254, 154, 188, 239, 144, 161, 171, 65, 42, 31, 214, 93, 115, 247, 69, 94, 143, 54, 51, 25, 49, 146, 204, 205, 165, 20, 120, 35, 184, 190, 65, 106, 12, 214, 176, 57, 125, 235, 51, 88, 135, 76, 73, 109, 112, 147, 138, 198, 252, 5, 20, 245, 51, 7, 32, 108, 89, 125, 204, 50, 189, 88, 254, 255, 146, 244, 244, 149, 79, 54, 216, 45, 89, 2, 3, 1, 0, 1]);
  let skData = new Uint8Array([48, 130, 2, 120, 2, 1, 0, 48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0, 4, 130, 2, 98, 48, 130, 2, 94, 2, 1, 0, 2, 129, 129, 0, 214, 179, 23, 198, 183, 139, 148, 8, 173, 74, 56, 160, 15, 248, 244, 166, 209, 250, 142, 74, 216, 58, 117, 215, 178, 247, 254, 39, 180, 227, 85, 201, 59, 133, 209, 221, 26, 9, 116, 31, 172, 151, 252, 185, 123, 20, 25, 7, 92, 129, 5, 196, 239, 214, 126, 254, 154, 188, 239, 144, 161, 171, 65, 42, 31, 214, 93, 115, 247, 69, 94, 143, 54, 51, 25, 49, 146, 204, 205, 165, 20, 120, 35, 184, 190, 65, 106, 12, 214, 176, 57, 125, 235, 51, 88, 135, 76, 73, 109, 112, 147, 138, 198, 252, 5, 20, 245, 51, 7, 32, 108, 89, 125, 204, 50, 189, 88, 254, 255, 146, 244, 244, 149, 79, 54, 216, 45, 89, 2, 3, 1, 0, 1, 2, 129, 129, 0, 152, 111, 145, 203, 10, 88, 116, 163, 112, 126, 9, 20, 68, 34, 235, 121, 98, 14, 182, 102, 151, 125, 114, 91, 210, 122, 215, 29, 212, 5, 176, 203, 238, 146, 5, 190, 41, 21, 91, 56, 125, 239, 111, 133, 53, 200, 192, 56, 132, 202, 42, 145, 120, 3, 224, 40, 223, 46, 148, 29, 41, 92, 17, 40, 12, 72, 165, 69, 192, 211, 142, 233, 81, 202, 177, 235, 156, 27, 179, 48, 18, 85, 154, 101, 193, 45, 218, 91, 24, 143, 196, 248, 16, 83, 177, 198, 136, 77, 111, 134, 60, 219, 95, 246, 23, 5, 45, 14, 83, 29, 137, 248, 159, 28, 132, 142, 205, 99, 226, 213, 84, 232, 57, 130, 156, 81, 191, 237, 2, 65, 0, 255, 158, 212, 13, 43, 132, 244, 135, 148, 161, 232, 219, 20, 81, 196, 102, 103, 44, 110, 71, 100, 62, 73, 200, 32, 138, 114, 209, 171, 150, 179, 92, 198, 5, 190, 218, 79, 227, 227, 37, 32, 57, 159, 252, 107, 211, 139, 198, 202, 248, 137, 143, 186, 205, 106, 81, 85, 207, 134, 148, 110, 204, 243, 27, 2, 65, 0, 215, 4, 181, 121, 57, 224, 170, 168, 183, 159, 152, 8, 74, 233, 80, 244, 146, 81, 48, 159, 194, 199, 36, 187, 6, 181, 182, 223, 115, 133, 151, 171, 78, 219, 90, 161, 248, 69, 6, 207, 173, 3, 81, 161, 2, 60, 238, 204, 177, 12, 138, 17, 220, 179, 71, 113, 200, 248, 159, 153, 252, 150, 180, 155, 2, 65, 0, 190, 202, 185, 211, 170, 171, 238, 40, 84, 84, 21, 13, 144, 57, 7, 178, 183, 71, 126, 120, 98, 229, 235, 4, 40, 229, 173, 149, 185, 209, 29, 199, 29, 54, 164, 161, 38, 8, 30, 62, 83, 179, 47, 42, 165, 0, 156, 207, 160, 39, 169, 229, 81, 180, 136, 170, 116, 182, 20, 233, 45, 90, 100, 9, 2, 65, 0, 152, 255, 47, 198, 15, 201, 238, 133, 89, 11, 133, 153, 184, 252, 37, 239, 177, 65, 118, 80, 231, 190, 222, 66, 250, 118, 72, 166, 221, 67, 156, 245, 119, 138, 28, 6, 142, 107, 71, 122, 116, 200, 156, 199, 237, 152, 191, 239, 4, 184, 64, 114, 143, 81, 62, 48, 23, 233, 217, 95, 47, 221, 104, 171, 2, 64, 30, 219, 1, 230, 241, 70, 246, 243, 121, 174, 67, 66, 11, 99, 202, 17, 52, 234, 78, 29, 3, 57, 51, 123, 149, 86, 64, 192, 73, 199, 108, 101, 55, 232, 41, 114, 153, 237, 253, 52, 205, 148, 45, 86, 186, 241, 182, 183, 42, 77, 252, 195, 29, 158, 173, 3, 182, 207, 254, 61, 71, 184, 167, 184]);
  let pubKeyBlob: cryptoFramework.DataBlob = { data: pkData };
  let priKeyBlob: cryptoFramework.DataBlob = { data: skData };
  let rsaGenerator = cryptoFramework.createAsyKeyGenerator('RSA1024');
  let signer = cryptoFramework.createSign('RSA1024|PKCS1|SHA256');
  rsaGenerator.convertKey(pubKeyBlob, priKeyBlob, (err, keyPair) => {
    signer.init(keyPair.priKey, err => {
      signer.update(inputUpdate, err => {
        signer.sign(inputVerify, (err, signData) => {
          console.info('sign output is ' + signData.data);
        });
      });
    });
  });
}

Example (promise)

For more examples of signing and signature verification, see Signing and Signature Verification with an RSA Key Pair (PKCS1 Mode).

import cryptoFramework from '@ohos.security.cryptoFramework';
import buffer from '@ohos.buffer';

async function genKeyPairByData(pubKeyData: Uint8Array, priKeyData: Uint8Array) {
  let pubKeyBlob: cryptoFramework.DataBlob = { data: pubKeyData };
  let priKeyBlob: cryptoFramework.DataBlob = { data: priKeyData };
  let rsaGenerator = cryptoFramework.createAsyKeyGenerator('RSA1024');
  let keyPair = await rsaGenerator.convertKey(pubKeyBlob, priKeyBlob);
  console.info('convertKey success');
  return keyPair;
}

async function signByPromise() {
  let pkData = new Uint8Array([48, 129, 159, 48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0, 3, 129, 141, 0, 48, 129, 137, 2, 129, 129, 0, 214, 179, 23, 198, 183, 139, 148, 8, 173, 74, 56, 160, 15, 248, 244, 166, 209, 250, 142, 74, 216, 58, 117, 215, 178, 247, 254, 39, 180, 227, 85, 201, 59, 133, 209, 221, 26, 9, 116, 31, 172, 151, 252, 185, 123, 20, 25, 7, 92, 129, 5, 196, 239, 214, 126, 254, 154, 188, 239, 144, 161, 171, 65, 42, 31, 214, 93, 115, 247, 69, 94, 143, 54, 51, 25, 49, 146, 204, 205, 165, 20, 120, 35, 184, 190, 65, 106, 12, 214, 176, 57, 125, 235, 51, 88, 135, 76, 73, 109, 112, 147, 138, 198, 252, 5, 20, 245, 51, 7, 32, 108, 89, 125, 204, 50, 189, 88, 254, 255, 146, 244, 244, 149, 79, 54, 216, 45, 89, 2, 3, 1, 0, 1]);
  let skData = new Uint8Array([48, 130, 2, 120, 2, 1, 0, 48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0, 4, 130, 2, 98, 48, 130, 2, 94, 2, 1, 0, 2, 129, 129, 0, 214, 179, 23, 198, 183, 139, 148, 8, 173, 74, 56, 160, 15, 248, 244, 166, 209, 250, 142, 74, 216, 58, 117, 215, 178, 247, 254, 39, 180, 227, 85, 201, 59, 133, 209, 221, 26, 9, 116, 31, 172, 151, 252, 185, 123, 20, 25, 7, 92, 129, 5, 196, 239, 214, 126, 254, 154, 188, 239, 144, 161, 171, 65, 42, 31, 214, 93, 115, 247, 69, 94, 143, 54, 51, 25, 49, 146, 204, 205, 165, 20, 120, 35, 184, 190, 65, 106, 12, 214, 176, 57, 125, 235, 51, 88, 135, 76, 73, 109, 112, 147, 138, 198, 252, 5, 20, 245, 51, 7, 32, 108, 89, 125, 204, 50, 189, 88, 254, 255, 146, 244, 244, 149, 79, 54, 216, 45, 89, 2, 3, 1, 0, 1, 2, 129, 129, 0, 152, 111, 145, 203, 10, 88, 116, 163, 112, 126, 9, 20, 68, 34, 235, 121, 98, 14, 182, 102, 151, 125, 114, 91, 210, 122, 215, 29, 212, 5, 176, 203, 238, 146, 5, 190, 41, 21, 91, 56, 125, 239, 111, 133, 53, 200, 192, 56, 132, 202, 42, 145, 120, 3, 224, 40, 223, 46, 148, 29, 41, 92, 17, 40, 12, 72, 165, 69, 192, 211, 142, 233, 81, 202, 177, 235, 156, 27, 179, 48, 18, 85, 154, 101, 193, 45, 218, 91, 24, 143, 196, 248, 16, 83, 177, 198, 136, 77, 111, 134, 60, 219, 95, 246, 23, 5, 45, 14, 83, 29, 137, 248, 159, 28, 132, 142, 205, 99, 226, 213, 84, 232, 57, 130, 156, 81, 191, 237, 2, 65, 0, 255, 158, 212, 13, 43, 132, 244, 135, 148, 161, 232, 219, 20, 81, 196, 102, 103, 44, 110, 71, 100, 62, 73, 200, 32, 138, 114, 209, 171, 150, 179, 92, 198, 5, 190, 218, 79, 227, 227, 37, 32, 57, 159, 252, 107, 211, 139, 198, 202, 248, 137, 143, 186, 205, 106, 81, 85, 207, 134, 148, 110, 204, 243, 27, 2, 65, 0, 215, 4, 181, 121, 57, 224, 170, 168, 183, 159, 152, 8, 74, 233, 80, 244, 146, 81, 48, 159, 194, 199, 36, 187, 6, 181, 182, 223, 115, 133, 151, 171, 78, 219, 90, 161, 248, 69, 6, 207, 173, 3, 81, 161, 2, 60, 238, 204, 177, 12, 138, 17, 220, 179, 71, 113, 200, 248, 159, 153, 252, 150, 180, 155, 2, 65, 0, 190, 202, 185, 211, 170, 171, 238, 40, 84, 84, 21, 13, 144, 57, 7, 178, 183, 71, 126, 120, 98, 229, 235, 4, 40, 229, 173, 149, 185, 209, 29, 199, 29, 54, 164, 161, 38, 8, 30, 62, 83, 179, 47, 42, 165, 0, 156, 207, 160, 39, 169, 229, 81, 180, 136, 170, 116, 182, 20, 233, 45, 90, 100, 9, 2, 65, 0, 152, 255, 47, 198, 15, 201, 238, 133, 89, 11, 133, 153, 184, 252, 37, 239, 177, 65, 118, 80, 231, 190, 222, 66, 250, 118, 72, 166, 221, 67, 156, 245, 119, 138, 28, 6, 142, 107, 71, 122, 116, 200, 156, 199, 237, 152, 191, 239, 4, 184, 64, 114, 143, 81, 62, 48, 23, 233, 217, 95, 47, 221, 104, 171, 2, 64, 30, 219, 1, 230, 241, 70, 246, 243, 121, 174, 67, 66, 11, 99, 202, 17, 52, 234, 78, 29, 3, 57, 51, 123, 149, 86, 64, 192, 73, 199, 108, 101, 55, 232, 41, 114, 153, 237, 253, 52, 205, 148, 45, 86, 186, 241, 182, 183, 42, 77, 252, 195, 29, 158, 173, 3, 182, 207, 254, 61, 71, 184, 167, 184]);
  let keyPair = await genKeyPairByData(pkData, skData);
  let inputUpdate: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from("This is Sign test plan1", 'utf-8').buffer) };
  let inputSign: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from("This is Sign test plan2", 'utf-8').buffer) };
  let signer = cryptoFramework.createSign('RSA1024|PKCS1|SHA256');
  await signer.init(keyPair.priKey);
  await signer.update(inputUpdate);
  let signData = await signer.sign(inputSign);
  console.info('signData result: ' + signData.data);
}

setSignSpec¹⁰⁺

setSignSpec(itemType: SignSpecItem, itemValue: number): void

setSignSpec(itemType: SignSpecItem, itemValue: number | Uint8Array): void

Sets signing specifications. You can use this API to set signing parameters that cannot be set by createSign.

Currently, only RSA and SM2 are supported. Since API version 11, SM2 signing parameters can be set.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let signer: cryptoFramework.Sign; // The process of generating the Sign instance is omitted here.
let setN = 20;
signer.setSignSpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM, setN);

getSignSpec¹⁰⁺

getSignSpec(itemType: SignSpecItem): string | number

Obtains signing specifications. Currently, only RSA is supported.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let signer: cryptoFramework.Sign; // The process of generating the Sign instance is omitted here.
let saltLen = signer.getSignSpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM);

cryptoFramework.createVerify

createVerify(algName: string): Verify

Creates a Verify instance.

For details about the supported specifications, see Signing and Signature Verification Overview and Algorithm Specifications.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Example

let verifyer1 = cryptoFramework.createVerify('RSA1024|PKCS1|SHA256');

let verifyer2 = cryptoFramework.createVerify('RSA1024|PSS|SHA256|MGF1_SHA256');

Verify

Provides APIs for signature verification. Before using any API of the Verify class, you must create a Verify instance by using createVerify(algName: string): Verify. Invoke init(), update(), and sign() in this class in sequence to complete the signature verification. For details about the sample code, see Signing and Signature Verification with an RSA Key Pair (PKCS1 Mode).

The Verify class does not support repeated initialization. When a new key is used for signature verification, you must create a new Verify instance and call init() for initialization.

The signature verification mode is determined in createVerify(), and the key is set by init().

If the signed message is short, you can call verify() to pass in the signed message and signature (signatureData) for signature verification after init(). That is, you do not need to use update().

If the signed message is too long, you can call update() multiple times to pass in the signed message by segment, and then call verify() to verify the full text of the message. In versions earlier than API version 10, the input parameter data of verify() supports only DataBlob. Since API version 10, data also supports null. After all the data is passed in by using update(), verify() can be called to verify the signature data.

Attributes

System capability: SystemCapability.Security.CryptoFramework

init

init(pubKey: PubKey, callback: AsyncCallback<void>): void

Initializes the Verify instance with a public key. This API uses an asynchronous callback to return the result. init, update, and verify must be used together. init and verify are mandatory, and update is optional.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

init

init(pubKey: PubKey): Promise<void>

Initializes the Verify instance with a public key. This API uses a promise to return the result. init, update, and verify must be used together. init and verify are mandatory, and update is optional.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

update

update(data: DataBlob, callback: AsyncCallback<void>): void

Updates the data for signature verification. This API uses an asynchronous callback to return the result.

This API can be called only after the Verify instance is initialized using init().

NOTE

You can call update multiple times or do not use update (call verify after init), depending on the data volume.
The amount of the data to be passed in by update (one-time or accumulative) is not limited. If there is a large amount of data, you are advised to call update multiple times to pass in the data by segment. This prevents too much memory from being requested at a time.
For details about the sample code for calling update multiple times in signature verification, see Signing and Signature Verification by Segment with an RSA Key Pair (PKCS1 Mode). The operations of other algorithms are similar.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

update

update(data: DataBlob): Promise<void>

Updates the data for signature verifications. This API uses a promise to return the result.

This API can be called only after the Verify instance is initialized using init().

NOTE

You can call update multiple times or do not use update (call verify after init), depending on the data volume.
The amount of the data to be passed in by update (one-time or accumulative) is not limited. If there is a large amount of data, you are advised to call update multiple times to pass in the data by segment. This prevents too much memory from being requested at a time.
For details about the sample code for calling update multiple times in signature verification, see Signing and Signature Verification by Segment with an RSA Key Pair (PKCS1 Mode). The operations of other algorithms are similar.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

verify

verify(data: DataBlob | null, signatureData: DataBlob, callback: AsyncCallback<boolean>): void

Verifies the signature. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Error codes For details about the error codes, see Crypto Framework Error Codes.

verify

verify(data: DataBlob | null, signatureData: DataBlob): Promise<boolean>

Verifies the signature. This API uses a promise to return the result.

System capability: SystemCapability.Security.CryptoFramework

Parameters

Return value

Error codes For details about the error codes, see Crypto Framework Error Codes.

Callback example:

For more examples of signing and signature verification, see Signing and Signature Verification with an RSA Key Pair (PKCS1 Mode).

import cryptoFramework from '@ohos.security.cryptoFramework';
import buffer from '@ohos.buffer';

function verifyByCallback() {
  let inputUpdate: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from("This is Sign test plan1", 'utf-8').buffer) };
  let inputVerify: cryptoFramework.DataBlob = { data: new Uint8Array(buffer.from("This is Sign test plan2", 'utf-8').buffer) };
  // Key generated based on the key data and input data for signature verification. If the data in verify() is the same as that in sign(), the signature verification is successful.
  let pkData = new Uint8Array([48, 129, 159, 48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0, 3, 129, 141, 0, 48, 129, 137, 2, 129, 129, 0, 214, 179, 23, 198, 183, 139, 148, 8, 173, 74, 56, 160, 15, 248, 244, 166, 209, 250, 142, 74, 216, 58, 117, 215, 178, 247, 254, 39, 180, 227, 85, 201, 59, 133, 209, 221, 26, 9, 116, 31, 172, 151, 252, 185, 123, 20, 25, 7, 92, 129, 5, 196, 239, 214, 126, 254, 154, 188, 239, 144, 161, 171, 65, 42, 31, 214, 93, 115, 247, 69, 94, 143, 54, 51, 25, 49, 146, 204, 205, 165, 20, 120, 35, 184, 190, 65, 106, 12, 214, 176, 57, 125, 235, 51, 88, 135, 76, 73, 109, 112, 147, 138, 198, 252, 5, 20, 245, 51, 7, 32, 108, 89, 125, 204, 50, 189, 88, 254, 255, 146, 244, 244, 149, 79, 54, 216, 45, 89, 2, 3, 1, 0, 1]);
  let skData = new Uint8Array([48, 130, 2, 120, 2, 1, 0, 48, 13, 6, 9, 42, 134, 72, 134, 247, 13, 1, 1, 1, 5, 0, 4, 130, 2, 98, 48, 130, 2, 94, 2, 1, 0, 2, 129, 129, 0, 214, 179, 23, 198, 183, 139, 148, 8, 173, 74, 56, 160, 15, 248, 244, 166, 209, 250, 142, 74, 216, 58, 117, 215, 178, 247, 254, 39, 180, 227, 85, 201, 59, 133, 209, 221, 26, 9, 116, 31, 172, 151, 252, 185, 123, 20, 25, 7, 92, 129, 5, 196, 239, 214, 126, 254, 154, 188, 239, 144, 161, 171, 65, 42, 31, 214, 93, 115, 247, 69, 94, 143, 54, 51, 25, 49, 146, 204, 205, 165, 20, 120, 35, 184, 190, 65, 106, 12, 214, 176, 57, 125, 235, 51, 88, 135, 76, 73, 109, 112, 147, 138, 198, 252, 5, 20, 245, 51, 7, 32, 108, 89, 125, 204, 50, 189, 88, 254, 255, 146, 244, 244, 149, 79, 54, 216, 45, 89, 2, 3, 1, 0, 1, 2, 129, 129, 0, 152, 111, 145, 203, 10, 88, 116, 163, 112, 126, 9, 20, 68, 34, 235, 121, 98, 14, 182, 102, 151, 125, 114, 91, 210, 122, 215, 29, 212, 5, 176, 203, 238, 146, 5, 190, 41, 21, 91, 56, 125, 239, 111, 133, 53, 200, 192, 56, 132, 202, 42, 145, 120, 3, 224, 40, 223, 46, 148, 29, 41, 92, 17, 40, 12, 72, 165, 69, 192, 211, 142, 233, 81, 202, 177, 235, 156, 27, 179, 48, 18, 85, 154, 101, 193, 45, 218, 91, 24, 143, 196, 248, 16, 83, 177, 198, 136, 77, 111, 134, 60, 219, 95, 246, 23, 5, 45, 14, 83, 29, 137, 248, 159, 28, 132, 142, 205, 99, 226, 213, 84, 232, 57, 130, 156, 81, 191, 237, 2, 65, 0, 255, 158, 212, 13, 43, 132, 244, 135, 148, 161, 232, 219, 20, 81, 196, 102, 103, 44, 110, 71, 100, 62, 73, 200, 32, 138, 114, 209, 171, 150, 179, 92, 198, 5, 190, 218, 79, 227, 227, 37, 32, 57, 159, 252, 107, 211, 139, 198, 202, 248, 137, 143, 186, 205, 106, 81, 85, 207, 134, 148, 110, 204, 243, 27, 2, 65, 0, 215, 4, 181, 121, 57, 224, 170, 168, 183, 159, 152, 8, 74, 233, 80, 244, 146, 81, 48, 159, 194, 199, 36, 187, 6, 181, 182, 223, 115, 133, 151, 171, 78, 219, 90, 161, 248, 69, 6, 207, 173, 3, 81, 161, 2, 60, 238, 204, 177, 12, 138, 17, 220, 179, 71, 113, 200, 248, 159, 153, 252, 150, 180, 155, 2, 65, 0, 190, 202, 185, 211, 170, 171, 238, 40, 84, 84, 21, 13, 144, 57, 7, 178, 183, 71, 126, 120, 98, 229, 235, 4, 40, 229, 173, 149, 185, 209, 29, 199, 29, 54, 164, 161, 38, 8, 30, 62, 83, 179, 47, 42, 165, 0, 156, 207, 160, 39, 169, 229, 81, 180, 136, 170, 116, 182, 20, 233, 45, 90, 100, 9, 2, 65, 0, 152, 255, 47, 198, 15, 201, 238, 133, 89, 11, 133, 153, 184, 252, 37, 239, 177, 65, 118, 80, 231, 190, 222, 66, 250, 118, 72, 166, 221, 67, 156, 245, 119, 138, 28, 6, 142, 107, 71, 122, 116, 200, 156, 199, 237, 152, 191, 239, 4, 184, 64, 114, 143, 81, 62, 48, 23, 233, 217, 95, 47, 221, 104, 171, 2, 64, 30, 219, 1, 230, 241, 70, 246, 243, 121, 174, 67, 66, 11, 99, 202, 17, 52, 234, 78, 29, 3, 57, 51, 123, 149, 86, 64, 192, 73, 199, 108, 101, 55, 232, 41, 114, 153, 237, 253, 52, 205, 148, 45, 86, 186, 241, 182, 183, 42, 77, 252, 195, 29, 158, 173, 3, 182, 207, 254, 61, 71, 184, 167, 184]);
  let pubKeyBlob: cryptoFramework.DataBlob = { data: pkData };
  let priKeyBlob: cryptoFramework.DataBlob = { data: skData };
  // The data is signData.data in Sign().
  let signMessageBlob: cryptoFramework.DataBlob = { data: new Uint8Array([9, 68, 164, 161, 230, 155, 255, 153, 10, 12, 14, 22, 146, 115, 209, 167, 223, 133, 89, 173, 50, 249, 176, 104, 10, 251, 219, 104, 117, 196, 105, 65, 249, 139, 119, 41, 15, 171, 191, 11, 177, 177, 1, 119, 130, 142, 87, 183, 32, 220, 226, 28, 38, 73, 222, 172, 153, 26, 87, 58, 188, 42, 150, 67, 94, 214, 147, 64, 202, 87, 155, 125, 254, 112, 95, 176, 255, 207, 106, 43, 228, 153, 131, 240, 120, 88, 253, 179, 207, 207, 110, 223, 173, 15, 113, 11, 183, 122, 237, 205, 206, 123, 246, 33, 167, 169, 251, 237, 199, 26, 220, 152, 190, 117, 131, 74, 232, 50, 39, 172, 232, 178, 112, 73, 251, 235, 131, 209]) }
  let rsaGenerator = cryptoFramework.createAsyKeyGenerator('RSA1024');
  let verifyer = cryptoFramework.createVerify('RSA1024|PKCS1|SHA256');
  rsaGenerator.convertKey(pubKeyBlob, priKeyBlob, (err, keyPair) => {
    verifyer.init(keyPair.pubKey, err => {
      verifyer.update(inputUpdate, err => {
        verifyer.verify(inputVerify, signMessageBlob, (err, res) => {
          console.info('verify result is ' + res);
        });
      });
    });
  });
}