@ohos.security.cryptoFramework (加解密算法库框架)

为屏蔽底层硬件和算法库,向上提供统一的密码算法库加解密相关接口。

说明:

  • 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
  • 以下示例代码片段仅适用于JS语言开发。

导入模块

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

Result

表示执行结果的枚举。

系统能力: SystemCapability.Security.CryptoFramework

名称 说明
INVALID_PARAMS 401 非法入参。
NOT_SUPPORT 801 操作不支持。
ERR_OUT_OF_MEMORY 17620001 内存错误。
ERR_RUNTIME_ERROR 17620002 运行时外部错误。
ERR_CRYPTO_OPERATION 17630001 调用三方算法库API出错。

DataBlob

buffer数组,提供blob数据类型。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
data Uint8Array 数据。

ParamsSpec

加解密参数,在进行对称加解密时需要构造其子类对象,并将子类对象传入init()方法。

适用于需要iv等参数的对称加解密模式(对于无iv等参数的模式如ECB模式,无需构造,在init()中传入null即可)。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC|CTR|OFB|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式

说明:

由于init()的params参数是ParamsSpec类型(父类),而实际需要传入具体的子类对象(如IvParamsSpec),因此在构造子类对象时应设置其父类ParamsSpec的algName参数,使算法库在init()时知道传入的是哪种子类对象。

IvParamsSpec

加解密参数ParamsSpec的子类,用于在对称加解密时作为init()方法的参数。

适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
iv DataBlob 指明加解密参数iv。常见取值如下:
- AES的CBC|CTR|OFB|CFB模式:iv长度为16字节
- 3DES的CBC|OFB|CFB模式:iv长度为8字节
- SM410+的CBC|CTR|OFB|CFB模式:iv长度为16字节。

说明:

传入init()方法前需要指定其algName属性(来源于父类ParamsSpec)。

GcmParamsSpec

加解密参数ParamsSpec的子类,用于在对称加解密时作为init()方法的参数。

适用于GCM模式。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
iv DataBlob 指明加解密参数iv,长度为12字节。
aad DataBlob 指明加解密参数aad,长度为8字节。
authTag DataBlob 指明加解密参数authTag,长度为16字节。
采用GCM模式加密时,需要获取doFinal()输出的DataBlob,取出其末尾16字节作为解密时init()方法的入参GcmParamsSpec中的的authTag。

说明:

传入init()方法前需要指定其algName属性(来源于父类ParamsSpec)。

CcmParamsSpec

加解密参数ParamsSpec的子类,用于在对称加解密时作为init()方法的参数。

适用于CCM模式。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
iv DataBlob 指明加解密参数iv,长度为7字节。
aad DataBlob 指明加解密参数aad,长度为8字节。
authTag DataBlob 指明加解密参数authTag,长度为12字节。
采用CCM模式加密时,需要获取doFinal()输出的DataBlob,取出其末尾12字节作为解密时init()方法的入参CcmParamsSpec中的authTag。

说明:

传入init()方法前需要指定其algName属性(来源于父类ParamsSpec)。

CryptoMode

表示加解密操作的枚举。

系统能力: SystemCapability.Security.CryptoFramework

名称 说明
ENCRYPT_MODE 0 表示进行加密操作。
DECRYPT_MODE 1 表示进行解密操作。

AsyKeySpecItem10+

表示密钥参数的枚举。

系统能力: SystemCapability.Security.CryptoFramework

名称 说明
DSA_P_BN 101 DSA算法的素模数p。
DSA_Q_BN 102 DSA算法中密钥参数q(p-1的素因子)。
DSA_G_BN 103 DSA算法的参数g。
DSA_SK_BN 104 DSA算法的私钥sk。
DSA_PK_BN 105 DSA算法的公钥pk。
ECC_FP_P_BN 201 DSA算法中表示椭圆曲线Fp域的素数p。
ECC_A_BN 202 DSA算法中椭圆曲线的第一个系数a。
ECC_B_BN 203 DSA算法中椭圆曲线的第二个系数b。
ECC_G_X_BN 204 ECC算法中基点g的x坐标。
ECC_G_Y_BN 205 ECC算法中基点g的y坐标。
ECC_N_BN 206 ECC算法中基点g的阶n。
ECC_H_NUM 207 ECC算法中的余因子h。
ECC_SK_BN 208 ECC算法中的私钥sk。
ECC_PK_X_BN 209 ECC算法中,公钥pk(椭圆曲线上的一个点)的x坐标。
ECC_PK_Y_BN 210 ECC算法中,公钥pk(椭圆曲线上的一个点)的y坐标。
ECC_FIELD_TYPE_STR 211 ECC算法中,椭圆曲线的域类型(当前只支持Fp域)。
ECC_FIELD_SIZE_NUM 212 ECC算法中域的大小,单位为bits(注:对于Fp域,域的大小为素数p的bits长度)。
ECC_CURVE_NAME_STR 213 ECC算法中的SECG曲线名称。
RSA_N_BN 301 RSA算法中的模数n。
RSA_SK_BN 302 RSA算法中的私钥sk(即私钥指数d)。
RSA_PK_BN 303 RSA算法中的公钥pk(即公钥指数e)。

AsyKeySpecType10+

表示密钥参数类型的枚举。

系统能力: SystemCapability.Security.CryptoFramework

名称 说明
COMMON_PARAMS_SPEC 0 表示公私钥中包含的公共参数。使用此类型的参数可以调用generateKeyPair随机生成密钥对。
PRIVATE_KEY_SPEC 1 表示私钥中包含的参数。使用此类型的参数可以调用generatePriKey生成指定的私钥。
PUBLIC_KEY_SPEC 2 表示公钥中包含的参数。使用此类型的参数可以调用generatePubKey生成指定的公钥。
KEY_PAIR_SPEC 3 表示公私钥中包含的全量参数。使用此类型的参数可以调用generateKeyPair生成指定的密钥对。

CipherSpecItem10+

表示加解密参数的枚举,这些加解密参数支持通过setCipherSpec接口设置/通过getCipherSpec接口获取。

当前只支持RSA算法,详细规格请参考框架概述加解密规格

系统能力: SystemCapability.Security.CryptoFramework

名称 说明
OAEP_MD_NAME_STR 100 表示RSA算法中,使用PKCS1_OAEP模式时,消息摘要功能的算法名。
OAEP_MGF_NAME_STR 101 表示RSA算法中,使用PKCS1_OAEP模式时,掩码生成算法(目前仅支持MGF1)。
OAEP_MGF1_MD_STR 102 表示RSA算法中,使用PKCS1_OAEP模式时,MGF1掩码生成功能的消息摘要算法。
OAEP_MGF1_PSRC_UINT8ARR 103 表示RSA算法中,使用PKCS1_OAEP模式时,pSource的字节流。

SignSpecItem10+

表示签名验签参数的枚举,这些签名验签参数支持通过setSignSpecsetVerifySpec接口设置/通过getSignSpecgetVerifySpec接口获取。

当前只支持RSA算法,详细规格请参考框架概述加解密规格

系统能力: SystemCapability.Security.CryptoFramework

名称 说明
PSS_MD_NAME_STR 100 表示RSA算法中,使用PSS模式时,消息摘要功能的算法名。
PSS_MGF_NAME_STR 101 表示RSA算法中,使用PSS模式时,掩码生成算法(目前仅支持MGF1)。
PSS_MGF1_MD_STR 102 表示RSA算法中,使用PSS模式时,MGF1掩码生成功能的消息摘要参数。
PSS_SALT_LEN_NUM 103 表示RSA算法中,使用PSS模式时,盐值的长度,长度以字节为单位。
PSS_TRAILER_FIELD_NUM 104 表示RSA算法中,使用PSS模式时,用于编码操作的整数,值为1。

AsyKeySpec10+

指定非对称密钥参数的基本接口,用于创建密钥生成器。在指定非对称密钥参数时需要构造其子类对象,并将子类对象传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。构造子类对象时,所有bigint类型的密钥参数均采用大端写法,并使用正数。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 指定非对称密钥的算法名称,比如"RSA"、"DSA"、"ECC"。
specType AsyKeySpecType 指定密钥参数类型,用于区分公/私钥参数。

DSACommonParamsSpec10+

密钥参数AsyKeySpec的子类,用于指定DSA算法中公私钥包含的公共参数,随机生成公/私钥。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
p bigint 指定DSA算法的素模数p。
q bigint 指定DSA算法中密钥参数q(p-1的素因子)。
g bigint 指定DSA算法的参数g。

DSAPubKeySpec10+

密钥参数AsyKeySpec的子类,用于指定DSA算法中公钥包含的参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params DSACommonParamsSpec 指定DSA算法中公私钥都包含的公共参数。
pk bigint 指定DSA算法的公钥。

DSAKeyPairSpec10+

密钥参数AsyKeySpec的子类,用于指定DSA算法中公私钥包含的全量参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params DSACommonParamsSpec 指定DSA算法中公私钥都包含的公共参数。
sk bigint 指定DSA算法的私钥sk。
pk bigint 指定DSA算法的公钥pk。

ECField10+

指定椭圆曲线的域。当前只支持Fp域。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
fieldType string 指定椭圆曲线域的类型,当前只支持"Fp"。

ECFieldFp10+

指定椭圆曲线素数域。是ECField的子类。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
p bigint 指定素数p。

Point10+

指定椭圆曲线上的一个点。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
x bigint 指定椭圆曲线上,点的x坐标。
y bigint 指定椭圆曲线上,点的y坐标。

ECCCommonParamsSpec10+

密钥参数AsyKeySpec的子类,用于指定ECC算法中公私钥包含的公共参数,随机生成公/私钥。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
field ECField 指定椭圆曲线的域(当前只支持Fp域)。
a bigint 指定椭圆曲线的第一个系数a。
b bigint 指定椭圆曲线的第二个系数b。
g Point 指定基点g。
n bigint 指定基点g的阶数n。
h number 指定余因子h。

ECCPriKeySpec10+

密钥参数AsyKeySpec的子类,用于指定ECC算法中私钥包含的参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params ECCCommonParamsSpec 指定ECC算法中公私钥都包含的公共参数。
sk bigint 指定ECC算法的私钥sk。

ECCPubKeySpec10+

密钥参数AsyKeySpec的子类,用于指定ECC算法中公钥包含的参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params ECCCommonParamsSpec 指定ECC算法中公私钥都包含的公共参数。
pk Point 指定ECC算法的公钥pk。

ECCKeyPairSpec10+

密钥参数AsyKeySpec的子类,用于指定ECC算法中公私钥包含的全量参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params ECCCommonParamsSpec 指定ECC算法中公私钥都包含的公共参数。
sk bigint 指定ECC算法的私钥sk。
pk Point 指定ECC算法的公钥pk。

RSACommonParamsSpec10+

密钥参数AsyKeySpec的子类,用于指定RSA算法中公私钥包含的公共参数,随机生成公/私钥。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
n bigint 指定模数n。

RSAPubKeySpec10+

密钥参数AsyKeySpec的子类,用于指定RSA算法中公钥包含的参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params RSACommonParamsSpec 指定RSA算法中公私钥都包含的公共参数。
pk bigint 指定RSA算法的公钥pk。

RSAKeyPairSpec10+

密钥参数AsyKeySpec的子类,用于指定RSA算法中公私钥包含的全量参数。

在使用密钥参数生成密钥时,将其传入createAsyKeyGeneratorBySpec()方法创建密钥生成器。

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
params RSACommonParamsSpec 指定RSA算法中公私钥都包含的公共参数。
sk bigint 指定RSA算法的私钥sk。
pk bigint 指定RSA算法的公钥pk。

Key

密钥(父类),在运行密码算法(如加解密)时需要提前生成其子类对象,并传入Cipher实例的init()方法。

密钥可以通过密钥生成器来生成。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
format string 密钥的格式。
algName string 密钥对应的算法名(含长度)。

getEncoded

getEncoded(): DataBlob

同步方法,获取密钥数据的字节流。密钥可以为对称密钥,公钥或者私钥。其中,公钥格式满足ASN.1语法、X.509规范、DER编码格式;私钥格式满足ASN.1语法,PKCS#8规范、DER编码方式。

说明:

RSA算法使用密钥参数生成私钥时,私钥对象不支持getEncoded。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
DataBlob 用于查看密钥的具体内容。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

let key: cryptoFramework.SymKey;    // The key is generated by a key generator. The generation process is omitted here.
let encodedKey = key.getEncoded();
console.info("key blob:" + encodedKey.data);

SymKey

对称密钥,是Key的子类,在对称加解密时需要将其对象传入Cipher实例的init()方法使用。

对称密钥可以通过对称密钥生成器SymKeyGenerator来生成。

clearMem

clearMem(): void

同步方法,将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时,调用本函数,避免内存中密钥数据存留过久。

系统能力: SystemCapability.Security.CryptoFramework

示例:

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

公钥,是Key的子类,在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。

公钥可以通过非对称密钥生成器AsyKeyGeneratorAsyKeyGeneratorBySpec来生成。

getAsyKeySpec10+

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

同步方法,获取密钥参数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
item AsyKeySpecItem 指定的密钥参数。

返回值:

类型 说明
bigint|string|number 用于查看密钥参数的具体内容。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

私钥,是Key的子类,在非对称加解密、签名、密钥协商时需要将其作为输入使用。

私钥可以通过非对称密钥生成器AsyKeyGeneratorAsyKeyGeneratorBySpec来生成。

clearMem

clearMem(): void

同步方法,将系统底层内存中的的密钥内容清零。

系统能力: SystemCapability.Security.CryptoFramework

示例:

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. 

getAsyKeySpec10+

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

同步方法,获取密钥参数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
item AsyKeySpecItem 指定的密钥参数类型。

返回值:

类型 说明
bigint|string|number 用于查看密钥参数的具体内容。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

非对称密钥对,包含:公钥与私钥。

可以通过非对称密钥生成器AsyKeyGeneratorAsyKeyGeneratorBySpec来生成。

说明:

KeyPair对象中的pubKey对象和priKey对象,作为KeyPair对象中的一个参数存在,当离开KeyPair对象作用域时,其内部对象可能被析构。

业务方使用时应持有KeyPair对象的引用,而非内部pubKey或priKey对象的引用。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
priKey PriKey 私钥。
pubKey PubKey 公钥。

cryptoFramework.createSymKeyGenerator

createSymKeyGenerator(algName: string): SymKeyGenerator

通过指定算法名称的字符串,获取相应的对称密钥生成器实例。

支持的规格详见框架概述“密钥生成规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 待生成对称密钥生成器的算法名称。
具体取值详见框架概述“密钥生成规格”一节中的“字符串参数”。

返回值:

类型 说明
SymKeyGenerator 返回对称密钥生成器的对象。

以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.

示例:

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

SymKeyGenerator

对称密钥生成器。

在使用该类的方法前,需要先使用createSymKeyGenerator方法构建一个symKeyGenerator实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 对称密钥生成器指定的算法名称。

generateSymKey

generateSymKey(callback: AsyncCallback<SymKey>): void

异步获取对称密钥生成器随机生成的密钥,通过注册回调函数获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。

目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
callback AsyncCallback<SymKey> 回调函数。当生成对称密钥成功,err为undefined,data为获取到的SymKey;否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.

示例:

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

let symAlgName = '3DES192';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
symKeyGenerator.generateSymKey((err, symKey) => {
  if (err) {
    console.error(`Generate symKey failed, ${err.code}, ${err.message}`);
  } else {
    console.info(`Generate symKey success, algName: ${symKey.algName}`);
  }
})

generateSymKey

generateSymKey(): Promise<SymKey>

异步获取该对称密钥生成器随机生成的密钥,通过Promise获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。

目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<SymKey> Promise对象,返回对称密钥SymKey。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.

示例:

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

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

convertKey

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

异步根据指定数据生成对称密钥,通过注册回调函数获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
key DataBlob 指定的对称密钥材料。
callback AsyncCallback<SymKey> 回调函数。当生成对称密钥成功,err为undefined,data为获取到的SymKey;否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.

示例:

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 };
}

let symAlgName = '3DES192';
let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName);
let keyMaterialBlob = genKeyMaterialBlob();
symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => {
  if (err) {
    console.error(`Convert symKey failed, ${err.code}, ${err.message}`);
  } else {
    console.info(`Convert symKey success, algName: ${symKey.algName}`);
  }
})

convertKey

convertKey(key: DataBlob): Promise<SymKey>

异步根据指定数据生成对称密钥,通过Promise获取结果。

必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
key DataBlob 指定的密钥材料数据。

返回值:

类型 说明
Promise<SymKey> Promise对象,返回对称密钥SymKey。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.

示例:

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 };
}

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

cryptoFramework.createAsyKeyGenerator

createAsyKeyGenerator(algName: string): AsyKeyGenerator

通过指定算法名称的字符串,获取相应的非对称密钥生成器实例。

支持的规格详见框架概述“密钥生成规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 待生成对称密钥生成器的算法名称。

返回值:

类型 说明
AsyKeyGenerator 返回非对称密钥生成器的对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.

示例:

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

AsyKeyGenerator

非对称密钥生成器。在使用该类的方法前,需要先使用createAsyKeyGenerator()方法构建一个AsyKeyGenerator实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 非对称密钥生成器指定的算法名称。

generateKeyPair

generateKeyPair(callback: AsyncCallback<KeyPair>): void

异步获取非对称密钥生成器随机生成的密钥,通过注册回调函数获取结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
callback AsyncCallback<KeyPair> 回调函数,用于获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

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

generateKeyPair

generateKeyPair(): Promise<KeyPair>

异步获取该非对称密钥生成器随机生成的密钥,通过Promise获取结果。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<KeyPair> 使用Promise的方式获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

异步获取指定数据生成非对称密钥,通过注册回调函数获取结果。详情请看下方密钥转换说明

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
pubKey DataBlob | null10+ 指定的公钥材料。如果公钥不需要转换,可直接传入null。API 10之前只支持DataBlob, API 10之后增加支持null。
priKey DataBlob | null10+ 指定的私钥材料。如果私钥不需要转换,可直接传入null。API 10之前只支持DataBlob, API 10之后增加支持null。
callback AsyncCallback<KeyPair> 回调函数,用于获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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}; // Data of the public key.
let priKeyBlob: cryptoFramework.DataBlob = {data: priKeyArray}; // 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>

异步获取指定数据生成非对称密钥,通过Promise获取结果。详情请看下方密钥转换说明

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
pubKey DataBlob | null10+ 指定的公钥材料。如果公钥不需要转换,可直接传入null。API 10之前只支持DataBlob, API 10之后增加支持null。
priKey DataBlob | null10+ 指定的私钥材料。如果私钥不需要转换,可直接传入null。API 10之前只支持DataBlob, API 10之后增加支持null。

返回值:

类型 说明
Promise<KeyPair> 使用Promise的方式获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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}; // Data of the public key.
let priKeyBlob: cryptoFramework.DataBlob = {data: priKeyArray}; // 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.");
});

密钥转换说明

  1. 非对称密钥(RSA、ECC、DSA)的公钥和私钥调用getEncoded()方法后,分别返回X.509格式和PKCS#8格式的二进制数据,此数据可用于跨应用传输或持久化存储。
  2. 当调用convertKey方法将外来二进制数据转换为算法库非对称密钥对象时,公钥应满足ASN.1语法、X.509规范、DER编码格式,私钥应满足ASN.1语法、PKCS#8规范、DER编码格式。
  3. convertKey方法中,公钥和密钥二进制数据非必选项,可单独传入公钥或私钥的数据,生成对应只包含公钥或私钥的KeyPair对象。

cryptoFramework.createAsyKeyGeneratorBySpec10+

createAsyKeyGeneratorBySpec(asyKeySpec: AsyKeySpec): AsyKeyGeneratorBySpec

通过指定密钥参数,获取相应的非对称密钥生成器实例。

支持的规格详见框架概述“密钥生成规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
asyKeySpec AsyKeySpec 密钥参数。非对称密钥生成器根据指定的这些参数生成公/私钥。

返回值:

类型 说明
AsyKeyGeneratorBySpec 返回非对称密钥生成器实例。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.

示例:

// Set the common parameters contained in both 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 contained in the DSA1024 public and private keys.
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);

AsyKeyGeneratorBySpec10+

非对称密钥生成器。在使用该类的方法前,需要先使用createAsyKeyGeneratorBySpec()方法构建一个AsyKeyGeneratorBySpec实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 非对称密钥生成器的算法名。

generateKeyPair

generateKeyPair(callback: AsyncCallback<KeyPair>): void

异步获取非对称密钥生成器生成的密钥,通过注册回调函数获取结果。

当使用COMMON_PARAMS_SPEC类型的密钥参数来创建密钥生成器时,可以得到随机生成的密钥对;当使用KEY_PAIR_SPEC类型的密钥参数来创建密钥生成器时,可以得到各项数据与密钥参数一致的密钥对。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
callback AsyncCallback<KeyPair> 回调函数,用于获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // dsa as example, asyKeyPairSpec specifies full parameters contained in 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>

异步获取该非对称密钥生成器生成的密钥,通过Promise获取结果。

当使用COMMON_PARAMS_SPEC类型的密钥参数来创建密钥生成器时,可以得到随机生成的密钥对;当使用KEY_PAIR_SPEC类型的密钥参数来创建密钥生成器时,可以得到各项数据与密钥参数一致的密钥对。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<KeyPair> 使用Promise的方式获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // dsa as example, asyKeyPairSpec specifies full parameters contained in 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

异步获取非对称密钥生成器生成的密钥,通过注册回调函数获取结果。

当使用PRIVATE_KEY_SPEC类型的密钥参数来创建密钥生成器时,可以得到指定的私钥;当使用KEY_PAIR_SPEC类型的密钥参数来创建密钥生成器时,可以从生成的密钥对中获取指定的私钥。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
callback AsyncCallback<PriKey> 回调函数,用于获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // dsa as example, asyKeyPairSpec specifies full parameters contained in the private and public keys.
let asyKeyGeneratorBySpec = cryptoFramework.createAsyKeyGeneratorBySpec(asyKeyPairSpec);
asyKeyGeneratorBySpec.generatePriKey((err, prikey) => {
  if (err) {
    console.error("generatePriKey: error.");
    return;
  }
  console.info("generatePriKey: success.");
})

generatePriKey

generatePriKey(): Promise<PriKey>

异步获取该非对称密钥生成器生成的密钥,通过Promise获取结果。

当使用PRIVATE_KEY_SPEC类型的密钥参数来创建密钥生成器时,可以得到指定的私钥;当使用KEY_PAIR_SPEC类型的密钥参数来创建密钥生成器时,可以从生成的密钥对中获取指定的私钥。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<PriKey> 使用Promise的方式获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // dsa as example, asyKeyPairSpec specifies full parameters contained in the private and public keys.
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

异步获取非对称密钥生成器生成的密钥,通过注册回调函数获取结果。

当使用PUBLIC_KEY_SPEC类型的密钥参数来创建密钥生成器时,可以得到指定的公钥;当使用KEY_PAIR_SPEC类型的密钥参数来创建密钥生成器时,可以从生成的密钥对中获取指定的公钥。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
callback AsyncCallback<PubKey> 回调函数,用于获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // dsa as example, asyKeyPairSpec specifies full parameters contained in 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>

异步获取该非对称密钥生成器生成的密钥,通过Promise获取结果。

当使用PUBLIC_KEY_SPEC类型的密钥参数来创建密钥生成器时,可以得到指定的公钥;当使用KEY_PAIR_SPEC类型的密钥参数来创建密钥生成器时,可以从生成的密钥对中获取指定的公钥。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<PubKey> 使用Promise的方式获取非对称密钥。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let asyKeyPairSpec: cryptoFramework.DSAKeyPairSpec; // dsa as example, asyKeyPairSpec specifies full parameters contained in 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.");
});

cryptoFramework.createCipher

createCipher(transformation: string): Cipher

通过指定算法名称,获取相应的Cipher实例。

支持的规格详见框架概述“加解密规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
transformation string 待生成Cipher的算法名称(含密钥长度)、加密模式以及填充方法的组合。
具体取值详见框架概述“加解密规格”一节中的“字符串参数”。

说明:

  1. 目前对称加解密中,PKCS5和PKCS7的实现相同,其padding长度和分组长度保持一致(即PKCS5和PKCS7在3DES中均按照8字节填充,在AES中均按照16字节填充),另有NoPadding表示不填充。
    开发者需要自行了解密码学不同分组模式的差异,以便选择合适的参数规格。例如选择ECB和CBC模式时,建议启用填充,否则必须确保明文长度是分组大小的整数倍;选择其他模式时,可以不启用填充,此时密文长度和明文长度一致(即可能不是分组大小的整数倍)。
  2. 使用RSA、SM2进行非对称加解密时,必须创建两个Cipher对象分别进行加密和解密操作,而不能对同一个Cipher对象进行加解密。对称加解密没有此要求(即只要算法规格一样,可以对同一个Cipher对象进行加解密操作)。

返回值:

类型 说明
Cipher 返回加解密生成器的对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.

示例:

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

提供加解密的算法操作功能,按序调用本类中的init()update()doFinal()方法,可以实现对称加密/对称解密/非对称加密/非对称解密。

完整的加解密流程示例可参考开发指导中的“使用加解密操作”一节。

一次完整的加/解密流程在对称加密和非对称加密中略有不同:

  • 对称加解密:init为必选,update为可选(且允许多次update加/解密大数据),doFinal为必选;doFinal结束后可以重新init开始新一轮加/解密流程。
  • RSA、SM2非对称加解密:init为必选,不支持update操作,doFinal为必选(允许连续多次doFinal加/解密大数据);RSA不支持重复init,切换加解密模式或填充方式时,需要重新创建Cipher对象。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 加解密生成器指定的算法名称。

init

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

初始化加解密的cipher对象,通过注册回调函数获取结果。

必须在使用createCipher创建Cipher实例后,才能使用本函数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
opMode CryptoMode 加密或者解密模式。
key Key 指定加密或解密的密钥。
params ParamsSpec | null10+ 指定加密或解密的参数,对于ECB等没有参数的算法模式,可以传入null。API 10之前只支持ParamsSpec, API 10之后增加支持null。
callback AsyncCallback<void> 回调函数。当加解密初始化成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

示例:

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

let symKey: cryptoFramework.SymKey;     // The process of generating the symmetric key is omitted here.
let cipher: cryptoFramework.Cipher;        // The process of creating a Cipher instance is omitted here.

cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null, (err, ) => {
  if (err) {
    console.error(`Failed to init cipher, ${err.code}, ${err.message}`);
  } else {
    console.info(`Init cipher success`);
    // Perform subsequent operations such as update.
  }
})

init

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

初始化加解密的cipher对象,通过Promise获取结果。

必须在使用createCipher创建Cipher实例后,才能使用本函数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
opMode CryptoMode 加密或者解密模式。
key Key 指定加密或解密的密钥。
params ParamsSpec | null10+ 指定加密或解密的参数,对于ECB等没有参数的算法模式,可以传入null。API 10之前只支持ParamsSpec, API 10之后增加支持null。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

示例:

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

let symKey: cryptoFramework.SymKey;     // The process of generating the symmetric key is omitted here.
let cipher: cryptoFramework.Cipher;        // The process of creating a Cipher instance is omitted here.
cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null)
  .then(() => {
    console.info(`Init cipher success`);
    // Perform subsequent operations such as update.
  }, (error: BusinessError) => {
    console.error(`Failed to init cipher, ${error.code}, ${error.message}`);
  })

update

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

分段更新加密或者解密数据操作,通过注册回调函数获取加/解密数据。

必须在对Cipher实例使用init()初始化后,才能使用本函数。

说明:

  1. 在进行对称加解密操作的时候,如果开发者对各个分组模式不够熟悉,建议对每次update和doFinal的结果都判断是否为null,并在结果不为null时取出其中的数据进行拼接,形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和doFinal结果产生影响。
    (例如对于ECB和CBC模式,不论update传入的数据是否为分组长度的整数倍,都会以分组作为基本单位进行加/解密,并输出本次update新产生的加/解密分组结果。
    可以理解为,update只要凑满一个新的分组就会有输出,如果没有凑满则此次update输出为null,把当前还没被加/解密的数据留着,等下一次update/doFinal传入数据的时候,拼接起来继续凑分组。
    最后doFinal的时候,会把剩下的还没加/解密的数据,根据createCipher时设置的padding模式进行填充,补齐到分组的整数倍长度,再输出剩余加解密结果。
    而对于可以将分组密码转化为流模式实现的模式,还可能出现密文长度和明文长度相同的情况等。)
  2. 根据数据量,可以不调用update(即init完成后直接调用doFinal)或多次调用update。
    算法库目前没有对update(单次或累计)的数据量设置大小限制,建议对于大数据量的对称加解密,采用多次update的方式传入数据。
    AES使用多次update操作的示例代码详见开发指导“使用加解密操作”。
  3. RSA、SM2非对称加解密不支持update操作。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob 加密或者解密的数据。data不能为null,也不允许传入{data: Uint8Array(空) }。
callback AsyncCallback<DataBlob> 回调函数。当更新加/解密数据成功,err为undefined,data为此次更新的加/解密结果DataBlob;否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

示例:

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

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

let cipher: cryptoFramework.Cipher;        // The process of creating a Cipher instance is omitted here.
// The init() process is omitted here.
let plainText: cryptoFramework.DataBlob = {data: stringToUint8Array('this is test!')};
cipher.update(plainText, (err, output) => {       // Example of the encryption process.
  if (err) {
    console.error(`Failed to update cipher`);
  } else {
    console.info(`Update cipher success`);
    if (output != null) {
      // Concatenate output.data to the ciphertext.
    }
    // Perform subsequent operations such as doFinal().
  }
})

update

update(data: DataBlob): Promise<DataBlob>

分段更新加密或者解密数据操作,通过Promise获取加/解密数据。

必须在对Cipher实例使用init()初始化后,才能使用本函数。

说明:

  1. 在进行对称加解密操作的时候,如果开发者对各个分组模式不够熟悉,建议对每次update和doFinal的结果都判断是否为null,并在结果不为null时取出其中的数据进行拼接,形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和doFinal结果产生影响。
    (例如对于ECB和CBC模式,不论update传入的数据是否为分组长度的整数倍,都会以分组作为基本单位进行加/解密,并输出本次update新产生的加/解密分组结果。
    可以理解为,update只要凑满一个新的分组就会有输出,如果没有凑满则此次update输出为null,把当前还没被加/解密的数据留着,等下一次update/doFinal传入数据的时候,拼接起来继续凑分组。
    最后doFinal的时候,会把剩下的还没加/解密的数据,根据createCipher时设置的padding模式进行填充,补齐到分组的整数倍长度,再输出剩余加解密结果。
    而对于可以将分组密码转化为流模式实现的模式,还可能出现密文长度和明文长度相同的情况等。)
  2. 根据数据量,可以不调用update(即init完成后直接调用doFinal)或多次调用update。
    算法库目前没有对update(单次或累计)的数据量设置大小限制,建议对于大数据量的对称加解密,可以采用多次update的方式传入数据。
    AES使用多次update操作的示例代码详见开发指导“使用加解密操作”。
  3. RSA、SM2非对称加解密不支持update操作。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob 加密或者解密的数据。data不能为null,也不允许传入{data: Uint8Array(空) }。

返回值:

类型 说明
Promise<DataBlob> Promise对象,返回此次更新的加/解密结果DataBlob。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

示例:

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

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

let cipher: cryptoFramework.Cipher;        // The process of creating a Cipher instance is omitted here.
// The init() process is omitted here.
let plainText: cryptoFramework.DataBlob = {data: stringToUint8Array('this is test!')};
cipher.update(plainText)
  .then((output) => {
    console.info(`Update cipher success.`);
    if (output != null) {
      // Concatenate output.data to the ciphertext.
    }
    // Perform subsequent operations such as doFinal().
  }, (error: BusinessError) => {
    console.info(`Update cipher failed.`);
  })

doFinal

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

(1)在对称加解密中,doFinal加/解密(分组模式产生的)剩余数据和本次传入的数据,最后结束加密或者解密数据操作,通过注册回调函数获取加密或者解密数据。
如果数据量较小,可以在doFinal中一次性传入数据,而不使用update;如果在本次加解密流程中,已经使用update传入过数据,可以在doFinal的data参数处传入null。
根据对称加解密的模式不同,doFinal的输出有如下区别:

  • 对于GCM和CCM模式的对称加密:一次加密流程中,如果将每一次update和doFinal的结果拼接起来,会得到“密文+authTag”,即末尾的16字节(GCM模式)或12字节(CCM模式)是authTag,而其余部分均为密文。(也就是说,如果doFinal的data参数传入null,则doFinal的结果就是authTag)
    authTag需要填入解密时的GcmParamsSpecCcmParamsSpec;密文则作为解密时的入参data。
  • 对于其他模式的对称加解密、GCM和CCM模式的对称解密:一次加/解密流程中,每一次update和doFinal的结果拼接起来,得到完整的明文/密文。

(2)在RSA、SM2非对称加解密中,doFinal加/解密本次传入的数据,通过注册回调函数获取加密或者解密数据。如果数据量较大,可以多次调用doFinal,拼接结果得到完整的明文/密文。

说明:

  1. 对称加解密中,调用doFinal标志着一次加解密流程已经完成,即Cipher实例的状态被清除,因此当后续开启新一轮加解密流程时,需要重新调用init()并传入完整的参数列表进行初始化
    (比如即使是对同一个Cipher实例,采用同样的对称密钥,进行加密然后解密,则解密中调用init的时候仍需填写params参数,而不能直接省略为null)。
  2. 如果遇到解密失败,需检查加解密数据和init时的参数是否匹配,包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。
  3. doFinal的结果可能为null,因此使用.data字段访问doFinal结果的具体数据前,请记得先判断结果是否为null,避免产生异常。
  4. RSA、SM2非对称加解密时多次doFinal操作的示例代码详见开发指导“使用加解密操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob | null10+ 加密或者解密的数据。在对称加解密中允许为null,但不允许传入{data: Uint8Array(空) }。API 10之前只支持DataBlob, API 10之后增加支持null。
callback AsyncCallback<DataBlob> 回调函数。当最终加/解密数据成功,err为undefined,data为剩余数据的加/解密结果DataBlob;否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

示例:

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

let cipher: cryptoFramework.Cipher;        // The process of creating a Cipher instance is omitted here.
let data: cryptoFramework.DataBlob;           // The process of preparing the data to encrypt or decrypt is omitted here.
// The init() and update() processes are omitted here.
cipher.doFinal(data, (err, output) => {
  if (err) {
    console.error(`Failed to finalize cipher, ${err.code}, ${err.message}`);
  } else {
    console.info(`Finalize cipher success`);
    if (output != null) {
      // Concatenate output.data to obtain the complete plaintext/ciphertext (and authTag).
    }
  }
})

doFinal

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

(1)在对称加解密中,doFinal加/解密(分组模式产生的)剩余数据和本次传入的数据,最后结束加密或者解密数据操作,通过Promise获取加密或者解密数据。
如果数据量较小,可以在doFinal中一次性传入数据,而不使用update;如果在本次加解密流程中,已经使用update传入过数据,可以在doFinal的data参数处传入null。
根据对称加解密的模式不同,doFinal的输出有如下区别:

  • 对于GCM和CCM模式的对称加密:一次加密流程中,如果将每一次update和doFinal的结果拼接起来,会得到“密文+authTag”,即末尾的16字节(GCM模式)或12字节(CCM模式)是authTag,而其余部分均为密文。(也就是说,如果doFinal的data参数传入null,则doFinal的结果就是authTag)
    authTag需要填入解密时的GcmParamsSpecCcmParamsSpec;密文则作为解密时的入参data。
  • 对于其他模式的对称加解密、GCM和CCM模式的对称解密:一次加/解密流程中,每一次update和doFinal的结果拼接起来,得到完整的明文/密文。

(2)在RSA、SM2非对称加解密中,doFinal加/解密本次传入的数据,通过Promise获取加密或者解密数据。如果数据量较大,可以多次调用doFinal,拼接结果得到完整的明文/密文。

说明:

  1. 对称加解密中,调用doFinal标志着一次加解密流程已经完成,即Cipher实例的状态被清除,因此当后续开启新一轮加解密流程时,需要重新调用init()并传入完整的参数列表进行初始化
    (比如即使是对同一个Cipher实例,采用同样的对称密钥,进行加密然后解密,则解密中调用init的时候仍需填写params参数,而不能直接省略为null)。
  2. 如果遇到解密失败,需检查加解密数据和init时的参数是否匹配,包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。
  3. doFinal的结果可能为null,因此使用.data字段访问doFinal结果的具体数据前,请记得先判断结果是否为null,避免产生异常。
  4. RSA、SM2非对称加解密时多次doFinal操作的示例代码详见开发指导“使用加解密操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob | null10+ 加密或者解密的数据。data参数允许为null,但不允许传入{data: Uint8Array(空) }。API 10之前只支持DataBlob, API 10之后增加支持null。

返回值:

类型 说明
Promise<DataBlob> Promise对象,返回剩余数据的加/解密结果DataBlob。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

示例:

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

let cipher: cryptoFramework.Cipher;        // The process of creating a Cipher instance is omitted here.
let data: cryptoFramework.DataBlob;           // The process of preparing the data to encrypt or decrypt is omitted here.
// The init() and update() processes are omitted here.
cipher.doFinal(data)
  .then(output => {
    console.info(`Finalize cipher success`);
    if (output != null) {
      // Concatenate output.data to obtain the complete plaintext/ciphertext (and authTag).
    }
  }, (error: BusinessError) => {
    console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`);
  })

使用RSA加密的callback完整示例:

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

let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
rsaGenerator.generateKeyPair((err, keyPair) => {
  let pubKey = keyPair.pubKey;
  cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, (err, data) => {
    let plainText = "this is cipher text";
    let input: cryptoFramework.DataBlob = {data: stringToUint8Array(plainText) };
    cipher.doFinal(input, (err, data) => {
      AlertDialog.show({ message: "EncryptOutPut is " + data.data} );
    });
  });
});

使用RSA加密的Promise完整示例:

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

let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
let keyGenPromise = rsaGenerator.generateKeyPair();
keyGenPromise.then((rsaKeyPair: cryptoFramework.KeyPair): Promise<void> => {
  let pubKey = rsaKeyPair.pubKey;
  return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // Pass in the private key and DECRYPT_MODE to initialize the decryption mode.
}).then(() => {
  let plainText = "this is cipher text";
  let input: cryptoFramework.DataBlob = { data: stringToUint8Array(plainText) };
  return cipher.doFinal(input);
}).then(dataBlob => {
  console.info("EncryptOutPut is " + dataBlob.data);
});

说明:

更多加解密流程的完整示例可参考开发指导中的“使用加解密操作”一节。

setCipherSpec10+

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

设置加解密参数。常用的加解密参数可以直接通过createCipher 来指定,剩余参数可以通过本接口指定。当前只支持RSA算法。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
itemType CipherSpecItem 用于指定需要设置的加解密参数。
itemValue Uint8Array 用于指定加解密参数的具体值。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

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);

getCipherSpec10+

getCipherSpec(itemType: CipherSpecItem): string | Uint8Array

获取加解密参数。当前只支持RSA算法。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
itemType CipherSpecItem 用于指定需要获取的加解密参数。

返回值:

类型 说明
string|Uint8Array 获取的加解密参数的具体值。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

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

Sign实例生成。

支持的规格详见框架概述“签名验签规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 指定签名算法:RSA,ECC,DSA或SM210+。使用RSA PKCS1模式时需要设置摘要,使用RSA PSS模式时需要设置摘要和掩码摘要。

返回值

类型 说明
Sign 返回由输入算法指定生成的Sign对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.

示例:

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

Sign类,使用Sign方法之前需要创建该类的实例进行操作,通过createSign(algName: string): Sign方法构造此实例。按序调用本类中的init、update、sign方法完成签名操作。签名操作的示例代码详见开发指导“使用签名验签操作”。

Sign类不支持重复初始化,当业务方需要使用新密钥签名时,需要重新创建新Sign对象并调用init初始化。

业务方使用时,在createSign时确定签名的模式,调用init接口设置密钥。

当待签名数据较短时,可在init初始化后,(无需update)直接调用sign接口传入原文数据进行签名。

当待签名数据较长时,可通过update接口分段传入切分后的原文数据,最后调用sign接口对整体原文数据进行签名。

当使用update分段传入原文时,sign接口API 10之前只支持传入DataBlob, API 10之后增加支持null。业务方可在循环中调用update接口,循环结束后调用sign进行签名。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 签名指定的算法名称。

init

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

使用私钥初始化Sign对象,通过注册回调函数获取结果。

Sign类暂不支持重复init。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
priKey PriKey 用于Sign的初始化。
callback AsyncCallback<void> 回调函数。当签名初始化成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

init

init(priKey: PriKey): Promise<void>

使用私钥初始化Sign对象,通过Promise获取结果。

Sign类暂不支持重复init。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
priKey PriKey 用于Sign的初始化。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

update

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

追加待签名数据,通过注册回调函数完成更新。

必须在对Sign实例使用init()初始化后,才能使用本函数。

说明:

根据数据量,可以不调用update(即init完成后直接调用sign)或多次调用update。
算法库目前没有对update(单次或累计)的数据量设置大小限制,建议对于大数据量的签名操作,采用多次update的方式传入数据,避免一次性申请过大内存。
签名使用多次update操作的示例代码详见开发指导“使用签名验签操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob 传入的消息。
callback AsyncCallback<void> 回调函数。当签名更新成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

update

update(data: DataBlob): Promise<void>

追加待签名数据,通过Promise方式完成更新。

必须在对Sign实例使用init()初始化后,才能使用本函数。

说明:

根据数据量,可以不调用update(即init完成后直接调用sign)或多次调用update。
算法库目前没有对update(单次或累计)的数据量设置大小限制,建议对于大数据量的签名操作,采用多次update的方式传入数据,避免一次性申请过大内存。
签名使用多次update操作的示例代码详见开发指导“使用签名验签操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob 传入的消息。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

sign

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

对数据进行签名,通过注册回调函数获取签名结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob | null10+ 传入的消息。API 10之前只支持DataBlob, API 10之后增加支持null。
callback AsyncCallback<DataBlob> 回调函数,用于获取DataBlob数据。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

sign

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

对数据进行签名,通过Promise方式返回签名结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob | null10+ 传入的消息。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

callback示例:

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

let globalKeyPair: cryptoFramework.KeyPair;
let signMessageBlob: cryptoFramework.DataBlob;
let plan1 = "This is Sign test plan1"; // The first segment of the data.
let plan2 = "This is Sign test plan2"; // The second segment of the data.
let input1: cryptoFramework.DataBlob = { data: stringToUint8Array(plan1) };
let input2: cryptoFramework.DataBlob = { data: stringToUint8Array(plan2) };

function signMessageCallback() {
  let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
  let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
  rsaGenerator.generateKeyPair((err, keyPair) => {
    globalKeyPair = keyPair;
    let priKey = globalKeyPair.priKey;
    signer.init(priKey, err => {
      signer.update(input1, err => { // add first segment of data
        signer.sign(input2, (err, data) => { // add second segment of data, sign input1 and input2
          signMessageBlob = data;
          AlertDialog.show({message: "res" +  signMessageBlob.data});
        });
      });
    });
  });
}

Promise示例:

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

let globalKeyPair: cryptoFramework.KeyPair;
let signMessageBlob: cryptoFramework.DataBlob;
let plan1 = "This is Sign test plan1"; // The first segment of the data.
let plan2 = "This is Sign test plan2"; // The second segment of the data.
let input1: cryptoFramework.DataBlob = { data: stringToUint8Array(plan1) };
let input2: cryptoFramework.DataBlob = { data: stringToUint8Array(plan2) };

function signMessagePromise() {
  let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
  let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); // From API version 10, a Sign instance can be created by specifying a string parameter defining the key specifications.
  let keyGenPromise = rsaGenerator.generateKeyPair();
  keyGenPromise.then(keyPair => {
    globalKeyPair = keyPair;
    let priKey = globalKeyPair.priKey;
    return signer.init(priKey);
  }).then(() => {
    return signer.update(input1);
  }).then(() => {
    return signer.sign(input2);
  }).then(dataBlob => {
    signMessageBlob = dataBlob;
    console.info("sign output is " + signMessageBlob.data);
  });
}

setSignSpec10+

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

设置签名参数。常用的签名参数可以直接通过createSign 来指定,剩余参数可以通过本接口指定。

当前只支持RSA算法。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
itemType SignSpecItem 用于指定需要设置的签名参数。
itemValue number 用于指定签名参数的具体值。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

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);

getSignSpec10+

getSignSpec(itemType: SignSpecItem): string | number

获取签名参数。当前只支持RSA算法。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
itemType SignSpecItem 用于指定需要获取的签名参数。

返回值:

类型 说明
string|number 获取的签名参数的具体值。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

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

Verify实例生成。

支持的规格详见框架概述“签名验签规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 指定签名算法:RSA,ECC,DSA或SM210+,。使用RSA PKCS1模式时需要设置摘要,使用RSA PSS模式时需要设置摘要和掩码摘要。

返回值

类型 说明
Verify 返回由输入算法指定生成的Verify对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.

示例:

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

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

Verify

Verify类,使用Verify方法之前需要创建该类的实例进行操作,通过createVerify(algName: string): Verify方法构造此实例。按序调用本类中的init、update、verify方法完成签名操作。验签操作的示例代码详见开发指导“使用签名验签操作”。

Verify类不支持重复初始化,当业务方需要使用新密钥验签时,需要重新创建新Verify对象并调用init初始化。

业务方使用时,在createVerify时确定验签的模式,调用init接口设置密钥。

当被签名的消息较短时,可在init初始化后,(无需update)直接调用verify接口传入被签名的消息和签名(signatureData)进行验签。

当被签名的消息较长时,可通过update接口分段传入被签名的消息,最后调用verify接口对消息全文进行验签。verify接口的data入参在API 10之前只支持DataBlob, API 10之后增加支持null。业务方可在循环中调用update接口,循环结束后调用verify传入签名(signatureData)进行验签。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 验签指定的算法名称。

init

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

传入公钥初始化Verify对象,通过注册回调函数获取结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
pubKey PubKey 公钥对象,用于Verify的初始化。
callback AsyncCallback<void> 回调函数。当验签初始化成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

init

init(pubKey: PubKey): Promise<void>

传入公钥初始化Verify对象,通过Promise获取结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
pubKey PubKey 公钥对象,用于Verify的初始化。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

update

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

追加待验签数据,通过注册回调函数完成更新。

必须在对Verify实例使用init()初始化后,才能使用本函数。

说明:

根据数据量,可以不调用update(即init完成后直接调用verify)或多次调用update。
算法库目前没有对update(单次或累计)的数据量设置大小限制,建议对于大数据量的验签操作,采用多次update的方式传入数据,避免一次性申请过大内存。
验签使用多次update操作的示例代码详见开发指导“使用签名验签操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob 传入的消息。
callback AsyncCallback<void> 回调函数。当验签更新成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

update

update(data: DataBlob): Promise<void>

追加待验签数据,通过Promise方式完成更新。

必须在对Verify实例使用init()初始化后,才能使用本函数。

说明:

根据数据量,可以不调用update(即init完成后直接调用verify)或多次调用update。
算法库目前没有对update(单次或累计)的数据量设置大小限制,建议对于大数据量的验签操作,采用多次update的方式传入数据,避免一次性申请过大内存。
验签使用多次update操作的示例代码详见开发指导“使用签名验签操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob 传入的消息。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

verify

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

对数据进行验签,通过注册回调函数返回返回验签结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob | null10+ 传入的消息。API 10之前只支持DataBlob, API 10之后增加支持null。
signatureData DataBlob 签名数据。
callback AsyncCallback<boolean> 回调函数,用于获取以boolean值表示的验签结果。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

verify

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

对数据进行验签,通过Promise返回验签结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
data DataBlob | null10+ 传入的消息。API 10之前只支持DataBlob, API 10之后增加支持null。
signatureData DataBlob 签名数据。

返回值:

类型 说明
Promise<boolean> 异步返回值,代表验签是否通过。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

callback示例:

let globalKeyPair: cryptoFramework.KeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
let input1: cryptoFramework.DataBlob;
let input2: cryptoFramework.DataBlob;
let signMessageBlob: cryptoFramework.DataBlob;// Signed data, which is omitted here.
let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
verifyer.init(globalKeyPair.pubKey, (err, data) => {
  verifyer.update(input1, (err, data) => {
    verifyer.verify(input2, signMessageBlob, (err, data) => {
      console.info("verify result is " + data);
    })
  });
})

Promise示例:

let globalKeyPair: cryptoFramework.KeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
let verifyInitPromise = verifyer.init(globalKeyPair.pubKey);
let input1: cryptoFramework.DataBlob;;
let input2: cryptoFramework.DataBlob;;
let signMessageBlob: cryptoFramework.DataBlob;; // Signed data, which is omitted here.
verifyInitPromise.then((): Promise<void> => {
  return verifyer.update(input1);
}).then(() => {
  return verifyer.verify(input2, signMessageBlob);
}).then(res => {
  console.log("Verify result is " + res);
});

setVerifySpec10+

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

设置验签参数。常用的签名参数可以直接通过createVerify 来指定,剩余参数可以通过本接口指定。当前只支持RSA算法。

验签的参数应当与签名的参数保持一致。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
itemType SignSpecItem 用于指定需要设置的验签参数。
itemValue number 用于指定验签参数的具体值。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

let verifyer: cryptoFramework.Verify; //The process of generating the Verify instance is omitted here.
let setN = 20;
verifyer.setVerifySpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM, setN);

getVerifySpec10+

getVerifySpec(itemType: SignSpecItem): string | number

获取验签参数。当前只支持RSA算法。

验签的参数应当与签名的参数保持一致。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
itemType SignSpecItem 用于指定需要获取的验签参数。

返回值:

类型 说明
string|number 获取的验签参数的具体值。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.
17630001 crypto operation error.

示例:

let verifyer: cryptoFramework.Verify; //The process of generating the Verify instance is omitted here.
let saltLen = verifyer.getVerifySpec(cryptoFramework.SignSpecItem.PSS_SALT_LEN_NUM);

cryptoFramework.createKeyAgreement

createKeyAgreement(algName: string): KeyAgreement

KeyAgreement实例生成。

支持的规格详见框架概述“密钥协商规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 指定密钥协商算法:目前仅支持ECC。

返回值

类型 说明
KeyAgreement 返回由输入算法指定生成的KeyAgreement对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
801 this operation is not supported.
17620001 memory error.

示例:

let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");

KeyAgreement

KeyAgreement类,使用密钥协商方法之前需要创建该类的实例进行操作,通过createKeyAgreement(algName: string): KeyAgreement方法构造此实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 密钥协商指定的算法名称。

generateSecret

generateSecret(priKey: PriKey, pubKey: PubKey, callback: AsyncCallback<DataBlob>): void

基于传入的私钥与公钥进行密钥协商,通过注册回调函数返回共享秘密。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
priKey PriKey 设置密钥协商的私钥输入。
pubKey PubKey 设置密钥协商的公钥输入。
callback AsyncCallback<DataBlob> 异步接受共享秘密的回调。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

generateSecret

generateSecret(priKey: PriKey, pubKey: PubKey): Promise<DataBlob>

基于传入的私钥与公钥进行密钥协商,通过Promise返回共享秘密。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
priKey PriKey 设置密钥协商的私钥输入。
pubKey PubKey 设置密钥协商的公钥输入。

返回值:

类型 说明
Promise<DataBlob> 共享秘密。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17620002 runtime error.
17630001 crypto operation error.

callback示例:

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

let globalKeyPair: cryptoFramework.KeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, (err, secret) => {
  if (err) {
    console.error("keyAgreement error.");
    return;
  }
  console.info("keyAgreement output is " + secret.data);
});

Promise示例:

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

let globalKeyPair: cryptoFramework.KeyPair; // globalKeyPair is an asymmetric key object generated by the asymmetric key generator. The generation process is omitted here.
let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
let keyAgreementPromise = keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey);
keyAgreementPromise.then((secret) => {
  console.info("keyAgreement output is " + secret.data);
}).catch((error: BusinessError) => {
  console.error("keyAgreement error.");
});

cryptoFramework.createMd

createMd(algName: string): Md

生成Md实例,用于进行消息摘要的计算与操作。

支持的规格详见框架概述“MD消息摘要算法规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 指定摘要算法,支持算法请参考“MD算法支持范围”一节。

返回值

类型 说明
Md 返回由输入算法指定生成的Md对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.

示例:

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

try {
  // Set algName based on the algorithm supported.
  let md = cryptoFramework.createMd("SHA256");
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`sync error, ${e.code}, ${e.message}`);
}

Md

Md类,调用Md方法可以进行MD(Message Digest)摘要计算。调用前,需要通过createMd构造Md实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 代表指定的摘要算法名。

update

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

传入消息进行Md更新计算,通过注册回调函数更新。

说明:

Md算法多次调用update更新的代码示例详见开发指导“使用摘要操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
input DataBlob 传入的消息。
callback AsyncCallback<void> 回调函数。当摘要更新成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17630001 crypto operation error.

示例:

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

let md = cryptoFramework.createMd("SHA256");
console.info("Md algName is: " + md.algName);

let blob: cryptoFramework.DataBlob;
md.update(blob, (err,) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  }
});

update

update(input: DataBlob): Promise<void>

传入消息进行Md更新计算,通过Promise更新。

说明:

Md算法多次调用update更新的代码示例详见开发指导“使用摘要操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数名 类型 必填 说明
input DataBlob 传入的消息。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17630001 crypto operation error.

示例:

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

let md = cryptoFramework.createMd("SHA256");
console.info("Md algName is: " + md.algName);

let blob: cryptoFramework.DataBlob;
let promiseMdUpdate = md.update(blob);
promiseMdUpdate.then(() => {
  // do something
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

digest

digest(callback: AsyncCallback<DataBlob>): void

通过注册回调函数返回Md的计算结果。

系统能力: SystemCapability.Security.CryptoFramework

参数名 类型 必填 说明
callback AsyncCallback<DataBlob> 回调函数,用于获取DataBlob数据。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.
17630001 crypto operation error.

示例:

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

let md = cryptoFramework.createMd("SHA256");
console.info("Md algName is: " + md.algName);

let blob: cryptoFramework.DataBlob;
md.update(blob, (err,) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  }
  md.digest((err1, mdOutput) => {
    if (err1) {
      console.error("[Callback] err: " + err1.code);
    } else {
      console.error("[Callback]: MD result: " + mdOutput);
    }
  });
});

digest

digest(): Promise<DataBlob>

通过Promise返回Md的计算结果。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<DataBlob> Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.
17630001 crypto operation error.

示例:

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

let md = cryptoFramework.createMd("SHA256");
console.info("Md algName is: " + md.algName);

let blob: cryptoFramework.DataBlob;
let promiseMdUpdate = md.update(blob);
promiseMdUpdate.then(() => {
  let promiseMdDigest = md.digest();
  return promiseMdDigest;
}).then(mdOutput => {
  console.error("[Promise]: MD result: " + mdOutput.data);
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

getMdLength

getMdLength(): number

获取Md消息摘要长度(字节数)。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
number 返回md计算结果的字节长度。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17630001 crypto operation error.

示例:

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

let md = cryptoFramework.createMd("SHA256");
console.info("Md algName is: " + md.algName);

let blob: cryptoFramework.DataBlob;
let promiseMdUpdate = md.update(blob);
promiseMdUpdate.then(() => {
  let promiseMdDigest = md.digest();
  return promiseMdDigest;
}).then(mdOutput => {
  console.error("[Promise]: MD result: " + mdOutput.data);
  let mdLen = md.getMdLength();
  console.error("MD len: " + mdLen);
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

cryptoFramework.createMac

createMac(algName: string): Mac

生成Mac实例,用于进行消息认证码的计算与操作。

支持的规格详见框架概述“HMAC消息认证码算法规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
algName string 指定摘要算法,支持算法请参考“HMAC算法支持范围”一节。

返回值

类型 说明
Mac 返回由输入算法指定生成的Mac对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.

示例:

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

try {
  // Set algName based on the algorithm supported.
  let mac = cryptoFramework.createMac("SHA256");
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`sync error, ${e.code}, ${e.message}`);
}

Mac

Mac类,调用Mac方法可以进行MAC(Message Authentication Code)加密计算。调用前,需要通过createMac构造Mac实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName string 代表指定的摘要算法名。

init

init(key: SymKey, callback: AsyncCallback<void>): void

使用对称密钥初始化Mac计算,通过注册回调函数获取结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
key SymKey 共享对称密钥。
callback AsyncCallback<void> 回调函数。当HMAC初始化成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17630001 crypto operation error.

示例:

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

let mac = cryptoFramework.createMac("SHA256");
let keyBlob: cryptoFramework.DataBlob;
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
symKeyGenerator.convertKey(keyBlob, (err, symKey) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  }
  mac.init(symKey, (err1, ) => {
    if (err1) {
      console.error("[Callback] err: " + err1.code);
    }
  });
});

init

init(key: SymKey): Promise<void>

使用对称密钥初始化Mac计算,通过Promise获取结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
key SymKey 共享对称密钥。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17630001 crypto operation error.

示例:

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

let mac = cryptoFramework.createMac("SHA256");
console.info("Mac algName is: " + mac.algName);

let keyBlob: cryptoFramework.DataBlob;
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
let promiseConvertKey = symKeyGenerator.convertKey(keyBlob);
promiseConvertKey.then(symKey => {
  let promiseMacInit = mac.init(symKey);
  return promiseMacInit;
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

update

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

传入消息进行Mac更新计算,通过注册回调函数获取结果。

说明:

Hmac算法多次调用update更新的代码示例详见开发指导“使用消息认证码操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
input DataBlob 传入的消息。
callback AsyncCallback<void> 回调函数。当HMAC更新成功,err为undefined,否则为错误对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17630001 crypto operation error.

示例:

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

let keyBlob: cryptoFramework.DataBlob;
let mac = cryptoFramework.createMac("SHA256");
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
symKeyGenerator.convertKey(keyBlob, (err, symKey) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  }
  mac.init(symKey, (err1, ) => {
    if (err1) {
      console.error("[Callback] err: " + err1.code);
    }
    let blob: cryptoFramework.DataBlob;
    mac.update(blob, (err2, data) => {
      if (err2) {
        console.error("[Callback] err: " + err2.code);
      }
    });
  });
});

update

update(input: DataBlob): Promise<void>

传入消息进行Mac更新计算,通过Promise获取结果。

说明:

Hmac算法多次调用update更新的代码示例详见开发指导“使用消息认证码操作”。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
input DataBlob 传入的消息。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17630001 crypto operation error.

示例:

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

let mac = cryptoFramework.createMac("SHA256");
console.info("Mac algName is: " + mac.algName);

let keyBlob: cryptoFramework.DataBlob;
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
let promiseConvertKey = symKeyGenerator.convertKey(keyBlob);
promiseConvertKey.then(symKey => {
  let promiseMacInit = mac.init(symKey);
  return promiseMacInit;
}).then(() => {
  let blob: cryptoFramework.DataBlob;
  let promiseMacUpdate = mac.update(blob);
  return promiseMacUpdate;
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

doFinal

doFinal(callback: AsyncCallback<DataBlob>): void

通过注册回调函数返回Mac的计算结果。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
callback AsyncCallback<DataBlob> 回调函数,用于获取DataBlob数据。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.
17630001 crypto operation error.

示例:

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

let keyBlob: cryptoFramework.DataBlob;
let mac = cryptoFramework.createMac("SHA256");
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
symKeyGenerator.convertKey(keyBlob, (err, symKey) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  }
  mac.init(symKey, (err1, ) => {
    if (err1) {
      console.error("[Callback] err: " + err1.code);
    }
    let blob: cryptoFramework.DataBlob;
    mac.update(blob, (err2, ) => {
      if (err2) {
        console.error("[Callback] err: " + err2.code);
      }
      mac.doFinal((err3, macOutput) => {
        if (err3) {
          console.error("[Callback] err: " + err3.code);
        } else {
          console.error("[Promise]: HMAC result: " + macOutput);
        }
      });
    });
  });
});

doFinal

doFinal(): Promise<DataBlob>

通过Promise返回Mac的计算结果。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
Promise<DataBlob> Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.
17630001 crypto operation error.

示例:

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

let mac = cryptoFramework.createMac("SHA256");
console.info("Mac algName is: " + mac.algName);
let keyBlob: cryptoFramework.DataBlob;
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
let promiseConvertKey = symKeyGenerator.convertKey(keyBlob);
promiseConvertKey.then(symKey => {
  let promiseMacInit = mac.init(symKey);
  return promiseMacInit;
}).then(() => {
  let blob: cryptoFramework.DataBlob;
  let promiseMacUpdate = mac.update(blob);
  return promiseMacUpdate;
}).then(() => {
  let promiseMacDoFinal = mac.doFinal();
  return promiseMacDoFinal;
}).then(macOutput => {
  console.error("[Promise]: HMAC result: " + macOutput.data);
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

getMacLength

getMacLength(): number

获取Mac消息认证码的长度(字节数)。

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型 说明
number 返回mac计算结果的字节长度。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17630001 crypto operation error.

示例:

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

let mac = cryptoFramework.createMac("SHA256");
console.info("Mac algName is: " + mac.algName);
let keyBlob: cryptoFramework.DataBlob;
let symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
let promiseConvertKey = symKeyGenerator.convertKey(keyBlob);
promiseConvertKey.then(symKey => {
  let promiseMacInit = mac.init(symKey);
  return promiseMacInit;
}).then(() => {
  let blob: cryptoFramework.DataBlob;
  let promiseMacUpdate = mac.update(blob);
  return promiseMacUpdate;
}).then(() => {
  let promiseMacDoFinal = mac.doFinal();
  return promiseMacDoFinal;
}).then(macOutput => {
  console.error("[Promise]: HMAC result: " + macOutput.data);
  let macLen = mac.getMacLength();
  console.error("MAC len: " + macLen);
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

cryptoFramework.createRandom

createRandom(): Random

生成Random实例,用于进行随机数的计算与设置种子。

支持的规格详见框架概述“随机数算法规格”一节。

系统能力: SystemCapability.Security.CryptoFramework

返回值

类型 说明
Random 返回由输入算法指定生成的Random对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.

示例:

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

try {
  let rand = cryptoFramework.createRandom();
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`sync error, ${e.code}, ${e.message}`);
}

Random

Random类,调用Random方法可以进行随机数计算。调用前,需要通过createRandom构造Random实例。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称 类型 可读 可写 说明
algName10+ string 代表当前使用的随机数生成算法,目前只支持“CTR_DRBG"。

generateRandom

generateRandom(len: number, callback: AsyncCallback<DataBlob>): void

异步生成指定长度的随机数,通过注册回调函数返回。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
len number 表示生成随机数的长度,单位为byte,范围在[1, INT_MAX]。
callback AsyncCallback<DataBlob> 回调函数,用于获取DataBlob数据。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let rand = cryptoFramework.createRandom();
rand.generateRandom(12, (err, randData) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  } else {
    console.error("[Callback]: generate random result: " + randData.data);
  }
});

generateRandom

generateRandom(len: number): Promise<DataBlob>

异步生成指定长度的随机数,通过Promise返回。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
len number 表示生成随机数的长度,单位为byte,范围在[1, INT_MAX]。

返回值:

类型 说明
Promise<DataBlob> Promise对象。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let rand = cryptoFramework.createRandom();
let promiseGenerateRand = rand.generateRandom(12);
promiseGenerateRand.then(randData => {
  console.error("[Promise]: rand result: " + randData.data);
}).catch((error: BusinessError) => {
  console.error("[Promise]: error: " + error.message);
});

generateRandomSync10+

generateRandomSync(len: number): DataBlob

同步生成指定长度的随机数。

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名 类型 必填 说明
len number 表示生成随机数的长度,单位为byte,范围在[1, INT_MAX]。

返回值:

类型 说明
DataBlob 表示生成的随机数。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
401 invalid parameters.
17620001 memory error.
17630001 crypto operation error.

示例:

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

let rand = cryptoFramework.createRandom();
try {
  let randData = rand.generateRandomSync(12);
  if (randData != null) {
    console.info("[Sync]: rand result: " + randData.data);
  } else {
    console.error("[Sync]: get rand result fail!");
  }
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`sync error, ${e.code}, ${e.message}`);
}

setSeed

setSeed(seed: DataBlob): void

设置指定的种子。

系统能力: SystemCapability.Security.CryptoFramework

参数名 类型 必填 说明
seed DataBlob 设置的种子。

错误码: 以下错误码的详细介绍请参见crypto framework错误码

错误码ID 错误信息
17620001 memory error.

示例:

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

let rand = cryptoFramework.createRandom();
rand.generateRandom(12, (err, randData) => {
  if (err) {
    console.error("[Callback] err: " + err.code);
  } else {
    console.info("[Callback]: generate random result: " + randData.data);
    try {
      rand.setSeed(randData);
    } catch (error) {
      let e: BusinessError = error as BusinessError;
      console.error(`sync error, ${e.code}, ${e.message}`);
    }
  }
});