
HarmonyOSAPI@ohos.security.cryptoFramework 加解密算法库框架
版本:v3.1 Beta
@ohos.security.cryptoFramework (加解密算法库框架)
更新时间: 2023-02-17 09:19
为屏蔽底层硬件和算法库,向上提供统一的密码算法库加解密相关接口。
说明
本模块首批接口从API version 9开始支持。
导入模块
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数组。
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
data | Uint8Array | 是 | 是 | 数据。 |
cryptoFramework.createMac
createMac(algName : string) : Mac
生成Mac实例,用于进行消息认证码的计算与操作
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
algName | string | 是 | 指定摘要算法,支持算法范围:SHA1/SHA224/SHA256/SHA384/SHA512 |
返回值:
类型 | 说明 |
Mac | 返回由输入算法指定生成的Mac对象 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
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> | 是 | 回调函数 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
init
init(key : SymKey) : Promise<void>;
使用对称密钥初始化Mac计算
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
key | SymKey | 是 | 共享对称密钥 |
返回值:
类型 | 说明 |
Promise<void> | Promise对象 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
update
update(input : DataBlob, callback : AsyncCallback<void>) : void;
传入消息进行Mac更新计算
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
input | 是 | 传入的消息 | |
callback | AsyncCallback<void> | 是 | 回调函数 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
update
update(input : DataBlob) : Promise<void>;
传入消息进行Mac更新计算
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
input | 是 | 传入的消息 |
返回值:
类型 | 说明 |
Promise<void> | Promise对象 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
doFinal
doFinal(callback : AsyncCallback<DataBlob>) : void;
返回Mac的计算结果
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<DataBlob> | 是 | 回调函数 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
17630001 | crypto operation error. |
示例:
doFinal
doFinal() : Promise<DataBlob>
返回Mac的计算结果
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
Promise<DataBlob> | Promise对象 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
17630001 | crypto operation error. |
示例:
getMacLength
getMacLength() : number
获取Mac消息认证码的长度(字节数)
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
number | 返回mac计算结果的字节长度 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
cryptoFramework.createMd
createMd(algName : string) : Md
生成Md实例,用于进行消息摘要的计算与操作
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
algName | string | 是 | 指定摘要算法,支持算法范围:SHA1/SHA224/SHA256/SHA384/SHA512/MD5 |
返回值:
类型 | 说明 |
Md | 返回由输入算法指定生成的Md对象 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
Md
Md类,调用Md方法可以进行MD(Message Digest)摘要计算。调用前,需要通过createMd构造Md实例。
属性
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
algName | string | 是 | 否 | 代表指定的摘要算法名 |
update
update(input : DataBlob, callback : AsyncCallback<void>) : void;
传入消息进行Md更新计算
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
input | 是 | 传入的消息 | |
callback | AsyncCallback<void> | 是 | 回调函数 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
update
update(input : DataBlob) : Promise<void>;
传入消息进行Md更新计算
系统能力: SystemCapability.Security.CryptoFramework
参数名 | 类型 | 必填 | 说明 |
input | DataBlob | 是 | 传入的消息 |
返回值:
类型 | 说明 |
Promise<void> | Promise对象 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
digest
digest(callback : AsyncCallback<DataBlob>) : void
返回Md的计算结果
系统能力: SystemCapability.Security.CryptoFramework
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<DataBlob> | 是 | 回调函数 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
17630001 | crypto operation error. |
示例:
digest
digest() : Promise<DataBlob>
返回Md的计算结果
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
Promise<DataBlob> | Promise对象 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
17630001 | crypto operation error. |
示例:
getMdLength
getMdLength() : number
获取Md消息摘要长度(字节数)
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
number | 返回md计算结果的字节长度 |
错误码:
错误码ID | 错误信息 |
17630001 | crypto operation error. |
示例:
cryptoFramework.createRandom
createRandom() : Random
生成Random实例,用于进行随机数的计算与设置种子
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
Random | 返回由输入算法指定生成的Random对象 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
Random
Random类,调用Random方法可以进行随机数计算。调用前,需要通过createRandom构造Random实例。
generateRandom
generateRandom(len : number, callback: AsyncCallback<DataBlob>) : void;
生成指定长度的随机数
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
len | number | 是 | 表示生成随机数的长度 |
callback | AsyncCallback<DataBlob> | 是 | 回调函数 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
17630001 | crypto operation error. |
示例:
generateRandom
generateRandom(len : number) : Promise<DataBlob>;
生成指定长度的随机数
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
len | number | 是 | 表示生成随机数的长度 |
返回值:
类型 | 说明 |
Promise<DataBlob> | Promise对象 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
17630001 | crypto operation error. |
示例:
setSeed
setSeed(seed : DataBlob) : void;
设置指定的种子
系统能力: SystemCapability.Security.CryptoFramework
参数名 | 类型 | 必填 | 说明 |
seed | DataBlob | 是 | 设置的种子 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
ParamsSpec
加解密参数,在进行对称加解密时需要构造其子类对象,并将子类对象传入init()方法。
适用于需要iv等参数的对称加解密模式(对于无iv等参数的模式如ECB模式,无需构造,在init()中传入null即可)。
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
algoName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下: - "IvParamsSpec": 适用于CBC|CTR|OFB|CFB模式 - "GcmParamsSpec": 适用于GCM模式 - "CcmParamsSpec": 适用于CCM模式 |
说明
由于init()的params参数是ParamsSpec类型(父类),而实际需要传入具体的子类对象(如IvParamsSpec),因此在构造子类对象时应设置其父类ParamsSpec的algoName参数,使算法库在init()时知道传入的是哪种子类对象。
IvParamsSpec
加解密参数ParamsSpec的子类,用于在对称加解密时作为init()方法的参数。
适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
iv | 是 | 是 | 指明加解密参数iv。常见取值如下: - AES的CBC|CTR|OFB|CFB模式:iv长度为16字节 - 3DES的CBC|OFB|CFB模式:iv长度为8字节 |
说明
传入init()方法前需要指定其algoName属性(来源于父类ParamsSpec)。
GcmParamsSpec
加解密参数ParamsSpec的子类,用于在对称加解密时作为init()方法的参数。
适用于GCM模式。
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
iv | 是 | 是 | 指明加解密参数iv,长度为12字节 | |
aad | 是 | 是 | 指明加解密参数aad,长度为8字节 | |
authTag | 是 | 是 | 指明加解密参数authTag,长度为16字节。 采用GCM模式加密时,需要获取doFinal()输出的DataBlob,取出其末尾16字节作为解密时init()方法的入参GcmParamsSpec中的的authTag |
说明
传入init()方法前需要指定其algoName属性(来源于父类ParamsSpec)。
CcmParamsSpec
加解密参数ParamsSpec的子类,用于在对称加解密时作为init()方法的参数。
适用于CCM模式。
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
iv | 是 | 是 | 指明加解密参数iv,长度为7字节 | |
aad | 是 | 是 | 指明加解密参数aad,长度为8字节 | |
authTag | 是 | 是 | 指明加解密参数authTag,长度为12字节。 采用CCM模式加密时,需要获取doFinal()输出的DataBlob,取出其末尾12字节作为解密时init()方法的入参CcmParamsSpec中的authTag |
说明
传入init()方法前需要指定其algoName属性(来源于父类ParamsSpec)。
CryptoMode
表示加解密操作的枚举。
系统能力: SystemCapability.Security.CryptoFramework
名称 | 值 | 说明 |
ENCRYPT_MODE | 0 | 表示进行加密操作 |
DECRYPT_MODE | 1 | 表示进行解密操作 |
Key
密钥(父类),在运行密码算法(如加解密)时需要提前生成其子类对象,并传入Cipher实例的init()方法。
密钥可以通过密钥生成器来生成。
属性
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
format | string | 是 | 否 | 密钥的格式。 |
algName | string | 是 | 否 | 密钥对应的算法名(含长度)。 |
getEncoded
getEncoded() : DataBlob
以同步方法,获取16进制形式的密钥内容。
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
用于查看密钥的具体内容。 |
示例:
SymKey
对称密钥,是Key的子类,在对称加解密时需要将其对象传入Cipher实例的init()方法使用。
对称密钥可以通过对称密钥生成器SymKeyGenerator来生成。
clearMem
clearMem() : void
以同步方法,将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时,调用本函数,避免内存中密钥数据存留过久。
系统能力: SystemCapability.Security.CryptoFramework
示例:
PubKey
公钥,是Key的子类,在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。
公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。
属性
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
format | string | 是 | 否 | 密钥的格式。 |
algName | string | 是 | 否 | 密钥对应的算法名(含长度)。 |
getEncoded
getEncoded() : DataBlob
以同步方法,获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
用于查看密钥的具体内容。 |
示例:
PriKey
私钥,是Key的子类,在非对称加解密、签名、密钥协商时需要将其作为输入使用。
私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。
属性
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
format | string | 是 | 否 | 密钥的格式。 |
algName | string | 是 | 否 | 密钥对应的算法名(含长度)。 |
getEncoded
getEncoded() : DataBlob
以同步方法,获取二进制形式的密钥内容。私钥格式满足ASN.1语法,PKCS#8规范、DER编码方式。
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
用于查看密钥的具体内容。 |
示例:
clearMem
clearMem() : void
以同步方法,将系统底层内存中的的密钥内容清零。
系统能力: SystemCapability.Security.CryptoFramework
示例:
KeyPair
非对称密钥对,包含:公钥与私钥,。
可以通过非对称密钥生成器AsyKeyGenerator来生成。
属性
系统能力: SystemCapability.Security.CryptoFramework
名称 | 类型 | 可读 | 可写 | 说明 |
priKey | PriKey | 是 | 否 | 私钥。 |
pubKey | PubKey | 是 | 否 | 公钥。 |
cryptoFramework.createSymKeyGenerator
createSymKeyGenerator(algName : string) : SymKeyGenerator
通过指定算法名称的字符串,获取相应的对称密钥生成器实例。
支持的规格详见框架概述“密钥生成规格”一节。
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
algName | string | 是 | 待生成对称密钥生成器的算法名称。 具体取值详见框架概述“密钥生成规格”一节中的“字符串参数”。 |
返回值:
类型 | 说明 |
返回对称密钥生成器的对象。 |
示例:
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;否则为错误对象。 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
generateSymKey
generateSymKey() : Promise<SymKey>
异步获取该对称密钥生成器随机生成的密钥,通过Promise获取结果。
必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。
系统能力: SystemCapability.Security.CryptoFramework
返回值:
类型 | 说明 |
Promise<SymKey> | Promise对象,返回对称密钥SymKey。 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
convertKey
convertKey(key : DataBlob, callback : AsyncCallback<SymKey>) : void
异步根据指定数据生成对称密钥,通过注册回调函数获取结果。
必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
key | 是 | 指定的对称密钥材料。 | |
callback | AsyncCallback<SymKey> | 是 | 回调函数。当生成对称密钥成功,err为undefined,data为获取到的SymKey;否则为错误对象。 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
convertKey
convertKey(key : DataBlob) : Promise<SymKey>
异步根据指定数据生成对称密钥,通过Promise获取结果。
必须在使用createSymKeyGenerator创建对称密钥生成器后,才能使用本函数。
系统能力: SystemCapability.Security.CryptoFramework
参数:
参数名 | 类型 | 必填 | 说明 |
key | 是 | 指定的密钥材料数据。 |
返回值:
类型 | 说明 |
Promise<SymKey> | Promise对象,返回对称密钥SymKey。 |
错误码:
错误码ID | 错误信息 |
17620001 | memory error. |
示例:
