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

joytrian
发布于 2023-4-4 16:26
浏览
0收藏

版本:v3.1 Beta

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

cryptoFramework.createAsyKeyGenerator

createAsyKeyGenerator(algName : string) : AsyKeyGenerator

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

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

algName

string

待生成对称密钥生成器的算法名称。

返回值:

类型

说明

​AsyKeyGenerator​

返回非对称密钥生成器的对象。

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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​​>

回调函数,用于获取非对称密钥。

错误码:

错误码ID

错误信息

17620001

memory error.

示例:

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>

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

系统能力: SystemCapability.Security.CryptoFramework

返回值:

类型

说明

Promise<​​KeyPair​​>

使用Promise的方式获取非对称密钥。

错误码:

错误码ID

错误信息

17620001

memory error.

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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

convertKey

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

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

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

pubKey

​DataBlob​

指定的公钥材料。如果公钥不需要转换,可直接传入null。

priKey

​DataBlob​

指定的私钥材料。如果私钥不需要转换,可直接传入null。

callback

AsyncCallback<​​KeyPair​​>

回调函数,用于获取非对称密钥。

错误码:

错误码ID

错误信息

17620001

memory error.

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"
let pubKey; // X.509规范、DER格式的公钥数据,此处省略数据。
let priKey; // PKCS#8规范、DER格式的私钥数据,此处省略数据。
let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
asyKeyGenerator.convertKey(pubKey, priKey, (err, keyPair) => {
  if (err) {
    console.error("convertKey: error.");
    return;
  }
  console.info("convertKey: success.");
})

convertKey

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

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

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

pubKey

DataBlob

指定的公钥材料。如果公钥不需要转换,可直接传入null

priKey

DataBlob

指定的私钥材料。如果私钥不需要转换,可直接传入null

返回值:

类型

说明

Promise<​​KeyPair​​>

使用Promise的方式获取非对称密钥。

错误码:

错误码ID

错误信息

17620001

memory error.

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
let pubKey; // pubKey为使用非对称密钥生成器生成的非对称密钥的公钥对象,此处省略生成过程
let priKey; // priKey为使用非对称密钥生成器生成的非对称密钥的私钥对象,此处省略生成过程
let keyGenPromise = asyKeyGenerator.convertKey(pubKey, priKey);
keyGenPromise.then( keyPair => {
  console.info("convertKey success.");
}).catch(error => {
  console.error("convertKey error.");
});

密钥转换说明

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

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进行非对称加解密时,必须创建两个Cipher对象分别进行加密和解密操作,而不能对同一个Cipher对象进行加解密。对称加解密没有此要求(即只要算法规格一样,可以对同一个Cipher对象进行加解密操作)。


返回值:

类型

说明

​Cipher​

返回加解密生成器的对象。

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

let cipherAlgoName = '3DES192|ECB|PKCS7';
var cipher;
try {
  cipher = cryptoFramework.createCipher(cipherAlgoName);
  console.info(`cipher algName: ${cipher.algName}`);
} catch (error) {
  console.error(`createCipher failed, ${error.code}, ${error.message}`);
}

Cipher

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

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

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

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

属性

系统能力: SystemCapability.Security.CryptoFramework

名称

类型

可读

可写

说明

algName

string

加解密生成器指定的算法名称。

init

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

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

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

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

opMode

​CryptoMode​

加密或者解密模式。

key

​Key​

指定加密或解密的密钥。

params

​ParamsSpec​

指定加密或解密的参数,对于ECB等没有参数的算法模式,可以传入null。

callback

AsyncCallback<void>

回调函数。当初始化成功,err为undefined,否则为错误对象。

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

示例:

import cryptoFramework from '@ohos.security.cryptoFramework';
let symKey;     // 此处省略生成对称密钥的过程
let cipher;         // 此处省略生成cipher实例的过程

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`);
    // 此处进行update等后续操作
  }
})

init

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

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

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

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

opMode

​CryptoMode​

加密或者解密模式。

key

​Key​

指定加密或解密的密钥。

params

​ParamsSpec​

指定加密或解密的参数,对于ECB等没有参数的算法模式,可以传入null。

返回值:

类型

说明

Promise<void>

Promise对象。无返回结果的Promise对象。

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

示例:

import cryptoFramework from '@ohos.security.cryptoFramework';
let symKey;     // 此处省略生成对称密钥的过程
let cipher;         // 此处省略生成cipher实例的过程
cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null)
.then(() => {
  console.info(`Init cipher success`);
  // 此处进行update等后续操作
}, error => {
  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的方式传入数据。
  3. RSA非对称加解密不支持update操作。


系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

加密或者解密的数据。data不能为null,也不允许传入{data : Uint8Array(空) }

callback

AsyncCallback<​​DataBlob​​>

回调函数。当更新加/解密数据成功,err为undefined,data为此次更新的加/解密结果DataBlob;否则为错误对象。

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

示例:

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

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

let cipher;         // 此处省略生成cipher实例的过程
// 此处省略init()过程
let plainText = {data : stringToUint8Array('this is test!')};
cipher.update(plainText, (err, output) => {       // 加密过程举例
  if (err) {
    console.error(`Failed to update cipher`);
  } else {
    console.info(`Update cipher success`);
    if (output != null) {
      // 拼接output.data到密文
    }
    // 此处进行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的方式传入数据。
  3. RSA非对称加解密不支持update操作。


系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

加密或者解密的数据。data不能为null,也不允许传入{data : Uint8Array(空) }

返回值:

类型

说明

Promise<​​DataBlob​​>

Promise对象,返回此次更新的加/解密结果DataBlob。

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

示例:

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

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

let cipher;         // 此处省略生成cipher实例的过程
// 此处省略init()过程
let plainText = {data : stringToUint8Array('this is test!')};
cipher.update(plainText)
.then((output) => {
  console.info(`Update cipher success.`);
  if (output != null) {
    // 拼接output.data到密文
  }
  // 此处进行doFinal等后续操作
}, error => {
  console.info(`Update cipher failed.`);
})

doFinal

doFinal(data : DataBlob, 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需要填入解密时的​​​GcmParamsSpec​​​或​​CcmParamsSpec​​;密文则作为解密时的入参data。
  • 对于其他模式的对称加解密、GCM和CCM模式的对称解密:一次加/解密流程中,每一次update和doFinal的结果拼接起来,得到完整的明文/密文。

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


说明

  1. 对称加解密中,调用doFinal标志着一次加解密流程已经完成,即​​Cipher​​​实例的状态被清除,因此当后续开启新一轮加解密流程时,需要重新调用​​init()​​​并传入完整的参数列表进行初始化
    (比如即使是对同一个Cipher实例,采用同样的对称密钥,进行加密然后解密,则解密中调用init的时候仍需填写params参数,而不能直接省略为null)。
  2. 如果遇到解密失败,需检查加解密数据和​​init​​时的参数是否匹配,包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。


系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

加密或者解密的数据。在对称加解密中允许为null,但不允许传入{data : Uint8Array(空) }。

callback

AsyncCallback<​​DataBlob​​>

回调函数。当最终加/解密数据成功,err为undefined,data为剩余数据的加/解密结果DataBlob;否则为错误对象。

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

示例:

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

let cipher;         // 此处省略生成cipher实例的过程
let data;           // 此处省略准备待加密/解密数据的过程
// 此处省略init()和update()过程
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) {
      // 拼接output.data得到完整的明文/密文(及authTag)
    }
  }
})

doFinal

doFinal(data : DataBlob) : 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需要填入解密时的​​​GcmParamsSpec​​​或​​CcmParamsSpec​​;密文则作为解密时的入参data。
  • 对于其他模式的对称加解密、GCM和CCM模式的对称解密:一次加/解密流程中,每一次update和doFinal的结果拼接起来,得到完整的明文/密文。

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


说明

  1. 对称加解密中,调用doFinal标志着一次加解密流程已经完成,即​​Cipher​​​实例的状态被清除,因此当后续开启新一轮加解密流程时,需要重新调用​​init()​​​并传入完整的参数列表进行初始化
    (比如即使是对同一个Cipher实例,采用同样的对称密钥,进行加密然后解密,则解密中调用init的时候仍需填写params参数,而不能直接省略为null)。
  2. 如果遇到解密失败,需检查加解密数据和​​init​​时的参数是否匹配,包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。


系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

加密或者解密的数据。data参数允许为null,但不允许传入{data : Uint8Array(空) }

返回值:

类型

说明

Promise<​​DataBlob​​>

Promise对象,返回剩余数据的加/解密结果DataBlob。

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

示例:

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

let cipher;         // 此处省略生成cipher实例的过程
let data;           // 此处省略准备待加密/解密数据的过程
// 此处省略init()和update()过程
cipher.doFinal(data)
.then(output => {
  console.info(`Finalize cipher success`);
    if (output != null) {
    // 拼接output.data得到完整的明文/密文(及authTag)
  }
}, error => {
  console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`);
})

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

import cryptoFramework from "@ohos.security.cryptoFramework"

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

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

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

import cryptoFramework from "@ohos.security.cryptoFramework"

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

let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
let cipher = cryptoFramework.createCipher("RSA1024|PKCS1");
let keyGenPromise = rsaGenerator.generateKeyPair();
keyGenPromise.then(rsaKeyPair => {
  let pubKey = rsaKeyPair.pubKey;
  return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // 传入私钥和DECRYPT_MODE可初始化解密模式
}).then(() => {
  let plainText = "this is cipher text";
  let input = { data : stringToUint8Array(plainText) };
  return cipher.doFinal(input);
}).then(dataBlob => {
  console.info("EncryptOutPut is " + dataBlob.data);
});


说明

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

cryptoFramework.createSign

createSign(algName : string) : Sign

Sign实例生成

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

algName

string

指定签名算法:RSA或ECC,使用RSA PKCS1模式时需要设置摘要,使用RSA PSS模式时需要设置摘要和掩码摘要

返回值

类型

说明

Sign

返回由输入算法指定生成的Sign对象

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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

let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256")

Sign

Sign类,使用Sign方法之前需要创建该类的实例进行操作,通过createSign(algName : string) : Sign方法构造此实例。Sign类不支持重复初始化,当业务方需要使用新密钥签名时,需要重新创建新Sign对象并调用init初始化。

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

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

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

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

属性

系统能力: SystemCapability.Security.CryptoFramework

名称

类型

可读

可写

说明

algName

string

签名指定的算法名称。

init

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

使用私钥初始化Sign对象,Callback形式,Sign类暂不支持重复init

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

priKey

​PriKey​

用于Sign的初始化

callback

AsyncCallback<void>

回调函数

错误码:

错误码ID

错误信息

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对象

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

update

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

追加待签名数据,callback方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

callback

AsyncCallback<void>

回调函数

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

update

update(data : DataBlob) : Promise<void>;

追加待签名数据,promise方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

返回值:

类型

说明

Promise<void>

Promise对象

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

sign

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

对数据进行签名,返回签名结果,callback方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

callback

AsyncCallback<​​DataBlob​​ >

回调函数

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

sign

sign(data : DataBlob) : Promise<DataBlob>

对数据进行签名,返回签名结果,promise方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

返回值:

类型

说明

Promise<void>

Promise对象

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

callback示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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

let globalKeyPair;
let SignMessageBlob;
let plan1 = "This is Sign test plan1"; // The first segment of data.
let plan2 = "This is Sign test plan2"; // The second segment of fata.
let input1 = { data : stringToUint8Array(plan1) };
let input2 = { data : stringToUint8Array(plan2) };

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

promise示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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

let globalKeyPair;
let SignMessageBlob;
let plan1 = "This is Sign test plan1"; // The first segment of data.
let plan2 = "This is Sign test plan2"; // The second segment of fata.
let input1 = { data : stringToUint8Array(plan1) };
let input2 = { data : stringToUint8Array(plan2) };

function signMessagePromise() {
  let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2");
  let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
  let keyGenPromise = rsaGenerator.generateKeyPair();
  keyGenPromise.then( keyPair => {
    globalKeyPair = keyPair;
    let priKey = globalKeyPair.priKey;
    return signer.init(priKey);
  }).then(() => {
    return signer.update(input1); // add first segment of data
  }).then(() => {
    return signer.sign(input2); // add second segment of data, sign input1 and input2
  }).then(dataBlob => {
    SignMessageBlob = dataBlob;
    console.info("sign output is " + SignMessageBlob.data);
    AlertDialog.show({message : "output" +  SignMessageBlob.data});
  });
}

cryptoFramework.createVerify

createVerify(algName : string) : Verify

Verify实例生成

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

algName

string

指定签名算法:RSA或ECC,使用RSA PKCS1模式时需要设置摘要,使用RSA PSS模式时需要设置摘要和掩码摘要

返回值

类型

说明

Verify

返回由输入算法指定生成的Verify对象

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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

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

Verify

Verify类,使用Verify方法之前需要创建该类的实例进行操作,通过createVerify(algName : string) : Verify方法构造此实例。

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

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

当签名数据较短时,可在init初始化后直接调用verify接口传入签名数据和原文进行验签。

当签名数据较长时,可通过update接口分段传入签名数据,最后调用verify接口对整体签名数据进行验签。

当使用update分段传入签名数据时,verify接口的签名数据支持传null,业务方可在循环中调用update接口,循环结束后调用verify传入原文进行验签。

属性

系统能力: SystemCapability.Security.CryptoFramework

名称

类型

可读

可写

说明

algName

string

验签指定的算法名称。

init

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

传入公钥初始化Verify对象,Callback形式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

pubKey

​PubKey​

公钥对象,用于Verify的初始化

callback

AsyncCallback<void>

回调函数

错误码:

错误码ID

错误信息

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对象

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

update

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

追加待验签数据,callback方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

callback

AsyncCallback<void>

回调函数

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

update

update(data : DataBlob) : Promise<void>;

追加待验签数据,promise方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

返回值:

类型

说明

Promise<void>

Promise对象

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

verify

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

对数据进行验签,返回验签结果,callback方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

signatureData

​DataBlob​

签名数据

callback

AsyncCallback<boolean>

回调函数

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

verify

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

对数据进行验签,返回验签结果,promise方式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

data

​DataBlob​

传入的消息

signatureData

​DataBlob​

签名数据

返回值:

类型

说明

Promise<boolean>

异步返回值,代表验签是否通过

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

callback示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象,此处省略生成过程
let input1 = null;
let input2 = null;
let signMessageBlob = null; // 签名后的数据,此处省略
let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25");
verifyer.init(globalKeyPair.pubKey, function (err, data) {
  verifyer.update(input1, function(err, data) {
    verifyer.verify(input2, signMessageBlob, function(err, data) {
      console.info("verify result is " + data);
    })
  });
})

promise示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象,此处省略生成过程
let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256");
let verifyInitPromise = verifyer.init(globalKeyPair.pubKey);
let input1 = null;
let input2 = null;
let signMessageBlob = null; // 签名后的数据,此处省略
verifyInitPromise.then(() => {
  return verifyer.update(input1);
}).then(() => {
  return verifyer.verify(input2, signMessageBlob);
}).then(res => {
  console.log("Verify result is " + res);
});

cryptoFramework.createKeyAgreement

createKeyAgreement(algName : string) : KeyAgreement

KeyAgreement实例生成

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

algName

string

指定密钥协商算法:目前仅支持ECC

返回值

类型

说明

KeyAgreement

返回由输入算法指定生成的KeyAgreement对象

示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

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

基于传入的私钥与公钥进行密钥协商,返回共享秘密,Callback形式

系统能力: SystemCapability.Security.CryptoFramework

参数:

参数名

类型

必填

说明

priKey

​PriKey​

设置密钥协商的私钥输入

pubKey

​PubKey​

设置密钥协商的公钥输入

callback

AsyncCallback<​​DataBlob​​>

异步接受共享秘密的回调

错误码:

错误码ID

错误信息

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​​>

共享秘密

错误码:

错误码ID

错误信息

17620001

memory error.

17620002

runtime error.

17630001

crypto operation error.

callback示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象,此处省略生成过程
let keyAgreement = cryptoFramework.createKeyAgreement("ECC256");
keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function (err, secret) {
  if (err) {
    console.error("keyAgreement error.");
    return;
  }
  console.info("keyAgreement output is " + secret.data);
});

promise示例:

import cryptoFramework from "@ohos.security.cryptoFramework"

let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象,此处省略生成过程
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) => {
  console.error("keyAgreement error.");
});


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-cryptoframework-0000001477981409-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001477981409__属性-11​

已于2023-4-4 16:26:35修改
收藏
回复
举报
回复
    相关推荐