From 494636444377a5a8b94854804d284cbb1adad13c Mon Sep 17 00:00:00 2001 From: hxt_lucky Date: Mon, 6 Feb 2023 16:55:18 +0800 Subject: [PATCH] change crypto framework API ParamSpec attribute from algoName to algName Signed-off-by: hxt_lucky --- .../reference/apis/js-apis-cryptoFramework.md | 66 +++++++++---------- .../security/cryptoFramework-guidelines.md | 18 ++--- .../OpenHarmony_4.0.3.2/changelog-security.md | 42 ++++++++++++ 3 files changed, 84 insertions(+), 42 deletions(-) create mode 100644 zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-security.md 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 93ee99fb63..64c706d77b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @@ -91,7 +91,7 @@ Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密 ### init -init(key : SymKey, callback : AsyncCallback\) : void; +init(key : SymKey, callback : AsyncCallback\) : void; 使用对称密钥初始化Mac计算 @@ -324,7 +324,7 @@ var mac; try { mac = cryptoFramework.createMac("SHA256"); } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); } var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { @@ -382,7 +382,7 @@ var mac; try { mac = cryptoFramework.createMac("SHA256"); } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); } console.error("Mac algName is: " + mac.algName); @@ -769,7 +769,7 @@ import cryptoFramework from "@ohos.security.cryptoFramework" try { var rand = cryptoFramework.createRandom(); } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); } ``` @@ -808,7 +808,7 @@ var rand; try { rand = cryptoFramework.createRandom(); } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); } rand.generateRandom(12, (err, randData) => { if (err) { @@ -918,10 +918,10 @@ rand.generateRandom(12, (err, randData) => { | 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | ------ | ---- | ---- | ----------------------- | -| algoName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | +| algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | -> **说明：** -> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algoName参数，使算法库在init()时知道传入的是哪种子类对象。 +> **说明：** +> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 ## IvParamsSpec @@ -933,8 +933,8 @@ rand.generateRandom(12, (err, randData) => { | ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | | iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：
- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节
- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algoName属性（来源于父类[ParamsSpec](#paramsspec)）。 +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 ## GcmParamsSpec @@ -948,8 +948,8 @@ rand.generateRandom(12, (err, randData) => { | 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)方法前需要指定其algoName属性（来源于父类[ParamsSpec](#paramsspec)）。 +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 ## CcmParamsSpec @@ -963,8 +963,8 @@ rand.generateRandom(12, (err, randData) => { | 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)方法前需要指定其algoName属性（来源于父类[ParamsSpec](#paramsspec)）。 +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 ## CryptoMode @@ -983,7 +983,7 @@ rand.generateRandom(12, (err, randData) => { ### 属性 -**系统能力：** SystemCapability.Security.CryptoFramework +**系统能力：** SystemCapability.Security.CryptoFramework | 名称 | 类型 | 可读 | 可写 | 说明 | | ------- | ------ | ---- | ---- | ---------------------------- | @@ -1055,7 +1055,7 @@ console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出全 ### 属性 -**系统能力：** SystemCapability.Security.CryptoFramework +**系统能力：** SystemCapability.Security.CryptoFramework | 名称 | 类型 | 可读 | 可写 | 说明 | | ------- | ------ | ---- | ---- | ---------------------------- | @@ -1099,7 +1099,7 @@ console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); ### 属性 -**系统能力：** SystemCapability.Security.CryptoFramework +**系统能力：** SystemCapability.Security.CryptoFramework | 名称 | 类型 | 可读 | 可写 | 说明 | | ------- | ------ | ---- | ---- | ---------------------------- | @@ -1228,8 +1228,8 @@ generateSymKey(callback : AsyncCallback\) : void ```js import cryptoFramework from '@ohos.security.cryptoFramework'; -let symAlgoName = '3DES192'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName); +let symAlgName = '3DES192'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); symKeyGenerator.generateSymKey((err, symKey) => { if (err) { console.error(`Generate symKey failed, ${err.code}, ${err.message}`); @@ -1263,8 +1263,8 @@ generateSymKey() : Promise\ ```js import cryptoFramework from '@ohos.security.cryptoFramework'; -let symAlgoName = 'AES128'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName); +let symAlgName = 'AES128'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); symKeyGenerator.generateSymKey() .then(symKey => { console.info(`Generate symKey success, algName: ${symKey.algName}`); @@ -1308,8 +1308,8 @@ function genKeyMaterialBlob() { return {data : keyMaterial}; } -let symAlgoName = '3DES192'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName); +let symAlgName = '3DES192'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); let keyMaterialBlob = genKeyMaterialBlob(); symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => { if (err) { @@ -1360,8 +1360,8 @@ function genKeyMaterialBlob() { return {data : keyMaterial}; } -let symAlgoName = '3DES192'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName); +let symAlgName = '3DES192'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); let keyMaterialBlob = genKeyMaterialBlob(); symKeyGenerator.convertKey(keyMaterialBlob) .then(symKey => { @@ -1582,7 +1582,7 @@ createCipher(transformation : string) : Cipher | -------------- | ------ | ---- | ------------------------------------------------------------ | | 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对象进行加解密操作）。 @@ -1597,10 +1597,10 @@ createCipher(transformation : string) : Cipher ```javascript import cryptoFramework from "@ohos.security.cryptoFramework" -let cipherAlgoName = '3DES192|ECB|PKCS7'; +let cipherAlgName = '3DES192|ECB|PKCS7'; var cipher; try { - cipher = cryptoFramework.createCipher(cipherAlgoName); + cipher = cryptoFramework.createCipher(cipherAlgName); console.info(`cipher algName: ${cipher.algName}`); } catch (error) { console.error(`createCipher failed, ${error.code}, ${error.message}`); @@ -1718,7 +1718,7 @@ 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操作。 @@ -1775,7 +1775,7 @@ 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操作。 @@ -1841,7 +1841,7 @@ doFinal(data : DataBlob, callback : AsyncCallback\) : void （2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过注册回调函数获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 -> **说明：** +> **说明：** > 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 > 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 @@ -1893,7 +1893,7 @@ doFinal(data : DataBlob) : Promise\ （2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过Promise获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 -> **说明：** +> **说明：** > 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 > 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 @@ -1993,7 +1993,7 @@ keyGenPromise.then(rsaKeyPair => { }); ``` -> **说明：** +> **说明：** > 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 ## cryptoFramework.createSign diff --git a/zh-cn/application-dev/security/cryptoFramework-guidelines.md b/zh-cn/application-dev/security/cryptoFramework-guidelines.md index 562bef2ff6..0c697abe1d 100644 --- a/zh-cn/application-dev/security/cryptoFramework-guidelines.md +++ b/zh-cn/application-dev/security/cryptoFramework-guidelines.md @@ -249,7 +249,7 @@ function genGcmParamsSpec() { 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, algoName : "GcmParamsSpec"}; + let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; return gcmParamsSpec; } @@ -296,8 +296,8 @@ function testAesGcm() { }, 10) }).then(() => { // 生成对称密钥生成器 - let symAlgoName = 'AES128'; - let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName); + let symAlgName = 'AES128'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); if (symKeyGenerator == null) { console.error('createSymKeyGenerator failed'); return; @@ -309,9 +309,9 @@ function testAesGcm() { globalGcmParams = genGcmParamsSpec(); // 生成加解密生成器 - let cipherAlgoName = 'AES128|GCM|PKCS7'; + let cipherAlgName = 'AES128|GCM|PKCS7'; try { - globalCipher = cryptoFramework.createCipher(cipherAlgoName); + globalCipher = cryptoFramework.createCipher(cipherAlgName); console.info(`cipher algName: ${globalCipher.algName}`); } catch (error) { console.error(`createCipher failed, ${error.code}, ${error.message}`); @@ -409,8 +409,8 @@ function genKeyMaterialBlob() { // 3DES ECB模式示例，采用已有数据生成密钥（callback写法） function test3DesEcb() { // 生成对称密钥生成器 - let symAlgoName = '3DES192'; - let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgoName); + let symAlgName = '3DES192'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); if (symKeyGenerator == null) { console.error('createSymKeyGenerator failed'); return; @@ -418,9 +418,9 @@ function test3DesEcb() { console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); // 生成加解密生成器 - let cipherAlgoName = '3DES192|ECB|PKCS7'; + let cipherAlgName = '3DES192|ECB|PKCS7'; try { - globalCipher = cryptoFramework.createCipher(cipherAlgoName); + globalCipher = cryptoFramework.createCipher(cipherAlgName); console.info(`cipher algName: ${globalCipher.algName}`); } catch (error) { console.error(`createCipher failed, ${error.code}, ${error.message}`); diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-security.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-security.md new file mode 100644 index 0000000000..1d853d92b2 --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-security.md @@ -0,0 +1,42 @@ +# security子系统ChangeLog + +## cl.security.1 ParamsSpec属性名变更为algName。 +结构体ParamsSpec的属性algoName由于API命名统一，名称更改为algName。 + +**变更影响** + +影响已发布的JS接口，对ParamsSpec以及其子类IvParamsSpec，GcmParamsSpec与CcmParamsSpec，使用这些对象作为参数或返回值时，其属性名需要更改为algName。 +应用需要进行适配，才可以在新版本SDK环境正常编译通过。 + +**关键的接口/组件变更** + +修改前的接口原型： + + ```ts +interface ParamsSpec { + /** + * Indicates the algorithm name. Should be set before initialization of a cipher object. + * @type { string } + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + algoName : string; +} + ``` +修改后的接口原型： + + ```ts +interface ParamsSpec { + /** + * Indicates the algorithm name. Should be set before initialization of a cipher object. + * @type { string } + * @syscap SystemCapability.Security.CryptoFramework + * @since 9 + */ + algName : string; +} + ``` + +**适配指导** +查看API参考中ParamsSpec对应的接口适配指南： +[加解密算法库框架-API参考](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md) \ No newline at end of file -- GitLab