From aa5cdb47ba86ef243ef7e039e6809a0a21a4e269 Mon Sep 17 00:00:00 2001 From: wangyongzhong2 Date: Thu, 9 Feb 2023 16:16:18 +0800 Subject: [PATCH] crypto framework docs update Signed-off-by: wangyongzhong2 --- .../reference/apis/js-apis-cryptoFramework.md | 5334 +++++++++-------- .../security/cryptoFramework-guidelines.md | 2719 +++++---- .../security/cryptoFramework-overview.md | 620 +- 3 files changed, 4674 insertions(+), 3999 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md index 64c706d77b..ba5f0890e9 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @@ -1,2651 +1,2683 @@ -# @ohos.security.cryptoFramework (加解密算法库框架) - -为屏蔽底层硬件和算法库，向上提供统一的密码算法库加解密相关接口。 - -> **说明：** -> -> 本模块首批接口从API version 9开始支持。 - -## 导入模块 - -```javascript -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数组。 - - **系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ---- | ---------- | ---- | ---- | ------ | -| data | Uint8Array | 是 | 是 | 数据。 | - - -## cryptoFramework.createMac - -createMac(algName : string) : Mac - -生成Mac实例，用于进行消息认证码的计算与操作 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定摘要算法，支持算法范围：SHA1/SHA224/SHA256/SHA384/SHA512 | - -**返回值**： - -| 类型 | 说明 | -| ---- | --------------------------------------- | -| Mac | 返回由输入算法指定生成的[Mac](#mac)对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------ | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - // 参数选择请参考上述算法支持范围 - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -``` - -## Mac - -Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密计算。调用前，需要通过[createMac](#cryptoframeworkcreatemac)构造Mac实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | -------------------- | -| algName | string | 是 | 否 | 代表指定的摘要算法名 | - -### init - -init(key : SymKey, callback : AsyncCallback\) : void; - -使用对称密钥初始化Mac计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------ | -| key | [SymKey](#symkey) | 是 | 共享对称密钥 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -var KeyBlob; -var 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\; - -使用对称密钥初始化Mac计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------ | -| key | [SymKey](#symkey) | 是 | 共享对称密钥 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); - -``` - -### update - -update(input : DataBlob, callback : AsyncCallback\) : void; - -传入消息进行Mac更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| input | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var KeyBlob; -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -var 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; - mac.update(blob, (err2, data) => { - if (err2) { - console.error("[Callback] err: " + err2.code); - } - }); - }); -}); -``` - -### update - -update(input : DataBlob) : Promise\; - -传入消息进行Mac更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| input | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).then(() => { - let blob; - var promiseMacUpdate = mac.update(blob); - return promiseMacUpdate; -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); - -``` - -### doFinal - -doFinal(callback : AsyncCallback\) : void; - -返回Mac的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | -------- | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var KeyBlob; -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -var 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; - 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\ - -返回Mac的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------------------ | ----------- | -| Promise\<[DataBlob](#datablob)> | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).then(() => { - let blob; - var promiseMacUpdate = mac.update(blob); - return promiseMacUpdate; -}).then(() => { - var PromiseMacDoFinal = mac.doFinal(); - return PromiseMacDoFinal; -}).then(macOutput => { - console.error("[Promise]: HMAC result: " + macOutput.data); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### getMacLength - -getMacLength() : number - -获取Mac消息认证码的长度（字节数） - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------ | ------------------------- | -| number | 返回mac计算结果的字节长度 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).then(() => { - let blob; - var promiseMacUpdate = mac.update(blob); - return promiseMacUpdate; -}).then(() => { - var 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 => { - console.error("[Promise]: error: " + error.message); -}); -``` - -## cryptoFramework.createMd - -createMd(algName : string) : Md - -生成Md实例，用于进行消息摘要的计算与操作 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定摘要算法，支持算法范围：SHA1/SHA224/SHA256/SHA384/SHA512/MD5 | - -**返回值**： - -| 类型 | 说明 | -| ---- | ------------------------------------- | -| Md | 返回由输入算法指定生成的[Md](#md)对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------ | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - // 参数选择请参考上述算法支持范围 - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -``` - -## Md - -Md类，调用Md方法可以进行MD（Message Digest）摘要计算。调用前，需要通过[createMd](#cryptoframeworkcreatemd)构造Md实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | -------------------- | -| algName | string | 是 | 否 | 代表指定的摘要算法名 | - -### update - -update(input : DataBlob, callback : AsyncCallback\) : void; - -传入消息进行Md更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| input | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -md.update(blob, (err,) => { - if (err) { - console.error("[Callback] err: " + err.code); - } -}); -``` - -### update - -update(input : DataBlob) : Promise\; - -传入消息进行Md更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| input | DataBlob | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -var promiseMdUpdate = md.update(blob); -promiseMdUpdate.then(() => { - // do something -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### digest - -digest(callback : AsyncCallback\) : void - -返回Md的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | -------- | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -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\ - -返回Md的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------------------ | ----------- | -| Promise\<[DataBlob](#datablob)> | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -var promiseMdUpdate = md.update(blob); -promiseMdUpdate.then(() => { - var PromiseMdDigest = md.digest(); - return PromiseMdDigest; -}).then(mdOutput => { - console.error("[Promise]: MD result: " + mdOutput.data); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### getMdLength - -getMdLength() : number - -获取Md消息摘要长度（字节数） - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------ | ------------------------ | -| number | 返回md计算结果的字节长度 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -var promiseMdUpdate = md.update(blob); -promiseMdUpdate.then(() => { - var 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 => { - console.error("[Promise]: error: " + error.message); -}); -``` - -## cryptoFramework.createRandom - -createRandom() : Random - -生成Random实例，用于进行随机数的计算与设置种子 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值**： - -| 类型 | 说明 | -| ------ | --------------------------------------------- | -| Random | 返回由输入算法指定生成的[Random](#random)对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------ | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -try { - var rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -``` - -## Random - -Random类，调用Random方法可以进行随机数计算。调用前，需要通过[createRandom](#cryptoframeworkcreaterandom)构造Random实例。 - -### generateRandom - -generateRandom(len : number, callback: AsyncCallback\) : void; - -生成指定长度的随机数 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | -------------------- | -| len | number | 是 | 表示生成随机数的长度 | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var rand; -try { - rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -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\; - -生成指定长度的随机数 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | -------------------- | -| len | number | 是 | 表示生成随机数的长度 | - -**返回值：** - -| 类型 | 说明 | -| ------------------ | ----------- | -| Promise\<[DataBlob](#datablob)> | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var rand; -try { - rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} - -var promiseGenerateRand = rand.generateRandom(12); -promiseGenerateRand.then(randData => { - console.error("[Promise]: rand result: " + randData.data); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### setSeed - -setSeed(seed : DataBlob) : void; - -设置指定的种子 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | ---------- | -| seed | DataBlob | 是 | 设置的种子 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ----------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var rand; -try { - rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} - -rand.generateRandom(12, (err, randData) => { - if (err) { - console.error("[Callback] err: " + err.code); - } else { - console.error("[Callback]: generate random result: " + randData.data); - try { - rand.setSeed(randData); - } catch (error) { - console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); - } - } -}); -``` - -## ParamsSpec - -加解密参数，在进行对称加解密时需要构造其子类对象，并将子类对象传入[init()](#init-2)方法。
适用于需要iv等参数的对称加解密模式（对于无iv等参数的模式如ECB模式，无需构造，在[init()](#init-2)中传入null即可）。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| -------- | ------ | ---- | ---- | ----------------------- | -| algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | - -> **说明：** -> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 - -## IvParamsSpec - -加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | -| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：
- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节
- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | - -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 - -## GcmParamsSpec - -加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于GCM模式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | -| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为12字节 | -| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | -| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。
采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾16字节作为解密时[init()](#init-2)方法的入参[GcmParamsSpec](#gcmparamsspec)中的的authTag | - -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 - -## CcmParamsSpec - -加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CCM模式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | -| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为7字节 | -| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | -| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。
采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾12字节作为解密时[init()](#init-2)方法的入参[CcmParamsSpec](#ccmparamsspec)中的authTag | - -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 - -## CryptoMode - -表示加解密操作的枚举。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 值 | 说明 | -| ------------ | ---- | ---------------- | -| ENCRYPT_MODE | 0 | 表示进行加密操作 | -| DECRYPT_MODE | 1 | 表示进行解密操作 | - -## Key - -密钥（父类），在运行密码算法（如加解密）时需要提前生成其子类对象，并传入[Cipher](#cipher)实例的[init()](#init-2)方法。
密钥可以通过密钥生成器来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| format | string | 是 | 否 | 密钥的格式。 | -| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | - -### getEncoded - -getEncoded() : DataBlob - -以同步方法，获取16进制形式的密钥内容。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------- | ------------------------ | -| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | - -**示例：** - -```js -import cryptoFramework from "@ohos.security.cryptoFramework" -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 -let encodedKey = key.getEncoded(); -console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); -``` - -## SymKey - -对称密钥，是[Key](#key)的子类，在对称加解密时需要将其对象传入[Cipher](#cipher)实例的[init()](#init-2)方法使用。
对称密钥可以通过对称密钥生成器[SymKeyGenerator](#symkeygenerator)来生成。 - -### clearMem - -clearMem() : void - -以同步方法，将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时，调用本函数，避免内存中密钥数据存留过久。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**示例：** - -```js -import cryptoFramework from "@ohos.security.cryptoFramework" -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 -let encodedKey = key.getEncoded(); -console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出密钥内容 -key.clearMem(); -encodedKey = key.getEncoded(); -console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出全零 -``` - -## PubKey - -公钥，是Key的子类，在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。
公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| format | string | 是 | 否 | 密钥的格式。 | -| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | - - -### getEncoded - -getEncoded() : DataBlob - -以同步方法，获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------- | ------------------------ | -| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | - -**示例：** - -```js -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 -console.info("key format:" + key.format); -console.info("key algName:" + key.algName); -var encodedKey = key.getEncoded(); -console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); -``` - -## PriKey - -私钥，是Key的子类，在非对称加解密、签名、密钥协商时需要将其作为输入使用。
私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| format | string | 是 | 否 | 密钥的格式。 | -| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | - -### getEncoded - -getEncoded() : DataBlob - -以同步方法，获取二进制形式的密钥内容。私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------- | ------------------------ | -| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | - -**示例：** - -```js -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 -console.info("key format:" + key.format); -console.info("key algName:" + key.algName); -var encodedKey = key.getEncoded(); -console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); -``` - -### clearMem - -clearMem() : void - -以同步方法，将系统底层内存中的的密钥内容清零。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**示例：** - -```js -let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 -key.clearMem(); -``` - -## KeyPair - -非对称密钥对，包含：公钥与私钥，。
可以通过非对称密钥生成器AsyKeyGenerator来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ------------ | -| priKey | [PriKey](#prikey) | 是 | 否 | 私钥。 | -| pubKey | [PubKey](#pubkey) | 是 | 否 | 公钥。 | - - -## cryptoFramework.createSymKeyGenerator - -createSymKeyGenerator(algName : string) : SymKeyGenerator - -通过指定算法名称的字符串，获取相应的对称密钥生成器实例。
支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 待生成对称密钥生成器的算法名称。
具体取值详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节中的“字符串参数”。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------- | -------------------------- | -| [SymKeyGenerator](#symkeygenerator) | 返回对称密钥生成器的对象。 | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); -``` - -## SymKeyGenerator - -对称密钥生成器。
在使用该类的方法前，需要先使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)方法构建一个symKeyGenerator实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ------------------------------ | -| algName | string | 是 | 否 | 对称密钥生成器指定的算法名称。 | - -### generateSymKey - -generateSymKey(callback : AsyncCallback\) : void - -异步获取对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -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\ - -异步获取该对称密钥生成器随机生成的密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------------- | --------------------------------- | -| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symAlgName = 'AES128'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); -symKeyGenerator.generateSymKey() -.then(symKey => { - console.info(`Generate symKey success, algName: ${symKey.algName}`); -}, error => { - console.error(`Generate symKey failed, ${error.code}, ${error.message}`); -}) -``` - -### convertKey - -convertKey(key : DataBlob, callback : AsyncCallback\) : void - -异步根据指定数据生成对称密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | -| key | [DataBlob](#datablob) | 是 | 指定的对称密钥材料。 | -| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | --------------------------------------------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function genKeyMaterialBlob() { - 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\ - -异步根据指定数据生成对称密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | --------------------- | ---- | -------------------- | -| key | [DataBlob](#datablob) | 是 | 指定的密钥材料数据。 | - -**返回值：** - -| 类型 | 说明 | -| --------------------------- | --------------------------------- | -| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | --------------------------------------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function genKeyMaterialBlob() { - 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 => { - console.error(`Convert symKey failed, ${error.code}, ${error.message}`); -}) -``` - -## cryptoFramework.createAsyKeyGenerator - -createAsyKeyGenerator(algName : string) : AsyKeyGenerator - -通过指定算法名称的字符串，获取相应的非对称密钥生成器实例。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | -------------------------------- | -| algName | string | 是 | 待生成对称密钥生成器的算法名称。 | - -**返回值：** - -| 类型 | 说明 | -| --------------- | ---------------------------- | -| [AsyKeyGenerator](#asykeygenerator) | 返回非对称密钥生成器的对象。 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); -``` - -## AsyKeyGenerator - -非对称密钥生成器。在使用该类的方法前，需要先使用createAsyKeyGenerator()方法构建一个AsyKeyGenerator实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | -------------------------------- | -| algName | string | 是 | 否 | 非对称密钥生成器指定的算法名称。 | - -### generateKeyPair - -generateKeyPair(callback : AsyncCallback\) : void; - -异步获取非对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ---- | ------------------------------ | -| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -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\ - -异步获取该非对称密钥生成器随机生成的密钥，通过Promise获取结果。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ----------------- | --------------------------------- | -| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -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\) : void - -异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。详情请看下方**密钥转换说明** - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------ | -| pubKey | [DataBlob](#datablob) | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null。 | -| priKey | [DataBlob](#datablob) | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null。 | -| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -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\ - -异步获取指定数据生成非对称密钥，通过Promise获取结果。详情请看下方**密钥转换说明** - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------------- | -| pubKey | DataBlob | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null | -| priKey | DataBlob | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null | - -**返回值：** - -| 类型 | 说明 | -| ----------------- | --------------------------------- | -| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -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](#cipher)实例。
支持的规格详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------ | ---- | ------------------------------------------------------------ | -| transformation | string | 是 | 待生成Cipher的算法名称（含密钥长度）、加密模式以及填充方法的组合。
具体取值详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节中的“字符串参数”。 | - -> **说明：** -> 1. 目前对称加解密中，PKCS5和PKCS7的实现相同，其padding长度和分组长度保持一致（即PKCS5和PKCS7在3DES中均按照8字节填充，在AES中均按照16字节填充），另有NoPadding表示不填充。
开发者需要自行了解密码学不同分组模式的差异，以便选择合适的参数规格。例如选择ECB和CBC模式时，建议启用填充，否则必须确保明文长度是分组大小的整数倍；选择其他模式时，可以不启用填充，此时密文长度和明文长度一致（即可能不是分组大小的整数倍）。 -> 2. 使用RSA进行非对称加解密时，必须创建两个Cipher对象分别进行加密和解密操作，而不能对同一个Cipher对象进行加解密。对称加解密没有此要求（即只要算法规格一样，可以对同一个Cipher对象进行加解密操作）。 - -**返回值：** - -| 类型 | 说明 | -| ----------------- | ------------------------ | -| [Cipher](#cipher) | 返回加解密生成器的对象。 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let cipherAlgName = '3DES192|ECB|PKCS7'; -var cipher; -try { - cipher = cryptoFramework.createCipher(cipherAlgName); - console.info(`cipher algName: ${cipher.algName}`); -} catch (error) { - console.error(`createCipher failed, ${error.code}, ${error.message}`); -} -``` - -## Cipher - -提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。
完整的加解密流程示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 - -一次完整的加/解密流程在对称加密和非对称加密中略有不同： - -- 对称加解密：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 - -初始化加解密的[cipher](#cipher)对象，通过注册回调函数获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | -| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | -| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | -| callback | AsyncCallback\ | 是 | 回调函数。当初始化成功，err为undefined，否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | --------------------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error.| - -**示例：** - -```js -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\ - -初始化加解密的cipher对象，通过Promise获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------------------- | ---- | ------------------------------------------------------------ | -| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | -| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | -| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | -------------------------------------- | -| Promise\ | Promise对象。无返回结果的Promise对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error.| - -**示例：** - -```js -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\) : void - -分段更新加密或者解密数据操作，通过注册回调函数获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 - -> **说明：** -> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） -> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，采用多次update的方式传入数据。 -> 3. RSA非对称加解密不支持update操作。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当更新加/解密数据成功，err为undefined，data为此次更新的加/解密结果DataBlob；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -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\ - -分段更新加密或者解密数据操作，通过通过Promise获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 - -> **说明：** -> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） -> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，可以采用多次update的方式传入数据。 -> 3. RSA非对称加解密不支持update操作。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | --------------------- | ---- | -------------------- | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------- | ------------------------------------------------ | -| Promise\<[DataBlob](#datablob)> | Promise对象，返回此次更新的加/解密结果DataBlob。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | -------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -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\) : void - -（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： - -- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 -- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 - -（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过注册回调函数获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 - -> **说明：** -> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 -> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。在对称加解密中允许为null，但不允许传入{data : Uint8Array(空) }。 | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当最终加/解密数据成功，err为undefined，data为剩余数据的加/解密结果DataBlob；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ----------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -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\ - -（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过Promise获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： - -- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 -- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 - -（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过Promise获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 - -> **说明：** -> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 -> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | --------------------- | ---- | -------------------- | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data参数允许为null，但不允许传入{data : Uint8Array(空) } | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------- | ------------------------------------------------ | -| Promise\<[DataBlob](#datablob)> | Promise对象，返回剩余数据的加/解密结果DataBlob。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | -------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -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完整示例：** - -```javascript -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完整示例：** - -```javascript -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); -}); -``` - -> **说明：** -> 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 - -## cryptoFramework.createSign - -createSign(algName : string) : Sign - -Sign实例生成 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | - -**返回值**： - -| 类型 | 说明 | -| ---- | -------------------------------- | -| Sign | 返回由输入算法指定生成的Sign对象 | - -**示例：** - -```javascript -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 - -使用私钥初始化Sign对象，Callback形式，Sign类暂不支持重复init - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------------- | -| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### init - -init(priKey : PriKey) : Promise\ - -使用私钥初始化Sign对象，Promise形式，Sign类暂不支持重复init - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ---------------- | -| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob, callback : AsyncCallback\) : void - -追加待签名数据，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob) : Promise\; - -追加待签名数据，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### sign - -sign(data : DataBlob, callback : AsyncCallback\) : void - -对数据进行签名，返回签名结果，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | -| callback | AsyncCallback\<[DataBlob](#datablob) > | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### sign - -sign(data : DataBlob) : Promise\ - -对数据进行签名，返回签名结果，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**callback示例：** - -```javascript -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示例：** - -```javascript -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对象 | - -**示例：** - -```javascript -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 - -传入公钥初始化Verify对象，Callback形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------------------------- | -| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### init - -init(pubKey : PubKey) : Promise\ - -传入公钥初始化Verify对象，Promise形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ---------------------------- | -| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob, callback : AsyncCallback\) : void - -追加待验签数据，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob) : Promise\; - -追加待验签数据，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### verify - -verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void - -对数据进行验签，返回验签结果，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | -| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### verify - -verify(data : DataBlob, signatureData : DataBlob) : Promise\ - -对数据进行验签，返回验签结果，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------------- | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | -| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | - -**返回值：** - -| 类型 | 说明 | -| ----------------- | ---------------------------- | -| Promise\ | 异步返回值，代表验签是否通过 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**callback示例：** - -```javascript -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示例：** - -```javascript -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对象 | - -**示例：** - -```javascript -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\) : void - -基于传入的私钥与公钥进行密钥协商，返回共享秘密，Callback形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | ---------------------- | -| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | -| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 异步接受共享秘密的回调 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### generateSecret - -generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\ - -基于传入的私钥与公钥进行密钥协商，返回共享秘密，Promise形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ---------------------- | -| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | -| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | - -**返回值：** - -| 类型 | 说明 | -| ------------------ | -------- | -| Promise\<[DataBlob](#datablob)> | 共享秘密 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**callback示例：** - -```javascript -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示例：** - -```javascript -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."); -}); -``` +# @ohos.security.cryptoFramework (加解密算法库框架) + +为屏蔽底层硬件和算法库，向上提供统一的密码算法库加解密相关接口。 + +> **说明：** +> +> 本模块首批接口从API version 9开始支持。 + +## 导入模块 + +```javascript +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数组。 + + **系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---- | ---------- | ---- | ---- | ------ | +| data | Uint8Array | 是 | 是 | 数据。 | + + +## cryptoFramework.createMac + +createMac(algName : string) : Mac + +生成Mac实例，用于进行消息认证码的计算与操作。
支持的规格详见框架概述“[HMAC消息认证码算法规格](../../security/cryptoFramework-overview.md#hmac消息认证码算法规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定摘要算法，支持算法请参考“[HMAC算法支持范围](../../security/cryptoFramework-overview.md#hmac消息认证码算法规格)”一节 | + +**返回值**： + +| 类型 | 说明 | +| ---- | --------------------------------------- | +| Mac | 返回由输入算法指定生成的[Mac](#mac)对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------ | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + // 参数选择请参考上述算法支持范围 + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +``` + +## Mac + +Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密计算。调用前，需要通过[createMac](#cryptoframeworkcreatemac)构造Mac实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | -------------------- | +| algName | string | 是 | 否 | 代表指定的摘要算法名 | + +### init + +init(key : SymKey, callback : AsyncCallback\) : void; + +使用对称密钥初始化Mac计算 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------ | +| key | [SymKey](#symkey) | 是 | 共享对称密钥 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +var KeyBlob; +var 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\; + +使用对称密钥初始化Mac计算 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| key | [SymKey](#symkey) | 是 | 共享对称密钥 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); + +``` + +### update + +update(input : DataBlob, callback : AsyncCallback\) : void; + +传入消息进行Mac更新计算 + +> **说明：** +> Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| input | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var KeyBlob; +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +var 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; + mac.update(blob, (err2, data) => { + if (err2) { + console.error("[Callback] err: " + err2.code); + } + }); + }); +}); +``` + +### update + +update(input : DataBlob) : Promise\; + +传入消息进行Mac更新计算 + +> **说明：** +> Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| input | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).then(() => { + let blob; + var promiseMacUpdate = mac.update(blob); + return promiseMacUpdate; +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); + +``` + +### doFinal + +doFinal(callback : AsyncCallback\) : void; + +返回Mac的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | -------- | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var KeyBlob; +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +var 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; + 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\ + +返回Mac的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ----------- | +| Promise\<[DataBlob](#datablob)> | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).then(() => { + let blob; + var promiseMacUpdate = mac.update(blob); + return promiseMacUpdate; +}).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; +}).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### getMacLength + +getMacLength() : number + +获取Mac消息认证码的长度（字节数） + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------- | +| number | 返回mac计算结果的字节长度 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).then(() => { + let blob; + var promiseMacUpdate = mac.update(blob); + return promiseMacUpdate; +}).then(() => { + var 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 => { + console.error("[Promise]: error: " + error.message); +}); +``` + +## cryptoFramework.createMd + +createMd(algName : string) : Md + +生成Md实例，用于进行消息摘要的计算与操作。
支持的规格详见框架概述“[MD消息摘要算法规格](../../security/cryptoFramework-overview.md#md消息摘要算法规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定摘要算法，支持算法请参考“[MD算法支持范围](../../security/cryptoFramework-overview.md#md消息摘要算法规格)”一节 | + +**返回值**： + +| 类型 | 说明 | +| ---- | ------------------------------------- | +| Md | 返回由输入算法指定生成的[Md](#md)对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------ | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + // 参数选择请参考上述算法支持范围 + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +``` + +## Md + +Md类，调用Md方法可以进行MD（Message Digest）摘要计算。调用前，需要通过[createMd](#cryptoframeworkcreatemd)构造Md实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | -------------------- | +| algName | string | 是 | 否 | 代表指定的摘要算法名 | + +### update + +update(input : DataBlob, callback : AsyncCallback\) : void; + +传入消息进行Md更新计算 + +> **说明：** +> Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| input | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +md.update(blob, (err,) => { + if (err) { + console.error("[Callback] err: " + err.code); + } +}); +``` + +### update + +update(input : DataBlob) : Promise\; + +传入消息进行Md更新计算 + +> **说明：** +> Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| input | DataBlob | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +var promiseMdUpdate = md.update(blob); +promiseMdUpdate.then(() => { + // do something +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### digest + +digest(callback : AsyncCallback\) : void + +返回Md的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | -------- | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +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\ + +返回Md的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ----------- | +| Promise\<[DataBlob](#datablob)> | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +var promiseMdUpdate = md.update(blob); +promiseMdUpdate.then(() => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; +}).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### getMdLength + +getMdLength() : number + +获取Md消息摘要长度（字节数） + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------ | +| number | 返回md计算结果的字节长度 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +var promiseMdUpdate = md.update(blob); +promiseMdUpdate.then(() => { + var 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 => { + console.error("[Promise]: error: " + error.message); +}); +``` + +## cryptoFramework.createRandom + +createRandom() : Random + +生成Random实例，用于进行随机数的计算与设置种子。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值**： + +| 类型 | 说明 | +| ------ | --------------------------------------------- | +| Random | 返回由输入算法指定生成的[Random](#random)对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------ | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +try { + var rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +``` + +## Random + +Random类，调用Random方法可以进行随机数计算。调用前，需要通过[createRandom](#cryptoframeworkcreaterandom)构造Random实例。 + +### generateRandom + +generateRandom(len : number, callback: AsyncCallback\) : void; + +生成指定长度的随机数 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | -------------------- | +| len | number | 是 | 表示生成随机数的长度 | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var rand; +try { + rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +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\; + +生成指定长度的随机数 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------- | +| len | number | 是 | 表示生成随机数的长度 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ----------- | +| Promise\<[DataBlob](#datablob)> | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var rand; +try { + rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} + +var promiseGenerateRand = rand.generateRandom(12); +promiseGenerateRand.then(randData => { + console.error("[Promise]: rand result: " + randData.data); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### setSeed + +setSeed(seed : DataBlob) : void; + +设置指定的种子 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------- | +| seed | DataBlob | 是 | 设置的种子 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ----------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var rand; +try { + rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} + +rand.generateRandom(12, (err, randData) => { + if (err) { + console.error("[Callback] err: " + err.code); + } else { + console.error("[Callback]: generate random result: " + randData.data); + try { + rand.setSeed(randData); + } catch (error) { + console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); + } + } +}); +``` + +## ParamsSpec + +加解密参数，在进行对称加解密时需要构造其子类对象，并将子类对象传入[init()](#init-2)方法。
适用于需要iv等参数的对称加解密模式（对于无iv等参数的模式如ECB模式，无需构造，在[init()](#init-2)中传入null即可）。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | + +> **说明：** +> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 + +## IvParamsSpec + +加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：
- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节
- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | + +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 + +## GcmParamsSpec + +加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于GCM模式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为12字节 | +| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | +| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。
采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾16字节作为解密时[init()](#init-2)方法的入参[GcmParamsSpec](#gcmparamsspec)中的的authTag | + +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 + +## CcmParamsSpec + +加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CCM模式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为7字节 | +| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | +| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。
采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾12字节作为解密时[init()](#init-2)方法的入参[CcmParamsSpec](#ccmparamsspec)中的authTag | + +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 + +## CryptoMode + +表示加解密操作的枚举。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 值 | 说明 | +| ------------ | ---- | ---------------- | +| ENCRYPT_MODE | 0 | 表示进行加密操作 | +| DECRYPT_MODE | 1 | 表示进行解密操作 | + +## Key + +密钥（父类），在运行密码算法（如加解密）时需要提前生成其子类对象，并传入[Cipher](#cipher)实例的[init()](#init-2)方法。
密钥可以通过密钥生成器来生成。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| format | string | 是 | 否 | 密钥的格式。 | +| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | + +### getEncoded + +getEncoded() : DataBlob + +以同步方法，获取16进制形式的密钥内容。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------ | +| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | + +**示例：** + +```js +import cryptoFramework from "@ohos.security.cryptoFramework" +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 +let encodedKey = key.getEncoded(); +console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); +``` + +## SymKey + +对称密钥，是[Key](#key)的子类，在对称加解密时需要将其对象传入[Cipher](#cipher)实例的[init()](#init-2)方法使用。
对称密钥可以通过对称密钥生成器[SymKeyGenerator](#symkeygenerator)来生成。 + +### clearMem + +clearMem() : void + +以同步方法，将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时，调用本函数，避免内存中密钥数据存留过久。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**示例：** + +```js +import cryptoFramework from "@ohos.security.cryptoFramework" +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 +let encodedKey = key.getEncoded(); +console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出密钥内容 +key.clearMem(); +encodedKey = key.getEncoded(); +console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出全零 +``` + +## PubKey + +公钥，是Key的子类，在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。
公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| format | string | 是 | 否 | 密钥的格式。 | +| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | + + +### getEncoded + +getEncoded() : DataBlob + +以同步方法，获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------ | +| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | + +**示例：** + +```js +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 +console.info("key format:" + key.format); +console.info("key algName:" + key.algName); +var encodedKey = key.getEncoded(); +console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); +``` + +## PriKey + +私钥，是Key的子类，在非对称加解密、签名、密钥协商时需要将其作为输入使用。
私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| format | string | 是 | 否 | 密钥的格式。 | +| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | + +### getEncoded + +getEncoded() : DataBlob + +以同步方法，获取二进制形式的密钥内容。私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------ | +| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | + +**示例：** + +```js +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 +console.info("key format:" + key.format); +console.info("key algName:" + key.algName); +var encodedKey = key.getEncoded(); +console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); +``` + +### clearMem + +clearMem() : void + +以同步方法，将系统底层内存中的的密钥内容清零。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**示例：** + +```js +let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 +key.clearMem(); +``` + +## KeyPair + +非对称密钥对，包含：公钥与私钥。
可以通过非对称密钥生成器AsyKeyGenerator来生成。 + +> **说明：** +> +> KeyPair对象中的pubKey对象和priKey对象，作为KeyPair对象中的一个参数存在，当离开KeyPair对象作用域时，其内部对象可能被析构。
业务方使用时应持有KeyPair对象的引用，而非内部pubKey或priKey对象的引用。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------ | +| priKey | [PriKey](#prikey) | 是 | 否 | 私钥。 | +| pubKey | [PubKey](#pubkey) | 是 | 否 | 公钥。 | + + +## cryptoFramework.createSymKeyGenerator + +createSymKeyGenerator(algName : string) : SymKeyGenerator + +通过指定算法名称的字符串，获取相应的对称密钥生成器实例。
支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 待生成对称密钥生成器的算法名称。
具体取值详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节中的“字符串参数”。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | -------------------------- | +| [SymKeyGenerator](#symkeygenerator) | 返回对称密钥生成器的对象。 | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); +``` + +## SymKeyGenerator + +对称密钥生成器。
在使用该类的方法前，需要先使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)方法构建一个symKeyGenerator实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------------------------ | +| algName | string | 是 | 否 | 对称密钥生成器指定的算法名称。 | + +### generateSymKey + +generateSymKey(callback : AsyncCallback\) : void + +异步获取对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +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\ + +异步获取该对称密钥生成器随机生成的密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------------- | --------------------------------- | +| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symAlgName = 'AES128'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); +symKeyGenerator.generateSymKey() +.then(symKey => { + console.info(`Generate symKey success, algName: ${symKey.algName}`); +}, error => { + console.error(`Generate symKey failed, ${error.code}, ${error.message}`); +}) +``` + +### convertKey + +convertKey(key : DataBlob, callback : AsyncCallback\) : void + +异步根据指定数据生成对称密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | +| key | [DataBlob](#datablob) | 是 | 指定的对称密钥材料。 | +| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function genKeyMaterialBlob() { + 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\ + +异步根据指定数据生成对称密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------------- | ---- | -------------------- | +| key | [DataBlob](#datablob) | 是 | 指定的密钥材料数据。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------- | --------------------------------- | +| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function genKeyMaterialBlob() { + 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 => { + console.error(`Convert symKey failed, ${error.code}, ${error.message}`); +}) +``` + +## cryptoFramework.createAsyKeyGenerator + +createAsyKeyGenerator(algName : string) : AsyKeyGenerator + +通过指定算法名称的字符串，获取相应的非对称密钥生成器实例。
支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | -------------------------------- | +| algName | string | 是 | 待生成对称密钥生成器的算法名称。 | + +**返回值：** + +| 类型 | 说明 | +| --------------- | ---------------------------- | +| [AsyKeyGenerator](#asykeygenerator) | 返回非对称密钥生成器的对象。 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); +``` + +## AsyKeyGenerator + +非对称密钥生成器。在使用该类的方法前，需要先使用createAsyKeyGenerator()方法构建一个AsyKeyGenerator实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | -------------------------------- | +| algName | string | 是 | 否 | 非对称密钥生成器指定的算法名称。 | + +### generateKeyPair + +generateKeyPair(callback : AsyncCallback\) : void; + +异步获取非对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------ | +| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +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\ + +异步获取该非对称密钥生成器随机生成的密钥，通过Promise获取结果。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------- | +| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +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\) : void + +异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。详情请看下方**密钥转换说明** + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------ | +| pubKey | [DataBlob](#datablob) | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null。 | +| priKey | [DataBlob](#datablob) | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null。 | +| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +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\ + +异步获取指定数据生成非对称密钥，通过Promise获取结果。详情请看下方**密钥转换说明** + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------------- | +| pubKey | DataBlob | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null | +| priKey | DataBlob | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------- | +| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +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](#cipher)实例。
支持的规格详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------ | ---- | ------------------------------------------------------------ | +| transformation | string | 是 | 待生成Cipher的算法名称（含密钥长度）、加密模式以及填充方法的组合。
具体取值详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节中的“字符串参数”。 | + +> **说明：** +> 1. 目前对称加解密中，PKCS5和PKCS7的实现相同，其padding长度和分组长度保持一致（即PKCS5和PKCS7在3DES中均按照8字节填充，在AES中均按照16字节填充），另有NoPadding表示不填充。
开发者需要自行了解密码学不同分组模式的差异，以便选择合适的参数规格。例如选择ECB和CBC模式时，建议启用填充，否则必须确保明文长度是分组大小的整数倍；选择其他模式时，可以不启用填充，此时密文长度和明文长度一致（即可能不是分组大小的整数倍）。 +> 2. 使用RSA进行非对称加解密时，必须创建两个Cipher对象分别进行加密和解密操作，而不能对同一个Cipher对象进行加解密。对称加解密没有此要求（即只要算法规格一样，可以对同一个Cipher对象进行加解密操作）。 + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------ | +| [Cipher](#cipher) | 返回加解密生成器的对象。 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let cipherAlgName = '3DES192|ECB|PKCS7'; +var cipher; +try { + cipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${cipher.algName}`); +} catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); +} +``` + +## Cipher + +提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。
完整的加解密流程示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 + +一次完整的加/解密流程在对称加密和非对称加密中略有不同： + +- 对称加解密：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 + +初始化加解密的[cipher](#cipher)对象，通过注册回调函数获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | +| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | +| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | +| callback | AsyncCallback\ | 是 | 回调函数。当初始化成功，err为undefined，否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error.| + +**示例：** + +```js +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\ + +初始化加解密的cipher对象，通过Promise获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------- | ---- | ------------------------------------------------------------ | +| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | +| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | +| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | -------------------------------------- | +| Promise\ | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error.| + +**示例：** + +```js +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\) : void + +分段更新加密或者解密数据操作，通过注册回调函数获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 + +> **说明：** +> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） +> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，采用多次update的方式传入数据。
AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 +> 3. RSA非对称加解密不支持update操作。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当更新加/解密数据成功，err为undefined，data为此次更新的加/解密结果DataBlob；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +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\ + +分段更新加密或者解密数据操作，通过通过Promise获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 + +> **说明：** +> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） +> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，可以采用多次update的方式传入数据。
AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 +> 3. RSA非对称加解密不支持update操作。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------------- | ---- | -------------------- | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------- | ------------------------------------------------ | +| Promise\<[DataBlob](#datablob)> | Promise对象，返回此次更新的加/解密结果DataBlob。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +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\) : void + +（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： + +- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 +- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 + +（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过注册回调函数获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 + +> **说明：** +> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 +> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 +> 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 +> 4. RSA非对称加解密时多次doFinal操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。在对称加解密中允许为null，但不允许传入{data : Uint8Array(空) }。 | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当最终加/解密数据成功，err为undefined，data为剩余数据的加/解密结果DataBlob；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ----------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +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\ + +（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过Promise获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： + +- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 +- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 + +（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过Promise获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 + +> **说明：** +> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 +> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 +> 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 +> 4. RSA非对称加解密时多次doFinal操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------------- | ---- | -------------------- | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data参数允许为null，但不允许传入{data : Uint8Array(空) } | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------- | ------------------------------------------------ | +| Promise\<[DataBlob](#datablob)> | Promise对象，返回剩余数据的加/解密结果DataBlob。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +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完整示例：** + +```javascript +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完整示例：** + +```javascript +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); +}); +``` + +> **说明：** +> 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 + +## cryptoFramework.createSign + +createSign(algName : string) : Sign + +Sign实例生成。
支持的规格详见框架概述“[签名验签规格](../../security/cryptoFramework-overview.md#签名验签规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | + +**返回值**： + +| 类型 | 说明 | +| ---- | -------------------------------- | +| Sign | 返回由输入算法指定生成的Sign对象 | + +**示例：** + +```javascript +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 + +使用私钥初始化Sign对象，Callback形式，Sign类暂不支持重复init + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------------- | +| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### init + +init(priKey : PriKey) : Promise\ + +使用私钥初始化Sign对象，Promise形式，Sign类暂不支持重复init + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------- | +| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob, callback : AsyncCallback\) : void + +追加待签名数据，callback方式 + +> **说明：** +> Sign多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob) : Promise\; + +追加待签名数据，promise方式 + +> **说明：** +> Sign多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### sign + +sign(data : DataBlob, callback : AsyncCallback\) : void + +对数据进行签名，返回签名结果，callback方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | +| callback | AsyncCallback\<[DataBlob](#datablob) > | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### sign + +sign(data : DataBlob) : Promise\ + +对数据进行签名，返回签名结果，promise方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**callback示例：** + +```javascript +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示例：** + +```javascript +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实例生成。
支持的规格详见框架概述“[签名验签规格](../../security/cryptoFramework-overview.md#签名验签规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | + +**返回值**： + +| 类型 | 说明 | +| ------ | ---------------------------------- | +| Verify | 返回由输入算法指定生成的Verify对象 | + +**示例：** + +```javascript +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 + +传入公钥初始化Verify对象，Callback形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------------------------- | +| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### init + +init(pubKey : PubKey) : Promise\ + +传入公钥初始化Verify对象，Promise形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------------------- | +| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob, callback : AsyncCallback\) : void + +追加待验签数据，callback方式 + +> **说明：** +> Verify多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob) : Promise\; + +追加待验签数据，promise方式 + +> **说明：** +> Verify多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### verify + +verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void + +对数据进行验签，返回验签结果，callback方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | +| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### verify + +verify(data : DataBlob, signatureData : DataBlob) : Promise\ + +对数据进行验签，返回验签结果，promise方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | +| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ---------------------------- | +| Promise\ | 异步返回值，代表验签是否通过 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**callback示例：** + +```javascript +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示例：** + +```javascript +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实例生成。
支持的规格详见框架概述“[密钥协商规格](../../security/cryptoFramework-overview.md#密钥协商规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------- | +| algName | string | 是 | 指定密钥协商算法：目前仅支持ECC | + +**返回值**： + +| 类型 | 说明 | +| ------------ | ---------------------------------------- | +| KeyAgreement | 返回由输入算法指定生成的KeyAgreement对象 | + +**示例：** + +```javascript +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\) : void + +基于传入的私钥与公钥进行密钥协商，返回共享秘密，Callback形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | ---------------------- | +| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | +| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 异步接受共享秘密的回调 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### generateSecret + +generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\ + +基于传入的私钥与公钥进行密钥协商，返回共享秘密，Promise形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------- | +| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | +| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | -------- | +| Promise\<[DataBlob](#datablob)> | 共享秘密 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**callback示例：** + +```javascript +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示例：** + +```javascript +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."); +}); +``` diff --git a/zh-cn/application-dev/security/cryptoFramework-guidelines.md b/zh-cn/application-dev/security/cryptoFramework-guidelines.md index 0c697abe1d..934a986b4b 100644 --- a/zh-cn/application-dev/security/cryptoFramework-guidelines.md +++ b/zh-cn/application-dev/security/cryptoFramework-guidelines.md @@ -1,1113 +1,1606 @@ -# 加解密算法库框架开发指导 - -> **说明** -> -> 本开发指导基于API version 9，OH SDK版本3.2.7以上，适用于JS语言开发 - -## 使用密钥对象生成与转换操作 - -**场景说明** - -使用密钥生成操作中，典型的场景有： - -1. 随机生成算法库密钥对象。该对象可用于后续的加解密等操作。 -2. 根据指定数据生成算法库密钥对象（也就是将外部或存储的二进制数据转换为算法库的密钥对象）。该对象可用于后续的加解密等操作。 -3. 获取算法库密钥对象的二进制数据，用于存储或传输。 -> **说明**：密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -以上场景涉及的常用接口如下表所示： - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|根据algName设置的非对称密钥规格，创建非对称密钥生成器对象| -|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|根据algName设置的对称密钥规格，创建对称密钥生成器对象| -|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\) : void|使用callback方式，随机生成非对称密钥对象KeyPair| -|AsyKeyGenerator|generateKeyPair() : Promise\|使用Promise方式，随机生成非对称密钥对象KeyPair| -|SymKeyGenerator|generateSymKey(callback : AsyncCallback\) : void|使用callback方式，随机生成对称密钥对象SymKey| -|SymKeyGenerator|generateSymKey() : Promise\|使用Promise方式，随机生成对称密钥对象SymKey| -| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void | 使用callback方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | -| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\ | 使用Promise方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | -| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\) : void| 使用callback方式，根据指定的二进制数据，生成对称密钥对象SymKey | -| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\| 使用Promise方式，根据指定的二进制数据，生成对称密钥对象SymKey | -| Key | getEncoded() : DataBlob; | 获取Key密钥对象的二进制数据（Key的子类实例包括对称密钥SymKey、公钥PubKey、私钥PriKey） | - -**开发步骤** - -示例1：随机生成非对称密钥KeyPair，并获得二进制数据（场景1、3） - -1. 创建非对称密钥生成器； -2. 通过非对称密钥生成器随机生成非对称密钥； -3. 获取密钥对象的二进制数据； - -以使用Promise方式随机生成RSA密钥（1024位，素数个数为2）为例： - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function generateAsyKey() { - // 创建非对称密钥生成器 - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - // 通过非对称密钥生成器，随机生成非对称密钥 - let keyGenPromise = rsaGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - let pubKey = globalKeyPair.pubKey; - let priKey = globalKeyPair.priKey; - // 获取非对称密钥的二进制数据 - pkBlob = pubKey.getEncoded(); - skBlob = priKey.getEncoded(); - AlertDialog.show({ message : "pk bin data" + pkBlob.data} ); - AlertDialog.show({ message : "sk bin data" + skBlob.data} ); - }) -} -``` - -示例2：随机生成对称密钥SymKey，并获得二进制数据（场景1、3） - -1. 创建对称密钥生成器； -2. 通过对称密钥生成器随机生成对称密钥； -3. 获取算法库密钥对象的二进制数据； - -以使用Promise方式随机生成AES密钥（256位）为例： - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -function testGenerateAesKey() { - // 创建对称密钥生成器 - let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256'); - // 通过密钥生成器随机生成对称密钥 - let promiseSymKey = symKeyGenerator.generateSymKey(); - promiseSymKey.then( key => { - // 获取对称密钥的二进制数据，输出长度为256bit的字节流 - let encodedKey = key.getEncoded(); - console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); - }) -} -``` - -示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2） - -1. 获取RSA公钥或私钥二进制数据，公钥需满足ASN.1语法、X.509规范、DER编码格式，私钥需满足ASN.1语法、PKCS#8规范、DER编码格式。 -2. 创建AsyKeyGenerator对象，调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function convertAsyKey() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024"); - let pkval = new Uint8Array([48,129,159,48,13,6,9,42,134,72,134,247,13,1,1,1,5,0,3,129,141,0,48,129,137,2,129,129,0,174,203,113,83,113,3,143,213,194,79,91,9,51,142,87,45,97,65,136,24,166,35,5,179,42,47,212,79,111,74,134,120,73,67,21,19,235,80,46,152,209,133,232,87,192,140,18,206,27,106,106,169,106,46,135,111,118,32,129,27,89,255,183,116,247,38,12,7,238,77,151,167,6,102,153,126,66,28,253,253,216,64,20,138,117,72,15,216,178,37,208,179,63,204,39,94,244,170,48,190,21,11,73,169,156,104,193,3,17,100,28,60,50,92,235,218,57,73,119,19,101,164,192,161,197,106,105,73,2,3,1,0,1]); - let pkBlob = {data : pkval}; - rsaGenerator.convertKey(pkBlob, null, function(err, keyPair) { - if (keyPair == null) { - AlertDialog.show({message : "Convert keypair fail"}); - } - AlertDialog.show({message : "Convert KeyPair success"}); - }) -} -``` - -**说明** - - 当前convertKey操作，公钥只支持转换满足X.509规范的DER格式，私钥只支持PKCS#8规范的DER格式； - -示例4：根据指定的ECC非对称密钥二进制数据，生成KeyPair对象（场景2、3） - -1. 获取ECC二进制密钥数据，封装成DataBlob对象。 -2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 - -```javascript -function convertEccAsyKey() { - let pubKeyArray = new Uint8Array([4,196,55,233,100,227,224,38,38,5,128,81,53,112,129,7,59,189,116,105,182,87,190,85,31,248,172,116,213,7,206,85,190,65,169,193,138,173,232,187,74,54,78,251,29,131,192,223,251,227,170,138,80,7,98,193,216,168,235,114,255,188,70,134,104]); - let priKeyArray = new Uint8Array([255,70,89,220,189,19,41,157,175,173,83,60,74,216,195,96,24,181,231,23,112,247,150,126,15,155,24,79,33,97,31,225]); - let pubKeyBlob = { data: pubKeyArray }; - let priKeyBlob = { data: priKeyArray }; - let generator = cryptoFrameWork.createAsyKeyGenerator("ECC256"); - generator.convertKey(pubKeyBlob, priKeyBlob, (error, data) => { - if (error) { - AlertDialog.show({message : "Convert keypair fail"}); - } - AlertDialog.show({message : "Convert KeyPair success"}); - }) -} -``` - -示例5：根据指定的对称密钥二进制数据，生成SymKey对象（场景2、3） - -1. 创建对称密钥生成器； -2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象； -3. 获取算法库密钥对象的二进制数据； - -以使用callback方式生成3DES密钥（3DES密钥只能为192位）为例： - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -function genKeyMaterialBlob() { - let arr = [ - 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, - 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, - 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) - let keyMaterial = new Uint8Array(arr); - return {data : keyMaterial}; -} - -function testConvertAesKey() { - // 生成对称密钥生成器 - let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); - // 根据用户指定的数据，生成对称密钥 - let keyMaterialBlob = genKeyMaterialBlob(); - try { - symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { - if (error) { // 业务逻辑执行错误通过callback的第一个参数返回错误信息 - console.error(`convertKey error, ${error.code}, ${error.message}`); - return; - } - console.info(`key algName: ${key.algName}`); - console.info(`key format: ${key.format}`); - let encodedKey = key.getEncoded(); // 获取对称密钥的二进制数据，输出长度为192bit的字节流 - console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); - }) - } catch (error) { // 参数检查的错误以同步的方式立即抛出异常 - console.error(`convertKey failed, ${error.code}, ${error.message}`); - return; - } -} -``` - -## 使用加解密操作 - -**场景说明** - -在数据存储或传输场景中，可以使用加解密操作用于保证数据的机密性，防止敏感数据泄露。使用加解密操作中，典型的场景有： -1. 使用对称密钥的加解密操作 -2. 使用非对称密钥的加解密操作 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -以上场景设计的常用接口如下表所示： - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createCipher(transformation : string) : Cipher|根据transformation设置的算法参数创建Cipher对象| -|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Cipher对象| -|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\|使用Promise方式设置密钥并初始化Cipher对象| -|Cipher|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加加解密数据| -|Cipher|update(data : DataBlob) : Promise\|使用Promise方式添加加解密数据| -|Cipher|doFinal(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式结束对所有数据的加解密| -|Cipher|doFinal(data : DataBlob) : Promise\|使用Promise方式结束对所有数据的加解密| - -**开发步骤** - -示例1：使用对称密钥的加解密操作 - -1. 创建对称密钥生成器。 -2. 通过密钥生成器生成对称密钥。 -3. 创建加解密生成器。 -4. 通过加解密生成器加密或解密数据。 - -以AES GCM以Promise方式加解密为例： - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -var globalCipher; -var globalGcmParams; -var globalKey; -var globalCipherText; - -function genGcmParamsSpec() { - let arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0 , 0, 0]; // 12 bytes - let dataIv = new Uint8Array(arr); - let ivBlob = {data : dataIv}; - - arr = [0, 0, 0, 0 , 0, 0, 0, 0]; // 8 bytes - let dataAad = new Uint8Array(arr); - let aadBlob = {data : dataAad}; - - arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0]; // 16 bytes - let dataTag = new Uint8Array(arr); - let tagBlob = {data : dataTag}; - let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; - return gcmParamsSpec; -} - -// 可理解的字符串转成字节流 -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -// 字节流转成可理解的字符串 -function uint8ArrayToString(array) { - let arrayString = ''; - for (let i = 0; i < array.length; i++) { - arrayString += String.fromCharCode(array[i]); - } - return arrayString; -} - -function genKeyMaterialBlob() { - 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}; -} - - -// AES GCM模式示例，自动生成密钥（promise写法） -function testAesGcm() { - return new Promise((resolve, reject) => { - setTimeout(() => { - resolve('testAesGcm'); - }, 10) - }).then(() => { - // 生成对称密钥生成器 - let symAlgName = 'AES128'; - let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); - if (symKeyGenerator == null) { - console.error('createSymKeyGenerator failed'); - return; - } - console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); - // 通过密钥生成器随机生成128位长度的对称密钥 - let promiseSymKey = symKeyGenerator.generateSymKey(); - // 构造参数 - globalGcmParams = genGcmParamsSpec(); - - // 生成加解密生成器 - let cipherAlgName = 'AES128|GCM|PKCS7'; - try { - globalCipher = cryptoFramework.createCipher(cipherAlgName); - console.info(`cipher algName: ${globalCipher.algName}`); - } catch (error) { - console.error(`createCipher failed, ${error.code}, ${error.message}`); - return; - } - return promiseSymKey; - }).then(key => { - let encodedKey = key.getEncoded(); - console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); - globalKey = key; - return key; - }).then(key => { - // 初始化加解密操作环境:开始加密 - let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; - let promiseInit = globalCipher.init(mode, key, globalGcmParams); // init - return promiseInit; - }).then(() => { - let plainText = {data : stringToUint8Array('this is test!')}; - let promiseUpdate = globalCipher.update(plainText); // update - return promiseUpdate; - }).then(updateOutput => { - globalCipherText = updateOutput; - let promiseFinal = globalCipher.doFinal(null); // doFinal - return promiseFinal; - }).then(authTag => { - // 获取加密后的认证信息 - globalGcmParams.authTag = authTag; - return; - }).then(() => { - // 初始化加解密操作环境:开始解密 - let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; - let promiseInit = globalCipher.init(mode, globalKey, globalGcmParams); // init - return promiseInit; - }).then(() => { - let promiseUpdate = globalCipher.update(globalCipherText); // update - return promiseUpdate; - }).then(updateOutput => { - console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); - let promiseFinal = globalCipher.doFinal(null); // doFinal - return promiseFinal; - }).then(finalOutput => { - if (finalOutput == null) { - console.info('GCM finalOutput is null'); - } - }).catch(error => { - console.error(`catch error, ${error.code}, ${error.message}`); - }) -} -``` - -以3DES ECB以callback方式加解密（采用已有数据生成密钥）为例： - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -var globalCipher; -var globalGcmParams; -var globalKey; -var globalCipherText; - -// 可理解的字符串转成字节流 -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -// 字节流转成可理解的字符串 -function uint8ArrayToString(array) { - let arrayString = ''; - for (let i = 0; i < array.length; i++) { - arrayString += String.fromCharCode(array[i]); - } - return arrayString; -} - -function genKeyMaterialBlob() { - 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}; -} - -// 3DES ECB模式示例，采用已有数据生成密钥（callback写法） -function test3DesEcb() { - // 生成对称密钥生成器 - let symAlgName = '3DES192'; - let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); - if (symKeyGenerator == null) { - console.error('createSymKeyGenerator failed'); - return; - } - console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); - - // 生成加解密生成器 - let cipherAlgName = '3DES192|ECB|PKCS7'; - try { - globalCipher = cryptoFramework.createCipher(cipherAlgName); - console.info(`cipher algName: ${globalCipher.algName}`); - } catch (error) { - console.error(`createCipher failed, ${error.code}, ${error.message}`); - return; - } - - // 根据指定的数据，生成对称密钥 - let keyMaterialBlob = genKeyMaterialBlob(); - try { - symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { - if (error) { - console.error(`convertKey error, ${error.code}, ${error.message}`); - return; - } - console.info(`key algName: ${key.algName}`); - console.info(`key format: ${key.format}`); - let encodedKey = key.getEncoded(); - console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); - globalKey = key; - - // 初始化加解密操作环境:开始加密 - let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; - // init - globalCipher.init(mode, key, null, (err, ) => { - let plainText = {data : stringToUint8Array('this is test!')}; - // update - globalCipher.update(plainText, (err, updateOutput) => { - globalCipherText = updateOutput; - //doFinal - globalCipher.doFinal(null, (err, finalOutput) => { - if (error) { - console.error(`doFinal error, ${error.code}, ${error.message}`); - return; - } - if (finalOutput != null) { - globalCipherText = Array.from(globalCipherText.data); - finalOutput = Array.from(finalOutput.data); - globalCipherText = globalCipherText.concat(finalOutput); - globalCipherText = new Uint8Array(globalCipherText); - globalCipherText = {data : globalCipherText}; - } - // 初始化加解密操作环境:开始解密 - let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; - // init - globalCipher.init(mode, globalKey, null, (err, ) => { - // update - globalCipher.update(globalCipherText, (err, updateOutput) => { - console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); - // doFinal - globalCipher.doFinal(null, (error, finalOutput) => { - if (finalOutput != null) { - console.info("decrypt plainText:" + uint8ArrayToString(finalOutput.data)); - } - }) - }) - }) - }) - }) - }) - }) - } catch (error) { - console.error(`convertKey failed, ${error.code}, ${error.message}`); - return; - } -} -``` - -示例2：使用非对称密钥的加解密操作 - -1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 -2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式。 -3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文。 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let plan = "This is cipher test."; - -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; -} - -function encryptMessageProMise() { - 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); - }).then(() => { - let input = { data : stringToUint8Array(plan) }; - return cipher.doFinal(input); - }).then(dataBlob => { - console.info("EncryptOutPut is " + dataBlob.data); - }); -} - -function encryptMessageCallback() { - 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 input = {data : stringToUint8Array(plan) }; - cipher.doFinal(input, function (err, data) { - console.info("EncryptOutPut is " + data.data); - }) - }) - }) -} -``` - -**说明** - -1. 使用RSA加解密时，Cipher对象不可重复调用init方法初始化，在创建了一个加密Cipher对象后，如果要进行解密，则需要重新创建另一个Cipher对象执行解密操作。 -2. RSA加密有长度限制，允许加密明文的最大长度见[加解密算法库框架概述](cryptoFramework-overview.md)中的基本概念章节。 -3. RSA解密每次允许解密的密文长度为，RSA密钥的位数/8。 - -## 使用签名验签操作 - -**场景说明** - -当需要判断接收的数据是否被篡改且是否为指定对象发送的数据时，可以使用签名验签操作。使用签名验签操作中，典型的场景有： -1. 使用RSA签名验签操作 -2. 使用ECC签名验签操作 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createSign(algName : string) : Sign|根据String设置的参数创建Sign对象| -|Sign|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Sign对象| -|Sign|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Sign对象| -|Sign|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加签名数据| -|Sign|update(data : DataBlob) : Promise\|用Promise方式添加签名数据| -|Sign|sign(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式签名所有数据| -|Sign|sign(data : DataBlob) : Promise\|使用Promise方式签名所有数据| -|cryptoFramework|function createVerify(algName : string) : Verify|根据String设置的参数创建Verify对象| -|Verify|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Verify对象| -|Verify|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Verify对象| -|Verify|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加验签数据| -|Verify|update(data : DataBlob) : Promise\|用Promise方式添加验签数据| -|Verify|verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void|使用callback方式验签所有数据| -|Verify|verify(data : DataBlob, signatureData : DataBlob) : Promise\|使用Promise方式验签所有数据| - -**开发步骤** - -示例1：使用RSA签名验签操作 -1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 -2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 -3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用sign接口生成数据的签名。 -4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 -5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。 -```javascript -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"; -let plan2 = "This is Sign test plan1"; -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); - }).then(() => { - return signer.sign(input2); - }).then(dataBlob => { - SignMessageBlob = dataBlob; - console.info("sign output is " + SignMessageBlob.data); - }); -} - -function verifyMessagePromise() { - let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); - let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); - verifyInitPromise.then(() => { - return verifyer.update(input1); - }).then(() => { - return verifyer.verify(input2, SignMessageBlob); - }).then(res => { - console.log("Verify result is " + res); - }); -} - -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) { - signer.sign(input2, function (err, data) { - SignMessageBlob = data; - console.info("sign output is " + SignMessageBlob.data); - }); - }); - }); - }); -} - -function verifyMessageCallback() { - let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); - 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); - }); - }); - }) -} -``` - -示例2：使用ECDSA操作 -1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 -2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 -3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用doFinal接口生成数据的签名。 -4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 -5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用doFinal接口传入签名进行验签。 - -```javascript -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"; -let plan2 = "This is Sign test plan1"; -let input1 = { data : stringToUint8Array(plan1) }; -let input2 = { data : stringToUint8Array(plan2) }; - -function signMessagePromise() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let signer = cryptoFramework.createSign("ECC256|SHA256"); - let keyGenPromise = eccGenerator.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); - }); -} - -function verifyMessagePromise() { - let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); - let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); - verifyInitPromise.then(() => { - return verifyer.update(input1); - }).then(() => { - return verifyer.verify(input2, SignMessageBlob); - }).then(res => { - console.log("Verify result is " + res); - }); -} - -function signMessageCallback() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let signer = cryptoFramework.createSign("ECC256|SHA256"); - eccGenerator.generateKeyPair(function (err, keyPair) { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - signer.init(priKey, function (err, data) { - signer.update(input1, function (err, data) { - signer.sign(input2, function (err, data) { - SignMessageBlob = data; - console.info("sign output is " + SignMessageBlob.data); - }); - }); - }); - }); -} - -function verifyMessageCallback() { - let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); - 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); - }); - }); - }) -} -``` - -## 使用摘要操作 - -**场景说明** - -用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） - -使用摘要操作的主要场景为： - -用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -| 实例名 | 接口名 | 描述 | -| --------------- | ------------------------------------------------------------ | -------------------------------------------------- | -| cryptoFramework | function createMd(algName : string) : Md; | 指定摘要算法，生成摘要操作实例Md | -| Md | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受用户输入数据，通过Callback的方式，异步更新摘要 | -| Md | update(input : DataBlob) : Promise\; | 接受用户输入数据，通过Promise的方式，异步更新摘要 | -| Md | digest(callback : AsyncCallback\) : void; | 通过Callback的方式，返回结果 | -| Md | digest() : Promise\; | 通过Promise的方式，返回结果 | -| Md | getMdLength() : number; | 获取摘要的长度（由指定的摘要算法决定） | -| Md | readonly algName : string; | 获取当前设置的摘要算法名 | - -**开发步骤** - -1. 设置算法，通过接口`createMd`生成摘要操作实例 -2. 接受用户数据，通过接口`update`，更新摘要，此步骤可重复 -3. 通过接口`digest`，返回摘要计算结果 -4. 获取当前摘要算法名与摘要计算长度 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -// turn string into uint8Arr -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -// generate dataBlob with given length -function GenDataBlob(dataBlobLen) { - var dataBlob; - if (dataBlobLen == 12) { - dataBlob = {data: stringToUint8Array("my test data")}; - } else { - console.error("GenDataBlob: dataBlobLen is invalid"); - dataBlob = {data: stringToUint8Array("my test data")}; - } - return dataBlob; -} - -// md with promise async -function doMdByPromise(algName) { - var md; - try { - md = cryptoFramework.createMd(algName); - } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); - } - console.error("[Promise]: Md algName is: " + md.algName); - var promiseMdUpdate = md.update(GenDataBlob(12)); - promiseMdUpdate.then(() => { - var PromiseMdDigest = md.digest(); - return PromiseMdDigest; - }).then(mdOutput => { - console.error("[Promise]: MD result: " + mdOutput.data); - var mdLen = md.getMdLength(); - console.error("[Promise]: MD len: " + mdLen); - }).catch(error => { - console.error("[Promise]: error: " + error.message); - }); -} - -// md with callback async -function doMdByCallback(algName) { - var md; - try { - md = cryptoFramework.createMd(algName); - } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); - } - console.error("[Callback]: Md algName is: " + md.algName); - md.update(GenDataBlob(12), (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.data); - var mdLen = md.getMdLength(); - console.error("[Callback]: MD len: " + mdLen); - } - }); - }); -} -``` - -## 使用密钥协商操作 - -**场景说明** - -使用密钥协商操作中，典型的场景有： - -通信双方可以在一个公开的信道上通过相互传送一些消息，共同建立一个安全的共享秘密密钥。 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createKeyAgreement(algName : string) : KeyAgreement|根据String设置的参数创建KeyAgreement对象| -|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void|使用callback方式进行密钥协商| -|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\|使用Promise方式进行密钥协商| - -**开发步骤** - -1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 -2. 基于ECC密钥的私钥及公钥执行ECDH操作。 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let globalKeyPair; - -function ecdhPromise() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); - let keyGenPromise = eccGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - return eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey); - }).then((secret) => { - console.info("ecdh output is " + secret.data); - }).catch((error) => { - console.error("ecdh error."); - }); -} - -function ecdhCallback() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); - eccGenerator.generateKeyPair(function (err, keyPair) { - globalKeyPair = keyPair; - eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey, function (err, secret) { - if (err) { - console.error("ecdh error."); - return; - } - console.info("ecdh output is " + secret.data); - }); - }); -} -``` - -## 使用消息认证码操作 - -**场景说明** - -消息认证码操作主要应用于身份认证的场景： - -Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为 - -用户指定摘要算法（如SHA256）生成消息认证码Mac实例，输入对称密钥初始化Mac，并传入单段或多段需要摘要的信息，进行消息认证码计算，并获取消息认证码计算结果，在指定算法后可获取当前算法名与消息认证码计算长度（字节）。 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -| 实例名 | 接口名 | 描述 | -| --------------- | ------------------------------------------------------------ | --------------------------------------------------- | -| cryptoFramework | function createMac(algName : string) : Mac; | 指定摘要算法，生成消息认证码实例Mac | -| Mac | init(key : SymKey, callback : AsyncCallback\) : void; | 接收输入对称密钥，通过Callback的方式，异步初始化MAC | -| Mac | init(key : SymKey) : Promise\; | 接收输入对称密钥，通过Promise的方式，异步初始化MAC | -| Mac | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受输入数据，通过Callback的方式，异步更新MAC | -| Mac | update(input : DataBlob) : Promise\; | 接受输入数据，通过Promise的方式，异步更新MAC | -| Mac | doFinal(callback : AsyncCallback\) : void; | 通过Callback的方式，返回MAC计算结果 | -| Mac | doFinal() : Promise\; | 通过Promise的方式，返回MAC计算结果 | -| Mac | getMacLength() : number; | 获取MAC的长度（由指定的摘要算法决定） | -| Mac | readonly algName : string; | 获取当前设置的摘要算法名 | - -**开发步骤** - -1. 设置算法，通过接口`createMac`生成消息认证码操作实例 -2. 接受输入对称密钥，通过接口`init`，初始化Mac -3. 接受数据，通过接口`update`，更新Mac，此步骤可重复 -4. 通过接口`doFinal`，返回Mac计算结果 -5. 获取当前摘要算法名与Mac计算长度 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -// turn string into uint8Arr -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -// generate blob with this func -function GenDataBlob(dataBlobLen) { - var dataBlob; - if (dataBlobLen == 12) { - dataBlob = {data: stringToUint8Array("my test data")}; - } else { - console.error("GenDataBlob: dataBlobLen is invalid"); - dataBlob = {data: stringToUint8Array("my test data")}; - } - return dataBlob; -} - -// process by promise -function doHmacByPromise(algName) { - var mac; - try { - mac = cryptoFramework.createMac(algName); - } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); - } - console.error("[Promise]: Mac algName is: " + mac.algName); - var KeyBlob = { - data : stringToUint8Array("12345678abcdefgh") - } - var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); - var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); - promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; - }).then(() => { - var promiseMacUpdate = mac.update(GenDataBlob(12)); - return promiseMacUpdate; - }).then(() => { - var PromiseMacDoFinal = mac.doFinal(); - return PromiseMacDoFinal; - }).then(macOutput => { - console.error("[Promise]: HMAC result: " + macOutput.data); - var macLen = mac.getMacLength(); - console.error("[Promise]: MAC len: " + macLen); - }).catch(error => { - console.error("[Promise]: error: " + error.message); - }); -} - -// process by callback -function doHmacByCallback(algName) { - var mac; - try { - mac = cryptoFramework.createMac(algName); - } catch (error) { - AlertDialog.show({message: "[Callback]: error code: " + error.code + ", message is: " + error.message}); - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); - } - var KeyBlob = { - data : stringToUint8Array("12345678abcdefgh") - } - var 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); - } - mac.update(GenDataBlob(12), (err2, ) => { - if (err2) { - console.error("[Callback]: err: " + err2.code); - } - mac.doFinal((err3, macOutput) => { - if (err3) { - console.error("[Callback]: err: " + err3.code); - } else { - console.error("[Callback]: HMAC result: " + macOutput.data); - var macLen = mac.getMacLength(); - console.error("[Callback]: MAC len: " + macLen); - } - }); - }); - }); - }); -} -``` - - - -## 使用随机数操作 - -**场景说明** - -使用随机数操作的主要场景为： - -- 用户生成随机数Random实例，输入随机数生成的长度（字节），生成指定长度的随机数。 -- 用户使用生成的随机数作为参数，进行种子设置。 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -| 实例名 | 接口名 | 描述 | -| --------------- | ------------------------------------------------------------ | ---------------------------------------------- | -| cryptoFramework | function createRandom() : Random; | 生成随机数Random实例 | -| Random | generateRandom(len : number, callback: AsyncCallback\) : void; | 接受输入长度，通过Callback，异步生成随机数 | -| Random | generateRandom(len : number) : Promise\; | 接受输入长度，通过Promise，异步生成随机数 | -| Random | setSeed(seed : DataBlob) : void; | 接受输入Blob，设置种子 | - -**开发步骤** - -1. 通过接口`createRandom`生成随机数操作实例 -2. 接受输入长度，通过接口`generateRandom`，生成指定长度的随机数 -3. 接受DataBlob数据，通过接口`setSeed`，为随机数生成池设置种子 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -// process by promise -function doRandByPromise(len) { - var rand; - try { - rand = cryptoFramework.createRandom(); - } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); - } - var promiseGenerateRand = rand.generateRandom(len); - promiseGenerateRand.then(randData => { - console.error("[Promise]: rand result: " + randData.data); - try { - rand.setSeed(randData); - } catch (error) { - console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); - } - }).catch(error => { - console.error("[Promise]: error: " + error.message); - }); -} - -// process by callback -function doRandByCallback(len) { - var rand; - try { - rand = cryptoFramework.createRandom(); - } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); - } - rand.generateRandom(len, (err, randData) => { - if (err) { - console.error("[Callback]: err: " + err.code); - } else { - console.error("[Callback]: generate random result: " + randData.data); - try { - rand.setSeed(randData); - } catch (error) { - console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); - } - } - }); -} -``` +# 加解密算法库框架开发指导 + +> **说明** +> +> 本开发指导基于API version 9，OH SDK版本3.2.7以上，适用于JS语言开发 + +## 使用密钥对象生成与转换操作 + +**场景说明** + +使用密钥生成操作中，典型的场景有： + +1. 随机生成算法库密钥对象。该对象可用于后续的加解密等操作。 +2. 根据指定数据生成算法库密钥对象（也就是将外部或存储的二进制数据转换为算法库的密钥对象）。该对象可用于后续的加解密等操作。 +3. 获取算法库密钥对象的二进制数据，用于存储或传输。 +> **说明**：密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +以上场景涉及的常用接口如下表所示： + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|根据algName设置的非对称密钥规格，创建非对称密钥生成器对象| +|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|根据algName设置的对称密钥规格，创建对称密钥生成器对象| +|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\) : void|使用callback方式，随机生成非对称密钥对象KeyPair| +|AsyKeyGenerator|generateKeyPair() : Promise\|使用Promise方式，随机生成非对称密钥对象KeyPair| +|SymKeyGenerator|generateSymKey(callback : AsyncCallback\) : void|使用callback方式，随机生成对称密钥对象SymKey| +|SymKeyGenerator|generateSymKey() : Promise\|使用Promise方式，随机生成对称密钥对象SymKey| +| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void | 使用callback方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | +| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\ | 使用Promise方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | +| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\) : void| 使用callback方式，根据指定的二进制数据，生成对称密钥对象SymKey | +| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\| 使用Promise方式，根据指定的二进制数据，生成对称密钥对象SymKey | +| Key | getEncoded() : DataBlob; | 获取Key密钥对象的二进制数据（Key的子类实例包括对称密钥SymKey、公钥PubKey、私钥PriKey） | + +**开发步骤** + +示例1：随机生成非对称密钥KeyPair，并获得二进制数据（场景1、3） + +1. 创建非对称密钥生成器； +2. 通过非对称密钥生成器随机生成非对称密钥； +3. 获取密钥对象的二进制数据； + +以使用Promise方式随机生成RSA密钥（1024位，素数个数为2）为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function generateAsyKey() { + // 创建非对称密钥生成器 + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + // 通过非对称密钥生成器，随机生成非对称密钥 + let keyGenPromise = rsaGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + let pubKey = globalKeyPair.pubKey; + let priKey = globalKeyPair.priKey; + // 获取非对称密钥的二进制数据 + pkBlob = pubKey.getEncoded(); + skBlob = priKey.getEncoded(); + AlertDialog.show({ message : "pk bin data" + pkBlob.data} ); + AlertDialog.show({ message : "sk bin data" + skBlob.data} ); + }) +} +``` + +示例2：随机生成对称密钥SymKey，并获得二进制数据（场景1、3） + +1. 创建对称密钥生成器； +2. 通过对称密钥生成器随机生成对称密钥； +3. 获取算法库密钥对象的二进制数据； + +以使用Promise方式随机生成AES密钥（256位）为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +function testGenerateAesKey() { + // 创建对称密钥生成器 + let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256'); + // 通过密钥生成器随机生成对称密钥 + let promiseSymKey = symKeyGenerator.generateSymKey(); + promiseSymKey.then( key => { + // 获取对称密钥的二进制数据，输出长度为256bit的字节流 + let encodedKey = key.getEncoded(); + console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); + }) +} +``` + +示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2） + +1. 获取RSA公钥或私钥二进制数据，公钥需满足ASN.1语法、X.509规范、DER编码格式，私钥需满足ASN.1语法、PKCS#8规范、DER编码格式。 +2. 创建AsyKeyGenerator对象，调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function convertAsyKey() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024"); + let pkval = new Uint8Array([48,129,159,48,13,6,9,42,134,72,134,247,13,1,1,1,5,0,3,129,141,0,48,129,137,2,129,129,0,174,203,113,83,113,3,143,213,194,79,91,9,51,142,87,45,97,65,136,24,166,35,5,179,42,47,212,79,111,74,134,120,73,67,21,19,235,80,46,152,209,133,232,87,192,140,18,206,27,106,106,169,106,46,135,111,118,32,129,27,89,255,183,116,247,38,12,7,238,77,151,167,6,102,153,126,66,28,253,253,216,64,20,138,117,72,15,216,178,37,208,179,63,204,39,94,244,170,48,190,21,11,73,169,156,104,193,3,17,100,28,60,50,92,235,218,57,73,119,19,101,164,192,161,197,106,105,73,2,3,1,0,1]); + let pkBlob = {data : pkval}; + rsaGenerator.convertKey(pkBlob, null, function(err, keyPair) { + if (keyPair == null) { + AlertDialog.show({message : "Convert keypair fail"}); + } + AlertDialog.show({message : "Convert KeyPair success"}); + }) +} +``` + +**说明** + + 当前convertKey操作，公钥只支持转换满足X.509规范的DER格式，私钥只支持PKCS#8规范的DER格式； + +示例4：根据指定的ECC非对称密钥二进制数据，生成KeyPair对象（场景2、3） + +1. 获取ECC二进制密钥数据，封装成DataBlob对象。 +2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 + +```javascript +function convertEccAsyKey() { + 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 = { data: pubKeyArray }; + let priKeyBlob = { data: priKeyArray }; + let generator = cryptoFrameWork.createAsyKeyGenerator("ECC256"); + generator.convertKey(pubKeyBlob, priKeyBlob, (error, data) => { + if (error) { + AlertDialog.show({message : "Convert keypair fail"}); + } + AlertDialog.show({message : "Convert KeyPair success"}); + }) +} +``` + +示例5：根据指定的对称密钥二进制数据，生成SymKey对象（场景2、3） + +1. 创建对称密钥生成器； +2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象； +3. 获取算法库密钥对象的二进制数据； + +以使用callback方式生成3DES密钥（3DES密钥只能为192位）为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +function genKeyMaterialBlob() { + let arr = [ + 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, + 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, + 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) + let keyMaterial = new Uint8Array(arr); + return {data : keyMaterial}; +} + +function testConvertAesKey() { + // 生成对称密钥生成器 + let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); + // 根据用户指定的数据，生成对称密钥 + let keyMaterialBlob = genKeyMaterialBlob(); + try { + symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { + if (error) { // 业务逻辑执行错误通过callback的第一个参数返回错误信息 + console.error(`convertKey error, ${error.code}, ${error.message}`); + return; + } + console.info(`key algName: ${key.algName}`); + console.info(`key format: ${key.format}`); + let encodedKey = key.getEncoded(); // 获取对称密钥的二进制数据，输出长度为192bit的字节流 + console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); + }) + } catch (error) { // 参数检查的错误以同步的方式立即抛出异常 + console.error(`convertKey failed, ${error.code}, ${error.message}`); + return; + } +} +``` + +## 使用加解密操作 + +**场景说明** + +在数据存储或传输场景中，可以使用加解密操作用于保证数据的机密性，防止敏感数据泄露。使用加解密操作中，典型的场景有： +1. 使用对称密钥的加解密操作 +2. 使用非对称密钥的加解密操作 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
由于密码算法的复杂性，在选取不同规格和参数时，开发差异较大，无法通过代码示例一一列举，请仔细阅读API参考资料中的相关接口，确保使用正确。 + +以上场景设计的常用接口如下表所示： + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createCipher(transformation : string) : Cipher|根据transformation设置的算法参数创建Cipher对象| +|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Cipher对象| +|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\|使用Promise方式设置密钥并初始化Cipher对象| +|Cipher|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加加解密数据| +|Cipher|update(data : DataBlob) : Promise\|使用Promise方式添加加解密数据| +|Cipher|doFinal(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式结束对所有数据的加解密| +|Cipher|doFinal(data : DataBlob) : Promise\|使用Promise方式结束对所有数据的加解密| + +**开发步骤** + +示例1：使用对称密钥的加解密操作 + +1. 创建对称密钥生成器。 +2. 通过密钥生成器生成对称密钥。 +3. 创建加解密生成器。 +4. 通过加解密生成器加密或解密数据。 + +以AES GCM以Promise方式加解密为例： + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +var globalCipher; +var globalGcmParams; +var globalKey; +var globalCipherText; + +function genGcmParamsSpec() { + let arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0 , 0, 0]; // 12 bytes + let dataIv = new Uint8Array(arr); + let ivBlob = {data : dataIv}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0]; // 8 bytes + let dataAad = new Uint8Array(arr); + let aadBlob = {data : dataAad}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0]; // 16 bytes + let dataTag = new Uint8Array(arr); + let tagBlob = {data : dataTag}; // GCM的authTag在加密时从doFinal结果中获取，在解密时填入init函数的params参数中 + + let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; + return gcmParamsSpec; +} + +// 可理解的字符串转成字节流 +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +function genKeyMaterialBlob() { + 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}; +} + + +// AES GCM模式示例，自动生成密钥（promise写法） +function testAesGcm() { + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve('testAesGcm'); + }, 10) + }).then(() => { + // 生成对称密钥生成器 + let symAlgName = 'AES128'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); + if (symKeyGenerator == null) { + console.error('createSymKeyGenerator failed'); + return; + } + console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); + // 通过密钥生成器随机生成128位长度的对称密钥 + let promiseSymKey = symKeyGenerator.generateSymKey(); + // 构造参数 + globalGcmParams = genGcmParamsSpec(); + + // 生成加解密生成器 + let cipherAlgName = 'AES128|GCM|PKCS7'; + try { + globalCipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${globalCipher.algName}`); + } catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); + return; + } + return promiseSymKey; + }).then(key => { + let encodedKey = key.getEncoded(); + console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); + globalKey = key; + return key; + }).then(key => { + // 初始化加解密操作环境:开始加密 + let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; + let promiseInit = globalCipher.init(mode, key, globalGcmParams); // init + return promiseInit; + }).then(() => { + let plainText = {data : stringToUint8Array('this is test!')}; + let promiseUpdate = globalCipher.update(plainText); // update + return promiseUpdate; + }).then(updateOutput => { + globalCipherText = updateOutput; + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(authTag => { + // GCM模式需要从doFinal的输出中取出加密后的认证信息并填入globalGcmParams，在解密时传入init() + globalGcmParams.authTag = authTag; + return; + }).then(() => { + // 初始化加解密操作环境:开始解密 + let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; + let promiseInit = globalCipher.init(mode, globalKey, globalGcmParams); // init + return promiseInit; + }).then(() => { + let promiseUpdate = globalCipher.update(globalCipherText); // update + return promiseUpdate; + }).then(updateOutput => { + console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(finalOutput => { + if (finalOutput == null) { // 使用finalOutput.data前，先判断结果是否为null + console.info('GCM finalOutput is null'); + } + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +以3DES ECB以callback方式加解密（采用已有数据生成密钥）为例： + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +var globalCipher; +var globalGcmParams; +var globalKey; +var globalCipherText; + +// 可理解的字符串转成字节流 +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +function genKeyMaterialBlob() { + 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}; +} + +// 3DES ECB模式示例，采用已有数据生成密钥（callback写法） +function test3DesEcb() { + // 生成对称密钥生成器 + let symAlgName = '3DES192'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); + if (symKeyGenerator == null) { + console.error('createSymKeyGenerator failed'); + return; + } + console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); + + // 生成加解密生成器 + let cipherAlgName = '3DES192|ECB|PKCS7'; + try { + globalCipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${globalCipher.algName}`); + } catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); + return; + } + + // 根据指定的数据，生成对称密钥 + let keyMaterialBlob = genKeyMaterialBlob(); + try { + symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { + if (error) { + console.error(`convertKey error, ${error.code}, ${error.message}`); + return; + } + console.info(`key algName: ${key.algName}`); + console.info(`key format: ${key.format}`); + let encodedKey = key.getEncoded(); + console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); + globalKey = key; + + // 初始化加解密操作环境:开始加密 + let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; + // init + globalCipher.init(mode, key, null, (err, ) => { + let plainText = {data : stringToUint8Array('this is test!')}; + // update + globalCipher.update(plainText, (err, updateOutput) => { + globalCipherText = updateOutput; + //doFinal + globalCipher.doFinal(null, (err, finalOutput) => { + if (error) { + console.error(`doFinal error, ${error.code}, ${error.message}`); + return; + } + if (finalOutput != null) { + globalCipherText = Array.from(globalCipherText.data); + finalOutput = Array.from(finalOutput.data); + globalCipherText = globalCipherText.concat(finalOutput); + globalCipherText = new Uint8Array(globalCipherText); + globalCipherText = {data : globalCipherText}; + } + // 初始化加解密操作环境:开始解密 + let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; + // init + globalCipher.init(mode, globalKey, null, (err, ) => { + // update + globalCipher.update(globalCipherText, (err, updateOutput) => { + console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); + // doFinal + globalCipher.doFinal(null, (error, finalOutput) => { + if (finalOutput != null) { // 使用finalOutput.data前，先判断结果是否为null + console.info("decrypt plainText:" + uint8ArrayToString(finalOutput.data)); + } + }) + }) + }) + }) + }) + }) + }) + } catch (error) { + console.error(`convertKey failed, ${error.code}, ${error.message}`); + return; + } +} +``` +以AES GCM以promise方式，分段update()实现加解密为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +var globalCipher; +var globalGcmParams; +var globalKey; +var globalCipherText; +var globalPlainText; + +function genGcmParamsSpec() { + let arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0 , 0, 0]; // 12 bytes + let dataIv = new Uint8Array(arr); + let ivBlob = {data : dataIv}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0]; // 8 bytes + let dataAad = new Uint8Array(arr); + let aadBlob = {data : dataAad}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0]; // 16 bytes + let dataTag = new Uint8Array(arr); + let tagBlob = {data : dataTag}; + let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; + return gcmParamsSpec; +} + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +// 算法库不限定update的次数和每次加解密的数据量，业务可根据自身内存情况对明文/密文进行多次分段。 +function testAesMultiUpdate() { + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve('testAesMultiUpdate'); + }, 10) + }).then(() => { + // 生成对称密钥生成器 + let symAlgName = 'AES128'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); + if (symKeyGenerator == null) { + console.error('createSymKeyGenerator failed'); + return; + } + console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); + // 通过密钥生成器随机生成128位长度的对称密钥 + let promiseSymKey = symKeyGenerator.generateSymKey(); + // 构造参数 + globalGcmParams = genGcmParamsSpec(); + + // 生成加解密生成器 + let cipherAlgName = 'AES128|GCM|PKCS7'; + try { + globalCipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${globalCipher.algName}`); + } catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); + return; + } + return promiseSymKey; + }).then(key => { + let encodedKey = key.getEncoded(); + console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); + globalKey = key; + return key; + }).then(key => { + // 初始化加解密操作环境:开始加密 + let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; + let promiseInit = globalCipher.init(mode, key, globalGcmParams); // init + return promiseInit; + }).then(async () => { + let plainText = "aaaaa.....bbbbb.....ccccc.....ddddd.....eee"; // 假设明文总共43字节 + let messageArr = []; + let updateLength = 20; // 假设每20字节分段update一次 + globalCipherText = []; + + for (let i = 0; i <= plainText.length; i++) { + if ((i % updateLength == 0 || i == plainText.length) && messageArr.length != 0) { + let message = new Uint8Array(messageArr); + let messageBlob = { data : message }; + let updateOutput = await globalCipher.update(messageBlob); // 分段update + // 把update的结果拼接起来，得到密文（有些情况下还需拼接doFinal的结果，这取决于分组模式 + // 和填充模式，本例中GCM模式的doFinal结果只包含authTag而不含密文，所以不需要拼接） + globalCipherText = globalCipherText.concat(Array.from(updateOutput.data)); + messageArr = []; + } + if (i < plainText.length) { + messageArr.push(plainText.charCodeAt(i)); + } + } + return; + }).then(() => { + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(authTag => { + // 获取加密后的认证信息 + globalGcmParams.authTag = authTag; + return; + }).then(() => { + // 初始化加解密操作环境:开始解密 + let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; + let promiseInit = globalCipher.init(mode, globalKey, globalGcmParams); // init + return promiseInit; + }).then(async () => { + let updateLength = 20; + let updateTimes = Math.ceil(globalCipherText.length / updateLength); // 上取整 + globalPlainText = ""; + for (let i = 0; i < updateTimes; i++) { + let messageArr = globalCipherText.slice(i * updateLength, (i + 1) * updateLength); + let message = new Uint8Array(messageArr); + let messageBlob = { data : message }; + let updateOutput = await globalCipher.update(messageBlob); // 分段update + globalPlainText += uint8ArrayToString(updateOutput.data); // 恢复出原始明文 + } + return; + }).then(() => { + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(finalOutput => { + if (finalOutput == null) { + console.info('GCM finalOutput is null'); + } + console.info(`decrypt output: ${globalPlainText}`); + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +示例2：使用非对称密钥的加解密操作 + +1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 +2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式。 +3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文。 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let plan = "This is cipher test."; + +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; +} + +function encryptMessageProMise() { + 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); + }).then(() => { + let input = { data : stringToUint8Array(plan) }; + return cipher.doFinal(input); + }).then(dataBlob => { + console.info("EncryptOutPut is " + dataBlob.data); + }); +} + +function encryptMessageCallback() { + 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 input = {data : stringToUint8Array(plan) }; + cipher.doFinal(input, function (err, data) { + console.info("EncryptOutPut is " + data.data); + }) + }) + }) +} + +function decryptMessageProMise() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); + let decoder = cryptoFramework.createCipher("RSA1024|PKCS1"); + let keyGenPromise = rsaGenerator.generateKeyPair(); + let keyPair; + let cipherDataBlob; + let input = { data : stringToUint8Array(plan) }; + keyGenPromise.then(rsaKeyPair => { + keyPair = rsaKeyPair; + return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, keyPair.pubKey, null); + }).then(() => { + return cipher.doFinal(input); + }).then(dataBlob => { + console.info("EncryptOutPut is " + dataBlob.data); + AlertDialog.show({message : "output" + dataBlob.data}); + cipherDataBlob = dataBlob; + return decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, keyPair.priKey, null); + }).then(() => { + return decoder.doFinal(cipherDataBlob); + }).then(decodeData => { + if (decodeData.data.toString() === input.data.toString()) { + AlertDialog.show({message : "decrypt success"}); + return; + } + AlertDialog.show({message : "decrypt fail"}); + }); +} + +function decryptMessageCallback() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); + let decoder = cryptoFramework.createCipher("RSA1024|PKCS1"); + let plainText = "this is cipher text"; + let input = {data : stringToUint8Array(plainText) }; + let cipherData; + let keyPair; + rsaGenerator.generateKeyPair(function (err, newKeyPair) { + keyPair = newKeyPair; + cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, keyPair.pubKey, null, function (err, data) { + cipher.doFinal(input, function (err, data) { + AlertDialog.show({ message : "EncryptOutPut is " + data.data} ); + cipherData = data; + decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, keyPair.priKey, null, function (err, data) { + decoder.doFinal(cipherData, function (err, data) { + if (input.data.toString() === data.data.toString()) { + AlertDialog.show({ message : "decrype success"} ); + return; + } + AlertDialog.show({ message : "decrype fail"} ); + }); + }); + }); + }); + }); +} +``` +以RSA非对称加解密（多次调用doFinal实现分段）为例： +```javascript +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; +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +function encryptLongMessagePromise() { + let globalPlainText = "This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!"; + let globalCipherOutput; + let globalDecodeOutput; + var globalKeyPair; + let plainTextSplitLen = 64; // RSA每次加解密允许的原文长度大小与密钥位数和填充模式等有关，详细规格内容见overview文档 + let cipherTextSplitLen = 128; // RSA密钥每次加密生成的密文数据长度计算方式：密钥位数/8 + let keyGenName = "RSA1024"; + let cipherAlgName = "RSA1024|PKCS1"; + let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator(keyGenName); // 创建非对称密钥生成器对象 + let cipher = cryptoFramework.createCipher(cipherAlgName); // 创建加密Cipher对象 + let decoder = cryptoFramework.createCipher(cipherAlgName); // 创建解密Decoder对象 + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve("testRsaMultiDoFinal"); + }, 10); + }).then(() => { + return asyKeyGenerator.generateKeyPair(); // 生成rsa密钥 + }).then(keyPair => { + globalKeyPair = keyPair; // 保存到密钥对全局变量 + return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, globalKeyPair.pubKey, null); + }).then(async () => { + globalCipherOutput = []; + // 将原文按64字符进行拆分，循环调用doFinal进行加密，使用1024bit密钥时，每次加密生成128B长度的密文 + for (let i = 0; i < (globalPlainText.length / plainTextSplitLen); i++) { + let tempStr = globalPlainText.substr(i * plainTextSplitLen, plainTextSplitLen); + let tempBlob = { data : stringToUint8Array(tempStr) }; + let tempCipherOutput = await cipher.doFinal(tempBlob); + globalCipherOutput = globalCipherOutput.concat(Array.from(tempCipherOutput.data)); + } + console.info(`globalCipherOutput len is ${globalCipherOutput.length}, data is: ${globalCipherOutput.toString()}`); + return; + }).then(() =>{ + return decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, globalKeyPair.priKey, null); + }).then(async() => { + globalDecodeOutput = []; + // 将密文按128B进行拆分解密，得到原文后进行拼接 + for (let i = 0; i < (globalCipherOutput.length / cipherTextSplitLen); i++) { + let tempBlobData = globalCipherOutput.slice(i * cipherTextSplitLen, (i + 1) * cipherTextSplitLen); + let message = new Uint8Array(tempBlobData); + let tempBlob = { data : message }; + let tempDecodeOutput = await decoder.doFinal(tempBlob); + globalDecodeOutput += uint8ArrayToString(tempDecodeOutput.data); + } + if (globalDecodeOutput === globalPlainText) { + console.info(`encode and decode success`); + } else { + console.info(`encode and decode error`); + } + return; + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +**说明** + +1. 使用RSA加解密时，Cipher对象不可重复调用init方法初始化，在创建了一个加密Cipher对象后，如果要进行解密，则需要重新创建另一个Cipher对象执行解密操作。 +2. RSA加密有长度限制，允许加密明文的最大长度见[加解密算法库框架概述](cryptoFramework-overview.md)中的基本概念章节。 +3. RSA解密每次允许解密的密文长度为，RSA密钥的位数/8。 + +## 使用签名验签操作 + +**场景说明** + +当需要判断接收的数据是否被篡改且是否为指定对象发送的数据时，可以使用签名验签操作。使用签名验签操作中，典型的场景有： +1. 使用RSA签名验签操作 +2. 使用ECC签名验签操作 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
由于密码算法的复杂性，在选取不同规格和参数时，开发差异较大，无法通过代码示例一一列举，请仔细阅读API参考资料中的相关接口，确保使用正确。 + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createSign(algName : string) : Sign|根据String设置的参数创建Sign对象| +|Sign|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Sign对象| +|Sign|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Sign对象| +|Sign|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加签名数据| +|Sign|update(data : DataBlob) : Promise\|用Promise方式添加签名数据| +|Sign|sign(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式签名所有数据| +|Sign|sign(data : DataBlob) : Promise\|使用Promise方式签名所有数据| +|cryptoFramework|function createVerify(algName : string) : Verify|根据String设置的参数创建Verify对象| +|Verify|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Verify对象| +|Verify|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Verify对象| +|Verify|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加验签数据| +|Verify|update(data : DataBlob) : Promise\|用Promise方式添加验签数据| +|Verify|verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void|使用callback方式验签所有数据| +|Verify|verify(data : DataBlob, signatureData : DataBlob) : Promise\|使用Promise方式验签所有数据| + +**开发步骤** + +示例1：使用RSA签名验签操作 +1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 +2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 +3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用sign接口生成数据的签名。 +4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 +5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。 +```javascript +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"; +let plan2 = "This is Sign test plan1"; +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); + }).then(() => { + return signer.sign(input2); + }).then(dataBlob => { + SignMessageBlob = dataBlob; + console.info("sign output is " + SignMessageBlob.data); + }); +} + +function verifyMessagePromise() { + let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); + let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); + verifyInitPromise.then(() => { + return verifyer.update(input1); + }).then(() => { + return verifyer.verify(input2, SignMessageBlob); + }).then(res => { + console.log("Verify result is " + res); + }); +} + +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) { + signer.sign(input2, function (err, data) { + SignMessageBlob = data; + console.info("sign output is " + SignMessageBlob.data); + }); + }); + }); + }); +} + +function verifyMessageCallback() { + let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); + 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); + }); + }); + }) +} +``` + +示例2：使用ECDSA操作 +1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 +2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 +3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用doFinal接口生成数据的签名。 +4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 +5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用doFinal接口传入签名进行验签。 + +```javascript +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"; +let plan2 = "This is Sign test plan1"; +let input1 = { data : stringToUint8Array(plan1) }; +let input2 = { data : stringToUint8Array(plan2) }; + +function signMessagePromise() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let signer = cryptoFramework.createSign("ECC256|SHA256"); + let keyGenPromise = eccGenerator.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); + }); +} + +function verifyMessagePromise() { + let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); + let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); + verifyInitPromise.then(() => { + return verifyer.update(input1); + }).then(() => { + return verifyer.verify(input2, SignMessageBlob); + }).then(res => { + console.log("Verify result is " + res); + }); +} + +function signMessageCallback() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let signer = cryptoFramework.createSign("ECC256|SHA256"); + eccGenerator.generateKeyPair(function (err, keyPair) { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + signer.init(priKey, function (err, data) { + signer.update(input1, function (err, data) { + signer.sign(input2, function (err, data) { + SignMessageBlob = data; + console.info("sign output is " + SignMessageBlob.data); + }); + }); + }); + }); +} + +function verifyMessageCallback() { + let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); + 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); + }); + }); + }) +} +``` +以执行签名、验签操作时多次调用update实现分段为例： + +```javascript +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; +} + +function signLongMessagePromise() { + let globalPlainText = "This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!"; + let globalSignData; + let textSplitLen = 64; // 自定义的数据拆分长度 + let keyGenName = "RSA1024"; + let cipherAlgName = "RSA1024|PKCS1|SHA256"; + let globalKeyPair; + let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator(keyGenName); // 创建非对称密钥生成器对象 + let signer = cryptoFramework.createSign(cipherAlgName); // 创建加密Cipher对象 + let verifier = cryptoFramework.createVerify(cipherAlgName); // 创建解密Decoder对象 + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve("testRsaMultiUpdate"); + }, 10); + }).then(() => { + return asyKeyGenerator.generateKeyPair(); // 生成rsa密钥 + }).then(keyPair => { + globalKeyPair = keyPair; // 保存到密钥对全局变量 + return signer.init(globalKeyPair.priKey); + }).then(async () => { + // 当原文过大时，可将原文按理想长度进行拆分，循环调用update添加原文 + for (let i = 0; i < (globalPlainText.length / textSplitLen); i++) { + let tempStr = globalPlainText.substr(i * textSplitLen, textSplitLen); + let tempBlob = { data : stringToUint8Array(tempStr) }; + await signer.update(tempBlob); + } + return signer.sign(null); + }).then(data =>{ + globalSignData = data.data; + console.info(`globalSignOutput len is ${globalSignData.length}, data is: ${globalSignData.toString()}`); + return verifier.init(globalKeyPair.pubKey); + }).then(async() => { + // 将密文按128B进行拆分解密，得到原文后进行拼接 + for (let i = 0; i < (globalPlainText.length / textSplitLen); i++) { + let tempData = globalPlainText.slice(i * textSplitLen, (i + 1) * textSplitLen); + let tempBlob = { data : stringToUint8Array(tempData) }; + await verifier.update(tempBlob); + } + return verifier.verify(null, { data : globalSignData}); + }).then(res => { + console.info(`verify res is ${res}`); + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +## 使用摘要操作 + +**场景说明** + +用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） + +使用摘要操作的主要场景为： + +用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +| 实例名 | 接口名 | 描述 | +| --------------- | ------------------------------------------------------------ | -------------------------------------------------- | +| cryptoFramework | function createMd(algName : string) : Md; | 指定摘要算法，生成摘要操作实例Md | +| Md | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受用户输入数据，通过Callback的方式，异步更新摘要 | +| Md | update(input : DataBlob) : Promise\; | 接受用户输入数据，通过Promise的方式，异步更新摘要 | +| Md | digest(callback : AsyncCallback\) : void; | 通过Callback的方式，返回结果 | +| Md | digest() : Promise\; | 通过Promise的方式，返回结果 | +| Md | getMdLength() : number; | 获取摘要的长度（由指定的摘要算法决定） | +| Md | readonly algName : string; | 获取当前设置的摘要算法名 | + +**开发步骤** + +1. 设置算法，通过接口`createMd`生成摘要操作实例 +2. 接受用户数据，通过接口`update`，更新摘要，此步骤可重复 +3. 通过接口`digest`，返回摘要计算结果 +4. 获取当前摘要算法名与摘要计算长度 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +// turn string into uint8Arr +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +// generate dataBlob with given length +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +// md with promise async +function doMdByPromise(algName) { + var md; + try { + md = cryptoFramework.createMd(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + } + console.error("[Promise]: Md algName is: " + md.algName); + // 初次update + var promiseMdUpdate = md.update(GenDataBlob(12)); + promiseMdUpdate.then(() => { + // 可根据情况进行多次update + promiseMdUpdate = md.update(GenDataBlob(12)); + return promiseMdUpdate; + }).then(mdOutput => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; + }).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); + var mdLen = md.getMdLength(); + console.error("[Promise]: MD len: " + mdLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} + +// md with callback async +function doMdByCallback(algName) { + var md; + try { + md = cryptoFramework.createMd(algName); + } catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + } + console.error("[Callback]: Md algName is: " + md.algName); + // 初次update + md.update(GenDataBlob(12), (err,) => { + if (err) { + console.error("[Callback]: err: " + err.code); + } + // 可根据情况进行多次update + md.update(GenDataBlob(12), (err1,) => { + if (err1) { + console.error("[Callback]: err: " + err1.code); + } + md.digest((err2, mdOutput) => { + if (err2) { + console.error("[Callback]: err: " + err2.code); + } else { + console.error("[Callback]: MD result: " + mdOutput.data); + var mdLen = md.getMdLength(); + console.error("[Callback]: MD len: " + mdLen); + } + }); + }); + }); +} +``` +以MD更新时多次调用update实现分段为例： +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +async function updateData(index, obj, data) { + console.error("update " + (index + 1) + " MB data..."); + return obj.update(data); +} + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +function LoopMdPromise(algName, loopSize) { + var md; + try { + md = cryptoFramework.createMd(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + return; + } + console.error("[Promise]: Md algName is: " + md.algName); + var promiseMdUpdate = md.update(GenDataBlob(12)); + promiseMdUpdate.then(() => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; + }).then(async () => { + for (var i = 0; i < loopSize; i++) { + await updateData(i, md, GenDataBlob(12)); + } + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; + }).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); + var mdLen = md.getMdLength(); + console.error("[Promise]: MD len: " + mdLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} +``` + +## 使用密钥协商操作 + +**场景说明** + +使用密钥协商操作中，典型的场景有： + +通信双方可以在一个公开的信道上通过相互传送一些消息，共同建立一个安全的共享秘密密钥。 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createKeyAgreement(algName : string) : KeyAgreement|根据String设置的参数创建KeyAgreement对象| +|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void|使用callback方式进行密钥协商| +|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\|使用Promise方式进行密钥协商| + +**开发步骤** + +1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 +2. 基于ECC密钥的私钥及公钥执行ECDH操作。 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let globalKeyPair; + +function ecdhPromise() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); + let keyGenPromise = eccGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + return eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey); + }).then((secret) => { + console.info("ecdh output is " + secret.data); + }).catch((error) => { + console.error("ecdh error."); + }); +} + +function ecdhCallback() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); + eccGenerator.generateKeyPair(function (err, keyPair) { + globalKeyPair = keyPair; + eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey, function (err, secret) { + if (err) { + console.error("ecdh error."); + return; + } + console.info("ecdh output is " + secret.data); + }); + }); +} +``` + +## 使用消息认证码操作 + +**场景说明** + +消息认证码操作主要应用于身份认证的场景： + +Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为 + +用户指定摘要算法（如SHA256）生成消息认证码Mac实例，输入对称密钥初始化Mac，并传入单段或多段需要摘要的信息，进行消息认证码计算，并获取消息认证码计算结果，在指定算法后可获取当前算法名与消息认证码计算长度（字节）。 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +| 实例名 | 接口名 | 描述 | +| --------------- | ------------------------------------------------------------ | --------------------------------------------------- | +| cryptoFramework | function createMac(algName : string) : Mac; | 指定摘要算法，生成消息认证码实例Mac | +| Mac | init(key : SymKey, callback : AsyncCallback\) : void; | 接收输入对称密钥，通过Callback的方式，异步初始化MAC | +| Mac | init(key : SymKey) : Promise\; | 接收输入对称密钥，通过Promise的方式，异步初始化MAC | +| Mac | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受输入数据，通过Callback的方式，异步更新MAC | +| Mac | update(input : DataBlob) : Promise\; | 接受输入数据，通过Promise的方式，异步更新MAC | +| Mac | doFinal(callback : AsyncCallback\) : void; | 通过Callback的方式，返回MAC计算结果 | +| Mac | doFinal() : Promise\; | 通过Promise的方式，返回MAC计算结果 | +| Mac | getMacLength() : number; | 获取MAC的长度（由指定的摘要算法决定） | +| Mac | readonly algName : string; | 获取当前设置的摘要算法名 | + +**开发步骤** + +1. 设置算法，通过接口`createMac`生成消息认证码操作实例 +2. 接受输入对称密钥，通过接口`init`，初始化Mac +3. 接受数据，通过接口`update`，更新Mac，此步骤可重复 +4. 通过接口`doFinal`，返回Mac计算结果 +5. 获取当前摘要算法名与Mac计算长度 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +// turn string into uint8Arr +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +// generate blob with this func +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +function doHmacByPromise(algName) { + var mac; + try { + mac = cryptoFramework.createMac(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + } + console.error("[Promise]: Mac algName is: " + mac.algName); + var KeyBlob = { + data : stringToUint8Array("12345678abcdefgh") + } + var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); + var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); + promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; + }).then(() => { + // 初次update + var promiseMacUpdate = mac.update(GenDataBlob(12)); + return promiseMacUpdate; + }).then(() => { + // 可根据情况进行多次update + var promiseMacUpdate = mac.update(GenDataBlob(12)); + return promiseMacUpdate; + }).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; + }).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); + var macLen = mac.getMacLength(); + console.error("[Promise]: MAC len: " + macLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} + +// process by callback +function doHmacByCallback(algName) { + var mac; + try { + mac = cryptoFramework.createMac(algName); + } catch (error) { + AlertDialog.show({message: "[Callback]: error code: " + error.code + ", message is: " + error.message}); + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + } + var KeyBlob = { + data : stringToUint8Array("12345678abcdefgh") + } + var 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); + } + // 初次update + mac.update(GenDataBlob(12), (err2, ) => { + if (err2) { + console.error("[Callback]: err: " + err2.code); + } + // 可根据情况进行多次update + mac.update(GenDataBlob(12), (err3, ) => { + if (err3) { + console.error("[Callback]: err: " + err3.code); + } + mac.doFinal((err4, macOutput) => { + if (err4) { + console.error("[Callback]: err: " + err4.code); + } else { + console.error("[Callback]: HMAC result: " + macOutput.data); + var macLen = mac.getMacLength(); + console.error("[Callback]: MAC len: " + macLen); + } + }); + }); + }); + }); + }); +} +``` +以HMAC更新MAC时多次调用update实现分段为例： +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +async function updateData(index, obj, data) { + console.error("update " + (index + 1) + " MB data..."); + return obj.update(data); +} + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +function LoopHmacPromise(algName, loopSize) { + var mac; + try { + mac = cryptoFramework.createMac(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + return; + } + console.error("[Promise]: Mac algName is: " + mac.algName); + var KeyBlob = { + data : stringToUint8Array("12345678abcdefgh") + } + var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); + var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); + promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; + }).then(async () => { + for (var i = 0; i < loopSize; i++) { + await updateData(i, mac, GenDataBlob(12)); + } + var promiseMacUpdate = mac.update(GenDataBlob(12)); + return promiseMacUpdate; + }).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; + }).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); + var macLen = mac.getMacLength(); + console.error("[Promise]: MAC len: " + macLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} +``` + + +## 使用随机数操作 + +**场景说明** + +使用随机数操作的主要场景为： + +- 用户生成随机数Random实例，输入随机数生成的长度（字节），生成指定长度的随机数。 +- 用户使用生成的随机数作为参数，进行种子设置。 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +| 实例名 | 接口名 | 描述 | +| --------------- | ------------------------------------------------------------ | ---------------------------------------------- | +| cryptoFramework | function createRandom() : Random; | 生成随机数Random实例 | +| Random | generateRandom(len : number, callback: AsyncCallback\) : void; | 接受输入长度，通过Callback，异步生成随机数 | +| Random | generateRandom(len : number) : Promise\; | 接受输入长度，通过Promise，异步生成随机数 | +| Random | setSeed(seed : DataBlob) : void; | 接受输入Blob，设置种子 | + +**开发步骤** + +1. 通过接口`createRandom`生成随机数操作实例 +2. 接受输入长度，通过接口`generateRandom`，生成指定长度的随机数 +3. 接受DataBlob数据，通过接口`setSeed`，为随机数生成池设置种子 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +// process by promise +function doRandByPromise(len) { + var rand; + try { + rand = cryptoFramework.createRandom(); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + } + var promiseGenerateRand = rand.generateRandom(len); + promiseGenerateRand.then(randData => { + console.error("[Promise]: rand result: " + randData.data); + try { + rand.setSeed(randData); + } catch (error) { + console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); + } + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} + +// process by callback +function doRandByCallback(len) { + var rand; + try { + rand = cryptoFramework.createRandom(); + } catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + } + rand.generateRandom(len, (err, randData) => { + if (err) { + console.error("[Callback]: err: " + err.code); + } else { + console.error("[Callback]: generate random result: " + randData.data); + try { + rand.setSeed(randData); + } catch (error) { + console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); + } + } + }); +} +``` diff --git a/zh-cn/application-dev/security/cryptoFramework-overview.md b/zh-cn/application-dev/security/cryptoFramework-overview.md index 0678a4d0f6..65c6ef5d43 100644 --- a/zh-cn/application-dev/security/cryptoFramework-overview.md +++ b/zh-cn/application-dev/security/cryptoFramework-overview.md @@ -1,235 +1,385 @@ -# 加解密算法库框架概述 -加解密算法库框架是一个屏蔽了第三方密码学算法库实现差异的算法框架，提供加解密、签名验签、消息验证码、哈希、安全随机数等相关功能。开发者可以通过调用加解密算法库框架，忽略底层不同三方算法库的差异，实现迅捷开发。 -## 框架实现原理 -加解密算法库框架提供的组件分为三层：接口层，Framework层和插件层。接口层负责对外提供统一的JS接口，插件层实现针对具体三方算法库的功能，Framework层通过灵活加载插件层的插件适配并屏蔽三方算法库差异。 -## 基本概念 -**对称密钥** - -对称密钥使用同一个密钥对数据进行加密解密操作。即对称加密算法中，数据发送方使用加密密钥对明文进行特殊加密算法处理后，使其变成复杂的加密密文发送出去。接收方收到密文后，若想解读原文，则需要使用同一个加密密钥以及相同算法的逆算法对密文进行解密，才能使其恢复成可读明文。 - -- **AES加密** - - AES的全称是Advanced Encryption Standard，是最常见的对称加密。AES为分组密码，分组密码也就是把明文分成一组一组的，每组长度相等，每次加密一组数据，直到加密完整个明文。在AES标准规范中，分组长度只能是128位，也就是说，每个分组为16个字节（每个字节8位）。密钥的长度可以使用128位、192位或256位。 -- **3DES加密** - - 3DES，也称为 3DESede 或 TripleDES，是三重数据加密算法，相当于是对每个数据块应用三次DES的对称加密算法，它使用3个64位的密钥对数据块进行三次加密。相比DES，3DES因密钥长度变长，安全性有所提高，但其处理速度不高。因此又出现了AES加密算法，AES较于3DES速度更快、安全性更高。 - -**非对称密钥** - -非对称密钥使用公钥和私钥两个密钥来进行算法操作，公钥对外公开，私钥对外保密。对于加解密操作，一般使用公钥对明文进行加密形成密文，持有私钥的人即可对密文解密形成明文。对于签名验签操作，使用私钥对明文进行签名，公钥持有者可以通过公钥对签名数据做验签，验证数据是否被篡改。 - -- **RSA密钥** - - RSA密钥以极大整数做因数分解的数学难题作为密钥安全性的基石。生成密钥时，首先需要随机出两个大素数p和q，计算n = p * q并将n做为模，再选择一个大于1且小于(p - 1) * (q - 1)的整数e，确保e与(p - 1)*(q - 1)互素，最后计算d，使得e * d - 1为(p - 1)和(q - 1)的倍数，则可得到公钥(n, e)和私钥(n, d)。 - - 算法库框架除提供了默认的双素数RSA密钥生成外，还提供了多素数密钥生成方式，可以在密钥生成时通过指定primes参数（PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5）指定素数个数。多素数密钥的优点是可以减少解密、签名的计算量（中国剩余定理），但相对的劣势是密钥强度会越低，算法库依据OpenSSL的素数使用规则制定了相应规格，具体将在**约束与限制**章节中说明。 -- **ECC密钥** - - ECC是一种基于椭圆曲线数学的公开密钥加密算法，其数学基础是利用椭圆曲线上的有理点构成Abel加法群上椭圆离散对数的计算困难性，算法库框架提供了多种椭圆曲线的ECC密钥生成能力。 - -**加解密** - -- **对称AES加解密** - - 算法库目前提供了AES加解密常用的7种加密模式：ECB、CBC、OFB、CFB、CTR、GCM和CCM。AES为分组加密算法，分组长度大小为128位。实际应用中明文最后一组可能不足128位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充； - - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； - - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； - - > **说明：** ECB、CBC加密模式，明文长度不是128位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即AES加密填充至16字节。 -- **对称3DES加解密** - - 该算法的加解密过程分别是对明文/密文数据进行三次DES加密或解密，得到相应的密文或明文。 - - 算法库目前提供了3DES加解密常用的4种加密模式：ECB、CBC、OFB和CFB。DES为分组加密算法，分组长度大小为64位。实际应用中明文最后一组可能不足64位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充； - - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； - - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； - - > **说明：** ECB、CBC加密模式，明文长度不是64位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即3DES加密填充至8字节。 - -- **非对称RSA加解密** - - 当持有RSA公钥(n, e)和私钥(n, d)后，RSA加密过程为：密文 = 明文 ^ e mod n, 解密过程为：明文 = 密文 ^ d mod n。算法库目前提供了RSA加解密常用的三种模式：PKCS1、PKCS1_OAEP和NoPadding。RSA为块加密算法，加密长度需要在固定长度进行，实际应用中会使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充，输入的数据必须与RSA钥模一样长，输出数据长度与RSA钥模一样长； - - PKCS1：pkcs1padding V1.5是RSA加解密默认的填充方式，输入的数据必须<=RSA钥模-11，输出数据长度与RSA钥模一样长； - - PKCS1_OAEP：RSA_PKCS1_OAEP_PADDING填充模式是PKCS#1推出的新填充方式，此模式需要设置两个摘要（md和mgf1_md），输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2，输出数据长度与RSA钥模一样长；
- - **补充说明：** RSA钥模 = (RSA的bits + 7) / 8 - -**签名验签** - -- **RSA签名验签** - - 当持有RSA公钥(n, e)和私钥(n, d)后，RSA签名生成过程为：签名 = 消息 ^ d mod n, 验签过程为：消息 = 签名 ^ d mod n。消息发送方发送数据时，同时发送消息和私钥签名后的签名信息，消息接收方接受到数据后，将签名信息用公钥解密并验证消息是否一致。因发送的消息长度大多大于RSA钥模，因此算法库框架提供了两种padding模式，通过摘要提取消息的散列值再做签名。算法库框架中提供了签名验签相关的两种模式：PKCS1和PSS。下问对两种模式做详细描述： - - PKCS1: pkcs1padding V1.5是RSA加解密默认的填充方式，使用该模式时需要设置摘要（md）； - - PSS: PSS模式是RSA 算法的基础上叠加上一种填充算法，使用该签名算法时需要使用摘要(md)和掩码函数（mgf1_md）; -- **ECDSA** - - 椭圆曲线数字签名算法（ECDSA）是基于椭圆曲线密码（ECC）模拟数字签名算法（DSA）。相比普通的离散对数问题（DLP）和大数分解问题（IFP），椭圆曲线密码的单位比特强度要高于其他公钥体制。算法库框架提供了多种椭圆曲线及摘要算法组合的椭圆曲线数字签名算法（ECDSA）能力。 - -**密钥协商** - -- **ECDH** - - ECDH的全称是椭圆曲线迪菲-赫尔曼秘钥交换，是用来在一个非安全通道中建立起安全的共有加密资料，交换双方可以在不共享任何秘密的情况下协商出一个密钥。算法库框架基于开源算法库提供了多种椭圆曲线的ECDH能力。 - -**摘要** - -消息摘要MD算法是一种能将任意长度的输入消息，通过哈希算法生成长度固定的摘要的算法。消息摘要算法通过其不可逆的特性能被用于敏感信息的加密。消息摘要算法也被称为哈希算法或单向散列算法。 -在摘要算法相同时，生成的摘要值主要有下列特点： - -- 当输入消息相同时，生成摘要序列相同； -- 当输入消息的长度不一致时，生成摘要序列长度固定（摘要长度由算法决定）； -- 当输入消息不一致时，生成摘要序列几乎不会相同（依然存在相同概率，由摘要长度决定相同概率）； - -消息摘要算法主要分为三类：MD，SHA与MAC（详见HMAC章节） -MD算法包括MD2，MD4和MD5。 -SHA算法主要包括SHA1，SHA224，SHA256，SHA384，SHA512。 - -**消息验证码** - -HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息认证码算法。HMAC通过指定摘要算法，以通信双方共享密钥与消息作为输入，生成消息认证码用于检验传递报文的完整性，HMAC生成的消息认证码为固定长度。HMAC在消息摘要算法的基础上增加了密钥的输入，确保了信息的正确性。 - -**随机数** - -随机数在加解密过程中主要用于临时会话密钥的生成与非对称加密算法中密钥的生成。随机数由硬件生成的硬件随机数生成器或由软件生成的伪随机数生成器进行生成。在加解密的场景中，安全随机数生成器需要具备随机性，不可预测性，与不可重现性。密码学安全伪随机数生成器CSPRNG（Cryptography Secure Random Number Generators）生成的随机数满足密码学安全伪随机性 - -- **内部状态**代表随机数生成器内存中的数值，当内部状态相同时，随机数生成器会生成固定的随机数序列 -- **种子**（seed）是一个用来对伪随机数的内部状态进行初始化的数据，随机数生成器通过种子来生成一系列的随机序列。 - - -## 约束与限制 - -- 算法库框架不支持多线程并发操作。 - -### 密钥生成规格 - -**对称密钥生成规格** - -支持的对称密钥生成参数： - -|对称密钥算法|密钥长度（bit）|字符串参数| -|---|---|---| -|3DES|192|3DES192| -|AES|128|AES128| -|AES|192|AES192| -|AES|256|AES256| - - > **说明**：“字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 - -**非对称密钥生成规格** -- **RSA密钥生成** - - 支持的非对称密钥生成参数： - - |非对称密钥算法|密钥长度（bit）|素数个数|字符串参数| - |---|---|---|---| - |RSA|512|2|RSA512\|PRIMES_2| - |RSA|768|2|RSA768\|PRIMES_2| - |RSA|1024|2|RSA1024\|PRIMES_2| - |RSA|1024|3|RSA1024\|PRIMES_3| - |RSA|2048|2|RSA2048\|PRIMES_2| - |RSA|2048|3|RSA2048\|PRIMES_3| - |RSA|3072|2|RSA3072\|PRIMES_2| - |RSA|3072|3|RSA3072\|PRIMES_3| - |RSA|4096|2|RSA4096\|PRIMES_2| - |RSA|4096|3|RSA4096\|PRIMES_3| - |RSA|4096|4|RSA4096\|PRIMES_4| - |RSA|8192|2|RSA8192\|PRIMES_2| - |RSA|8192|3|RSA8192\|PRIMES_3| - |RSA|8192|4|RSA8192\|PRIMES_4| - |RSA|8192|5|RSA8192\|PRIMES_5| - - > **说明**：生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 - -- **ECC密钥生成** - - 支持的非对称密钥生成参数： - - |非对称密钥算法|密钥长度| - |---|---| - |ECC|ECC224| - |ECC|ECC256| - |ECC|ECC384| - |ECC|ECC521| - -### 加解密规格 - -**对称加解密** - -支持的对称加密算法： - -|对称加解密算法|分组模式| 字符串参数 | -|---|---|---| -|3DES|ECB|3DES192\|ECB\|[NoPadding\|PKCS5\|PKCS7]| -|3DES|CBC|3DES192\|CBC\|[NoPadding\|PKCS5\|PKCS7]| -|3DES|OFB|3DES192\|OFB\|[NoPadding\|PKCS5\|PKCS7]| -|3DES|CFB|3DES192\|CFB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|ECB|AES[128\|192\|256]\|ECB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CBC|AES[128\|192\|256]\|CBC\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CTR|AES[128\|192\|256]\|CTR\|[NoPadding\|PKCS5\|PKCS7]| -|AES|OFB|AES[128\|192\|256]\|OFB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CFB|AES[128\|192\|256]\|CFB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|GCM|AES[128\|192\|256]\|GCM\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CCM|AES[128\|192\|256]\|CCM\|[NoPadding\|PKCS5\|PKCS7]| - -> **说明：** -> 1. []中只能任选一项。 -> 2. “字符串参数”是“对称加解密算法（含密钥长度）”、“分组模式”、“填充模式”拼接而成，用于在创建对称加解密实例时，指定对称加解密算法规格。 - -**非对称RSA加解密** - -RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 -- 使用NoPadding模式时可以指定的参数: [RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|NoPadding -- 使用PKCS1模式时可以指定的参数: [RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PKCS1 -- 使用PKCS1_OAEP模式时可以指定的参数：[RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PKCS1_OAEP|[MD5|SHA1|SHA224|SHA256|SHA384|SHA512]|[MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] - -> **说明：** []内的参数只能任选一项，非[]内的为固定值 - -### 签名验签规格 - -**RSA签名验签** - -RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 -- 使用PKCS1模式时可以指定的参数: [RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PKCS1|[MD5|SHA1|SHA224|SHA256|SHA384|SHA512] -- 使用PSS模式时可以指定的参数：[RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PSS|[MD5|SHA1|SHA224|SHA256|SHA384|SHA512]|[MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] -> **说明：** []内的参数只能任选一项，非[]内的为固定值 - -**ECDSA签名验签** - -支持的ECDSA参数： - - |非对称密钥算法|支持种类| - |---|---| - |ECC|ECC224| - |ECC|ECC256| - |ECC|ECC384| - |ECC|ECC521| - - |摘要算法|支持种类| - |---|---| - |HASH|SHA1| - |HASH|SHA224| - |HASH|SHA256| - |HASH|SHA384| - |HASH|SHA512| - -### 密钥协商规格 - -**ECDH** - - 支持的ECDH参数： - - |非对称密钥算法|支持种类| - |---|---| - |ECC|ECC224| - |ECC|ECC256| - |ECC|ECC384| - |ECC|ECC521| - -### MD算法规格 -加解密算法库框架当前支持MD5算法 - -### SHA算法规格 -加解密算法库框架当前支持：SHA1，SHA224，SHA256，SHA384，SHA512 +# 加解密算法库框架概述 +加解密算法库框架是一个屏蔽了第三方密码学算法库实现差异的算法框架，提供加解密、签名验签、消息验证码、哈希、安全随机数等相关功能。开发者可以通过调用加解密算法库框架，忽略底层不同三方算法库的差异，实现迅捷开发。 + +> **说明：** 加解密算法库框架仅提供密钥的密码学操作，而不提供密钥管理功能。因此，使用算法库时，需要应用自己来保管密钥（适用于临时会话密钥等仅在内存中使用的场景，或者应用自己实现密钥安全存储的场景）。如果业务需要由系统提供密钥管理功能（密钥存储等），请使用[HUKS部件](huks-overview.md)。 + +## 框架实现原理 +加解密算法库框架提供的组件分为三层：接口层，Framework层和插件层。接口层负责对外提供统一的JS接口，插件层实现针对具体三方算法库的功能，Framework层通过灵活加载插件层的插件适配并屏蔽三方算法库差异。 + +## 基本概念 +**对称密钥** + +对称密钥使用同一个密钥对数据进行加密解密操作。即对称加密算法中，数据发送方使用加密密钥对明文进行特殊加密算法处理后，使其变成复杂的加密密文发送出去。接收方收到密文后，若想解读原文，则需要使用同一个加密密钥以及相同算法的逆算法对密文进行解密，才能使其恢复成可读明文。 + +- **AES加密** + + AES的全称是Advanced Encryption Standard，是最常见的对称加密。AES为分组密码，分组密码也就是把明文分成一组一组的，每组长度相等，每次加密一组数据，直到加密完整个明文。在AES标准规范中，分组长度只能是128位，也就是说，每个分组为16个字节（每个字节8位）。密钥的长度可以使用128位、192位或256位。 +- **3DES加密** + + 3DES，也称为 3DESede 或 TripleDES，是三重数据加密算法，相当于是对每个数据块应用三次DES的对称加密算法，它使用3个64位的密钥对数据块进行三次加密。相比DES，3DES因密钥长度变长，安全性有所提高，但其处理速度不高。因此又出现了AES加密算法，AES较于3DES速度更快、安全性更高。 + +**非对称密钥** + +非对称密钥使用公钥和私钥两个密钥来进行算法操作，公钥对外公开，私钥对外保密。对于加解密操作，一般使用公钥对明文进行加密形成密文，持有私钥的人即可对密文解密形成明文。对于签名验签操作，使用私钥对明文进行签名，公钥持有者可以通过公钥对签名数据做验签，验证数据是否被篡改。 + +- **RSA密钥** + + RSA密钥以极大整数做因数分解的数学难题作为密钥安全性的基石。生成密钥时，首先需要随机出两个大素数p和q，计算n = p * q并将n做为模，再选择一个大于1且小于(p - 1) * (q - 1)的整数e，确保e与(p - 1)*(q - 1)互素，最后计算d，使得e * d - 1为(p - 1)和(q - 1)的倍数，则可得到公钥(n, e)和私钥(n, d)。 + + 算法库框架除提供了默认的双素数RSA密钥生成外，还提供了多素数密钥生成方式，可以在密钥生成时通过指定primes参数（PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5）指定素数个数。多素数密钥的优点是可以减少解密、签名的计算量（中国剩余定理），但相对的劣势是密钥强度会越低，算法库依据OpenSSL的素数使用规则制定了相应规格，具体将在**约束与限制**章节中说明。 +- **ECC密钥** + + ECC是一种基于椭圆曲线数学的公开密钥加密算法，其数学基础是利用椭圆曲线上的有理点构成Abel加法群上椭圆离散对数的计算困难性，算法库框架提供了多种椭圆曲线的ECC密钥生成能力。 + +**加解密** + +- **对称AES加解密** + + 算法库目前提供了AES加解密常用的7种加密模式：ECB、CBC、OFB、CFB、CTR、GCM和CCM。AES为分组加密算法，分组长度大小为128位。实际应用中明文最后一组可能不足128位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： + - NoPadding：不带填充； + - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； + - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； + + > **说明：** ECB、CBC加密模式，明文长度不是128位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即AES加密填充至16字节。 +- **对称3DES加解密** + + 该算法的加解密过程分别是对明文/密文数据进行三次DES加密或解密，得到相应的密文或明文。 + + 算法库目前提供了3DES加解密常用的4种加密模式：ECB、CBC、OFB和CFB。DES为分组加密算法，分组长度大小为64位。实际应用中明文最后一组可能不足64位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： + - NoPadding：不带填充； + - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； + - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； + + > **说明：** ECB、CBC加密模式，明文长度不是64位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即3DES加密填充至8字节。 + +- **非对称RSA加解密** + + 当持有RSA公钥(n, e)和私钥(n, d)后，RSA加密过程为：密文 = 明文 ^ e mod n, 解密过程为：明文 = 密文 ^ d mod n。算法库目前提供了RSA加解密常用的三种模式：PKCS1、PKCS1_OAEP和NoPadding。RSA为块加密算法，加密长度需要在固定长度进行，实际应用中会使用各种padding模式做数据填充。下文中描述了各个padding的区别： + - NoPadding：不带填充，输入的数据必须与RSA钥模一样长，输出数据长度与RSA钥模一样长； + - PKCS1：pkcs1padding V1.5是RSA加解密默认的填充方式，输入的数据必须<=RSA钥模-11，输出数据长度与RSA钥模一样长； + - PKCS1_OAEP：RSA_PKCS1_OAEP_PADDING填充模式是PKCS#1推出的新填充方式，此模式需要设置两个摘要（md和mgf1_md），输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2，输出数据长度与RSA钥模一样长；
+ + **补充说明：** RSA钥模 = (RSA的bits + 7) / 8 + +**签名验签** + +- **RSA签名验签** + + 当持有RSA公钥(n, e)和私钥(n, d)后，RSA签名生成过程为：签名 = 消息 ^ d mod n, 验签过程为：消息 = 签名 ^ d mod n。消息发送方发送数据时，同时发送消息和私钥签名后的签名信息，消息接收方接受到数据后，将签名信息用公钥解密并验证消息是否一致。因发送的消息长度大多大于RSA钥模，因此算法库框架提供了两种padding模式，通过摘要提取消息的散列值再做签名。算法库框架中提供了签名验签相关的两种模式：PKCS1和PSS。下问对两种模式做详细描述： + - PKCS1: pkcs1padding V1.5是RSA加解密默认的填充方式，使用该模式时需要设置摘要（md）； + - PSS: PSS模式是RSA 算法的基础上叠加上一种填充算法，使用该签名算法时需要使用摘要(md)和掩码函数（mgf1_md）; +- **ECDSA** + + 椭圆曲线数字签名算法（ECDSA）是基于椭圆曲线密码（ECC）模拟数字签名算法（DSA）。相比普通的离散对数问题（DLP）和大数分解问题（IFP），椭圆曲线密码的单位比特强度要高于其他公钥体制。算法库框架提供了多种椭圆曲线及摘要算法组合的椭圆曲线数字签名算法（ECDSA）能力。 + +**密钥协商** + +- **ECDH** + + ECDH的全称是椭圆曲线迪菲-赫尔曼秘钥交换，是用来在一个非安全通道中建立起安全的共有加密资料，交换双方可以在不共享任何秘密的情况下协商出一个密钥。算法库框架基于开源算法库提供了多种椭圆曲线的ECDH能力。 + +**摘要** + +消息摘要MD算法是一种能将任意长度的输入消息，通过哈希算法生成长度固定的摘要的算法。消息摘要算法通过其不可逆的特性能被用于敏感信息的加密。消息摘要算法也被称为哈希算法或单向散列算法。 +在摘要算法相同时，生成的摘要值主要有下列特点： + +- 当输入消息相同时，生成摘要序列相同； +- 当输入消息的长度不一致时，生成摘要序列长度固定（摘要长度由算法决定）； +- 当输入消息不一致时，生成摘要序列几乎不会相同（依然存在相同概率，由摘要长度决定相同概率）； + +消息摘要算法主要分为三类：MD，SHA与MAC（详见HMAC章节） +MD算法包括MD2，MD4和MD5。 +SHA算法主要包括SHA1，SHA224，SHA256，SHA384，SHA512。 + +**消息验证码** + +HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息认证码算法。HMAC通过指定摘要算法，以通信双方共享密钥与消息作为输入，生成消息认证码用于检验传递报文的完整性，HMAC生成的消息认证码为固定长度。HMAC在消息摘要算法的基础上增加了密钥的输入，确保了信息的正确性。 + +**随机数** + +随机数在加解密过程中主要用于临时会话密钥的生成与非对称加密算法中密钥的生成。随机数由硬件生成的硬件随机数生成器或由软件生成的伪随机数生成器进行生成。在加解密的场景中，安全随机数生成器需要具备随机性，不可预测性，与不可重现性。密码学安全伪随机数生成器CSPRNG（Cryptography Secure Random Number Generators）生成的随机数满足密码学安全伪随机性 + +- **内部状态**代表随机数生成器内存中的数值，当内部状态相同时，随机数生成器会生成固定的随机数序列 +- **种子**（seed）是一个用来对伪随机数的内部状态进行初始化的数据，随机数生成器通过种子来生成一系列的随机序列。 + + +## 约束与限制 + +- 算法库框架不支持多线程并发操作。 +- 算法库当前只支持OpenSSL。 + +### 密钥生成规格 + +**对称密钥生成规格** + +- 支持的对称密钥生成参数： + + |对称密钥算法|密钥长度（bit）|字符串参数| + |---|---|---| + |3DES|192|3DES192| + |AES|128|AES128| + |AES|192|AES192| + |AES|256|AES256| + + > **说明**：“字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 + +**非对称密钥生成规格** +- **RSA密钥生成** + + 支持的非对称密钥生成参数： + + |非对称密钥类型|素数个数|字符串参数| + |---|---|---| + |RSA512|2|RSA512\|PRIMES_2| + |RSA768|2|RSA768\|PRIMES_2| + |RSA1024|2|RSA1024\|PRIMES_2| + |RSA1024|3|RSA1024\|PRIMES_3| + |RSA2048|2|RSA2048\|PRIMES_2| + |RSA2048|3|RSA2048\|PRIMES_3| + |RSA3072|2|RSA3072\|PRIMES_2| + |RSA3072|3|RSA3072\|PRIMES_3| + |RSA4096|2|RSA4096\|PRIMES_2| + |RSA4096|3|RSA4096\|PRIMES_3| + |RSA4096|4|RSA4096\|PRIMES_4| + |RSA8192|2|RSA8192\|PRIMES_2| + |RSA8192|3|RSA8192\|PRIMES_3| + |RSA8192|4|RSA8192\|PRIMES_4| + |RSA8192|5|RSA8192\|PRIMES_5| + + > **说明**：生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 + +- **ECC密钥生成** + + 支持的非对称密钥生成参数： + + |非对称密钥算法|密钥长度| + |---|---| + |ECC|ECC224| + |ECC|ECC256| + |ECC|ECC384| + |ECC|ECC521| + +### 加解密规格 + +**对称加解密** + +- 支持的对称加密算法： + + |对称加解密算法|分组模式| 字符串参数 | + |---|---|---| + |3DES|ECB|3DES192\|ECB\|[NoPadding\|PKCS5\|PKCS7]| + |3DES|CBC|3DES192\|CBC\|[NoPadding\|PKCS5\|PKCS7]| + |3DES|OFB|3DES192\|OFB\|[NoPadding\|PKCS5\|PKCS7]| + |3DES|CFB|3DES192\|CFB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|ECB|AES[128\|192\|256]\|ECB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CBC|AES[128\|192\|256]\|CBC\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CTR|AES[128\|192\|256]\|CTR\|[NoPadding\|PKCS5\|PKCS7]| + |AES|OFB|AES[128\|192\|256]\|OFB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CFB|AES[128\|192\|256]\|CFB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|GCM|AES[128\|192\|256]\|GCM\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CCM|AES[128\|192\|256]\|CCM\|[NoPadding\|PKCS5\|PKCS7]| + +> **说明：** +> +> 1. []中只能任选一项。 +> 2. “字符串参数”是“对称加解密算法（含密钥长度）”、“分组模式”、“填充模式”拼接而成，用于在创建对称加解密实例时，指定对称加解密算法规格。 + +**非对称RSA加解密** + +RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 +- 使用NoPadding模式时可以指定的参数: + + |非对称密钥类型| 填充模式 | 字符串参数 | + |---|---|---| + |RSA512|NoPadding|RSA512\|NoPadding| + |RSA768|NoPadding|RSA768\|NoPadding| + |RSA1024|NoPadding|RSA1024\|NoPadding| + |RSA2048|NoPadding|RSA2048\|NoPadding| + |RSA3072|NoPadding|RSA3072\|NoPadding| + |RSA4096|NoPadding|RSA4096\|NoPadding| + |RSA8192|NoPadding|RSA8192\|NoPadding| + +- 使用PKCS1模式时可以指定的参数: + + |非对称密钥类型| 填充模式 | 字符串参数 | + |---|---|---| + |RSA512|PKCS1|RSA512\|PKCS1| + |RSA768|PKCS1|RSA768\|PKCS1| + |RSA1024|PKCS1|RSA1024\|PKCS1| + |RSA2048|PKCS1|RSA2048\|PKCS1| + |RSA3072|PKCS1|RSA3072\|PKCS1| + |RSA4096|PKCS1|RSA4096\|PKCS1| + |RSA8192|PKCS1|RSA8192\|PKCS1| + +- 使用PKCS1_OAEP模式时可以指定的参数： + > **说明：** + > + > 1.[]内的参数只能任选一项，非[]内的为固定值； + > 2.使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成字符串。 + > 例如："RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256" + + | 非对称密钥类型 | 填充模式 | 摘要 | 掩码摘要 | + |---|---|---|---| + |RSA512|PKCS1_OAEP|MD5| [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224] + |RSA768|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA768|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA768|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]| + |RSA1024|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA2048|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512 ]| + |RSA8192|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + + +### 签名验签规格 + +**RSA签名验签** + +RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 +- 使用PKCS1模式时可以指定的参数: + + | 非对称密钥类型 | 填充模式 | 摘要 | 字符串参数 | + |---|---|---|---| + |RSA512|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384]|RSA512\|PKCS1\| [MD5\|SHA1\|SHA224\|SHA256\|SHA384]| + |RSA768|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA768\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA1024|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA1024\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA2048|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA2048\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA3072|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA3072\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA4096|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA4096\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA8192|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA8192\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + +- 使用PSS模式时可以指定的参数： + > **说明：** + > + > 1.[]内的参数只能任选一项，非[]内的为固定值； + > 2.使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成字符串。 + > 例如："RSA2048|PSS|SHA256|MGF1_SHA256" + + | 非对称密钥类型 | 填充模式 | 摘要 | 掩码摘要 | + |---|---|---|---| + |RSA512|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]|RSA512\|PSS\|SHA256\|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]| + |RSA768|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA768|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA768|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]| + |RSA1024|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA512| [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA2048|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA512| [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + +**ECDSA签名验签** + +- 支持的ECDSA参数： + + |非对称密钥算法|支持种类| + |---|---| + |ECC|ECC224| + |ECC|ECC256| + |ECC|ECC384| + |ECC|ECC521| + + |摘要算法|支持种类| + |---|---| + |HASH|SHA1| + |HASH|SHA224| + |HASH|SHA256| + |HASH|SHA384| + |HASH|SHA512| + +### 密钥协商规格 + +**ECDH** + +- 支持的ECDH参数： + + |非对称密钥算法|支持种类| + |---|---| + |ECC|ECC224| + |ECC|ECC256| + |ECC|ECC384| + |ECC|ECC521| + +### MD消息摘要算法规格 +- 加解密算法库框架当前支持的MD算法参数： + + |摘要算法|支持种类| + |---|---| + |HASH|SHA1| + |HASH|SHA224| + |HASH|SHA256| + |HASH|SHA384| + |HASH|SHA512| + |HASH|MD5| + +### HMAC消息认证码算法规格 +- 加解密算法库框架当前支持的HMAC算法参数： + + |摘要算法|支持种类| + |---|---| + |HASH|SHA1| + |HASH|SHA224| + |HASH|SHA256| + |HASH|SHA384| + |HASH|SHA512| -- GitLab