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.");
});

密钥转换说明

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

cryptoFramework.createCipher

createCipher(transformation : string) : Cipher

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

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

系统能力： SystemCapability.Security.CryptoFramework

参数：

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

说明

目前对称加解密中，PKCS5和PKCS7的实现相同，其padding长度和分组长度保持一致（即PKCS5和PKCS7在3DES中均按照8字节填充，在AES中均按照16字节填充），另有NoPadding表示不填充。
开发者需要自行了解密码学不同分组模式的差异，以便选择合适的参数规格。例如选择ECB和CBC模式时，建议启用填充，否则必须确保明文长度是分组大小的整数倍；选择其他模式时，可以不启用填充，此时密文长度和明文长度一致（即可能不是分组大小的整数倍）。
使用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()初始化后，才能使用本函数。

说明

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

说明

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

说明

对称加解密中，调用doFinal标志着一次加解密流程已经完成，即Cipher实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用init()并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。
如果遇到解密失败，需检查加解密数据和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的输出有如下区别：

对于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，拼接结果得到完整的明文/密文。

说明

对称加解密中，调用doFinal标志着一次加解密流程已经完成，即Cipher实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用init()并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。
如果遇到解密失败，需检查加解密数据和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

分类

卡片开发

三方件

标签

HarmonyOS API

已于2023-4-4 16:26:35修改

51CTO

51CTO博客

51CTO学堂

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

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

cryptoFramework.createAsyKeyGenerator

AsyKeyGenerator

属性

generateKeyPair

generateKeyPair

convertKey

convertKey

cryptoFramework.createCipher

Cipher

属性

init

init

update

update

doFinal

doFinal

cryptoFramework.createSign

Sign

属性

init

init

update

update

sign

sign

cryptoFramework.createVerify

Verify

属性

init

init

update

update

verify

verify

cryptoFramework.createKeyAgreement

KeyAgreement

属性

generateSecret

generateSecret

目录

订阅鸿蒙技术特刊，精选内容抢先看