!14358 【回合1018】crypto framework API ParamsSpec change attribute name from "algoName" to "algName"

Merge pull request !14358 from 胡啸天/monthly_20221018

zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md

@@ -918,10 +918,10 @@ rand.generateRandom(12, (err, randData) => {
 
 | 名称     | 类型   | 可读 | 可写 | 说明                    |
 | -------- | ------ | ---- | ---- | ----------------------- |
-| algoName | string | 是   | 是   | 指明对称加解密参数的算法模式。可选值如下:<br/>- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式<br/>- "GcmParamsSpec": 适用于GCM模式<br/>- "CcmParamsSpec": 适用于CCM模式 |
+| algName | string | 是   | 是   | 指明对称加解密参数的算法模式。可选值如下:<br/>- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式<br/>- "GcmParamsSpec": 适用于GCM模式<br/>- "CcmParamsSpec": 适用于CCM模式 |
 
 > **说明：**
-> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algoName参数，使算法库在init()时知道传入的是哪种子类对象。
+> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。
 
 ## IvParamsSpec
 
@@ -934,7 +934,7 @@ rand.generateRandom(12, (err, randData) => {
 | iv   | [DataBlob](#datablob) | 是   | 是   | 指明加解密参数iv。常见取值如下：<br/>- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节<br/>- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 |
 
 > **说明：**
-> 传入[init()](#init-2)方法前需要指定其algoName属性（来源于父类[ParamsSpec](#paramsspec)）。
+> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。
 
 ## GcmParamsSpec
 
@@ -949,7 +949,7 @@ rand.generateRandom(12, (err, randData) => {
 | authTag | [DataBlob](#datablob) | 是   | 是   | 指明加解密参数authTag，长度为16字节。<br/>采用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
 
@@ -964,7 +964,7 @@ rand.generateRandom(12, (err, randData) => {
 | authTag | [DataBlob](#datablob) | 是   | 是   | 指明加解密参数authTag，长度为12字节。<br/>采用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
 
@@ -1228,8 +1228,8 @@ generateSymKey(callback : AsyncCallback\<SymKey>) : 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\<SymKey>
 
 ```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 => {
@@ -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}`);

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}`);

zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.7/changelog-security.md

+# 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;
+}
+ ```
+
+**适配指导**
+
+对ParamsSpec以及其子类IvParamsSpec，GcmParamsSpec与CcmParamsSpec，使用这些对象作为参数或返回值时，其属性名需要从algoName更改为algName。
+ ```ts
+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;
+}
+ ```   
+详细查看API参考中ParamsSpec对应的接口适配指南：
+[加解密算法库框架-ParamsSpec-API参考](../../../application-dev/reference/apis/js-apis-cryptoFramework.md#paramsspec)
\ No newline at end of file