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 8c50f6c5802894bb1be14347322c3f53e8631f34..7f94ed2d53385f476881ce819528c68b6f719bb1 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @@ -8,7 +8,7 @@ ## 导入模块 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" ``` @@ -46,7 +46,8 @@ buffer数组。 | ------- | ------ | ---- | ---- | ------------------------------------------------------------ | | algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | -> **说明：** +> **说明：** +> > 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 ## IvParamsSpec @@ -59,7 +60,8 @@ buffer数组。 | ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | | iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：
- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节
- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | -> **说明：** +> **说明：** +> > 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 ## GcmParamsSpec @@ -74,7 +76,8 @@ buffer数组。 | 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 @@ -89,7 +92,8 @@ buffer数组。 | 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 @@ -351,7 +355,8 @@ getEncoded(): DataBlob 以同步方法，获取密钥数据的字节流。密钥可以为对称密钥，公钥或者私钥。其中，公钥格式满足ASN.1语法、X.509规范、DER编码格式；私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。 -> **说明：**
+> **说明：** +> > RSA算法使用密钥参数生成私钥时，私钥对象不支持getEncoded。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -364,7 +369,8 @@ getEncoded(): DataBlob **错误码：** -> **说明：**
+> **说明：** +> > 从API version 10开始，该接口支持抛出错误码。 | 错误码ID | 错误信息 | @@ -535,9 +541,10 @@ console.info("ecc item --- p: " + p.toString(16)); 非对称密钥对，包含：公钥与私钥。
可以通过非对称密钥生成器[AsyKeyGenerator](#asykeygenerator)、[AsyKeyGeneratorBySpec](#asykeygeneratorbyspec10)来生成。 -> **说明：** -> -> KeyPair对象中的pubKey对象和priKey对象，作为KeyPair对象中的一个参数存在，当离开KeyPair对象作用域时，其内部对象可能被析构。
业务方使用时应持有KeyPair对象的引用，而非内部pubKey或priKey对象的引用。 +> **说明：** +> +> KeyPair对象中的pubKey对象和priKey对象，作为KeyPair对象中的一个参数存在，当离开KeyPair对象作用域时，其内部对象可能被析构。
+> 业务方使用时应持有KeyPair对象的引用，而非内部pubKey或priKey对象的引用。 ### 属性 @@ -787,12 +794,12 @@ createAsyKeyGenerator(algName: string): AsyKeyGenerator | 错误码ID | 错误信息 | | -------- | ---------------------- | | 401 | invalid parameters. | -| 801 | this operation is not supported. | -| 17620001 | memory error. | +| 80110+ | this operation is not supported. | +| 1762000110+ | memory error. | **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); @@ -834,7 +841,7 @@ generateKeyPair(callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); @@ -847,7 +854,6 @@ asyKeyGenerator.generateKeyPair((err, keyPair) => { }) ``` - ### generateKeyPair generateKeyPair(): Promise\ @@ -872,7 +878,7 @@ generateKeyPair(): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); @@ -910,7 +916,7 @@ convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" 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]); @@ -1010,7 +1016,7 @@ createAsyKeyGeneratorBySpec(asyKeySpec: AsyKeySpec): AsyKeyGeneratorBySpec **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 设置DSA1024中公私钥都包含的公共参数 @@ -1077,7 +1083,7 @@ generateKeyPair(callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyPairSpec; // asyKeyPairSpec为全量密钥参数，此处省略生成过程 @@ -1115,7 +1121,7 @@ generateKeyPair(): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyPairSpec; // asyKeyPairSpec为全量密钥参数，此处省略生成过程 @@ -1152,7 +1158,7 @@ generatePriKey(callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyPairSpec; // asyKeyPairSpec为全量密钥参数 @@ -1190,7 +1196,7 @@ generatePriKey(): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyPairSpec; // asyKeyPairSpec为全量密钥参数 @@ -1227,7 +1233,7 @@ generatePubKey(callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyPairSpec; // asyKeyPairSpec为全量密钥参数，此处省略生成过程 @@ -1265,7 +1271,7 @@ generatePubKey(): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let asyKeyPairSpec; // asyKeyPairSpec为全量密钥参数，此处省略生成过程 @@ -1292,7 +1298,8 @@ 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对象进行加解密操作）。 @@ -1312,7 +1319,7 @@ createCipher(transformation: string): Cipher **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let cipherAlgName = '3DES192|ECB|PKCS7'; @@ -1438,9 +1445,12 @@ 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#使用加解密操作)”。 +> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
+> 算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，采用多次update的方式传入数据。
+> AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 > 3. RSA非对称加解密不支持update操作。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -1496,9 +1506,12 @@ 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#使用加解密操作)”。 +> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
+> 算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，可以采用多次update的方式传入数据。
+> AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 > 3. RSA非对称加解密不支持update操作。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -1563,7 +1576,8 @@ 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等。 > 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 @@ -1618,7 +1632,8 @@ 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等。 > 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 @@ -1668,7 +1683,7 @@ cipher.doFinal(data) **使用RSA加密的callback完整示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" function stringToUint8Array(str) { @@ -1695,7 +1710,7 @@ rsaGenerator.generateKeyPair(function (err, keyPair) { **使用RSA加密的promise完整示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" function stringToUint8Array(str) { @@ -1721,7 +1736,8 @@ keyGenPromise.then(rsaKeyPair => { }); ``` -> **说明：** +> **说明：** +> > 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 ### setCipherSpec10+ @@ -1750,7 +1766,7 @@ setCipherSpec(itemType: CipherSpecItem, itemValue: Uint8Array): void **示例：** -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; let cipher; // 此处省略生成Cipher实例的过程 @@ -1789,7 +1805,7 @@ getCipherSpec(itemType: CipherSpecItem): string | Uint8Array **示例：** -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; let cipher; // 此处省略生成Cipher实例的过程 @@ -1826,7 +1842,7 @@ Sign实例生成。
支持的规格详见框架概述“[签名验签规格] **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); @@ -1919,8 +1935,11 @@ update(data: DataBlob, callback: AsyncCallback\): void 追加待签名数据，通过注册回调函数完成更新。
必须在对[Sign](#sign)实例使用[init()](#init-2)初始化后，才能使用本函数。 -> **说明：** -> 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[sign](#sign-1)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的签名操作，采用多次update的方式传入数据，避免一次性申请过大内存。
签名使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 +> **说明：** +> +> 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[sign](#sign-1)）或多次调用update。
+> 算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的签名操作，采用多次update的方式传入数据，避免一次性申请过大内存。
+> 签名使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -1946,8 +1965,11 @@ update(data: DataBlob): Promise\ 追加待签名数据，通过promise方式完成更新。
必须在对[Sign](#sign)实例使用[init()](#init-3)初始化后，才能使用本函数。 -> **说明：** -> 根据数据量，可以不调用update（即[init](#init-3)完成后直接调用[sign](#sign-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的签名操作，采用多次update的方式传入数据，避免一次性申请过大内存。
签名使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 +> **说明：** +> +> 根据数据量，可以不调用update（即[init](#init-3)完成后直接调用[sign](#sign-2)）或多次调用update。
+> 算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的签名操作，采用多次update的方式传入数据，避免一次性申请过大内存。
+> 签名使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -2027,7 +2049,7 @@ sign(data: DataBlob): Promise\ **callback示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" function stringToUint8Array(str) { @@ -2066,7 +2088,7 @@ function signMessageCallback() { **promise示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" function stringToUint8Array(str) { @@ -2131,7 +2153,7 @@ setSignSpec(itemType: SignSpecItem, itemValue: number): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let signer; // 此处省略生成Sign实例的过程 @@ -2170,7 +2192,7 @@ getSignSpec(itemType: SignSpecItem): string | number **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let signer; // 此处省略生成Sign实例的过程 @@ -2207,7 +2229,7 @@ Verify实例生成。
支持的规格详见框架概述“[签名验签规 **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let verifyer1 = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); @@ -2294,8 +2316,11 @@ update(data: DataBlob, callback: AsyncCallback\): void 追加待验签数据，通过注册回调函数完成更新。
必须在对[Verify](#verify)实例使用[init()](#init-4)初始化后，才能使用本函数。 -> **说明：** -> 根据数据量，可以不调用update（即[init](#init-4)完成后直接调用[verify](#verify-1)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的验签操作，采用多次update的方式传入数据，避免一次性申请过大内存。
验签使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 +> **说明：** +> +> 根据数据量，可以不调用update（即[init](#init-4)完成后直接调用[verify](#verify-1)）或多次调用update。
+> 算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的验签操作，采用多次update的方式传入数据，避免一次性申请过大内存。
+> 验签使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -2321,8 +2346,11 @@ update(data: DataBlob): Promise\ 追加待验签数据，通过Promise方式完成更新。
必须在对[Verify](#verify)实例使用[init()](#init-5)初始化后，才能使用本函数。 -> **说明：** -> 根据数据量，可以不调用update（即[init](#init-5)完成后直接调用[verify](#verify-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的验签操作，采用多次update的方式传入数据，避免一次性申请过大内存。
验签使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 +> **说明：** +> +> 根据数据量，可以不调用update（即[init](#init-5)完成后直接调用[verify](#verify-2)）或多次调用update。
+> 算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的验签操作，采用多次update的方式传入数据，避免一次性申请过大内存。
+> 验签使用多次update操作的示例代码详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -2404,7 +2432,7 @@ verify(data: DataBlob, signatureData: DataBlob): Promise\ **callback示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 @@ -2423,7 +2451,7 @@ verifyer.init(globalKeyPair.pubKey, function (err, data) { **promise示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 @@ -2469,7 +2497,7 @@ setVerifySpec(itemType: SignSpecItem, itemValue: number): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let verifyer; // 此处省略生成Verify实例的过程 @@ -2510,7 +2538,7 @@ getVerifySpec(itemType: SignSpecItem): string | number **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let verifyer; // 此处省略生成Verify实例的过程 @@ -2547,7 +2575,7 @@ KeyAgreement实例生成。
支持的规格详见框架概述“[密钥协 **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); @@ -2623,7 +2651,7 @@ generateSecret(priKey: PriKey, pubKey: PubKey): Promise\ **callback示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 @@ -2639,7 +2667,7 @@ keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function **promise示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 @@ -2681,7 +2709,7 @@ createMd(algName: string): Md **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var md; @@ -2711,7 +2739,8 @@ update(input: DataBlob, callback: AsyncCallback\): void 传入消息进行Md更新计算。 -> **说明：** +> **说明：** +> > Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -2732,7 +2761,7 @@ update(input: DataBlob, callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var md; @@ -2757,7 +2786,8 @@ update(input: DataBlob): Promise\ 传入消息进行Md更新计算。 -> **说明：** +> **说明：** +> > Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -2781,7 +2811,7 @@ update(input: DataBlob): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var md; @@ -2822,7 +2852,7 @@ digest(callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var md; @@ -2871,7 +2901,7 @@ digest(): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var md; @@ -2916,7 +2946,7 @@ getMdLength(): number **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var md; @@ -2970,7 +3000,7 @@ createMac(algName: string): Mac **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var mac; @@ -3018,7 +3048,7 @@ init(key: SymKey, callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var mac; @@ -3070,7 +3100,7 @@ init(key: SymKey): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var mac; @@ -3099,7 +3129,8 @@ update(input: DataBlob, callback: AsyncCallback\): void 传入消息进行Mac更新计算。 -> **说明：** +> **说明：** +> > Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -3120,7 +3151,7 @@ update(input: DataBlob, callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var KeyBlob; @@ -3155,7 +3186,8 @@ update(input: DataBlob): Promise\ 传入消息进行Mac更新计算。 -> **说明：** +> **说明：** +> > Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 **系统能力：** SystemCapability.Security.CryptoFramework @@ -3181,7 +3213,7 @@ update(input: DataBlob): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var mac; @@ -3231,7 +3263,7 @@ doFinal(callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var KeyBlob; @@ -3290,7 +3322,7 @@ doFinal(): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var mac; @@ -3343,7 +3375,7 @@ getMacLength(): number **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var mac; @@ -3398,7 +3430,7 @@ createRandom(): Random **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" try { @@ -3445,7 +3477,7 @@ generateRandom(len: number, callback: AsyncCallback\): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var rand; @@ -3493,7 +3525,7 @@ generateRandom(len: number): Promise\ **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var rand; @@ -3541,7 +3573,7 @@ generateRandomSync(len: number): DataBlob **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var rand; @@ -3583,7 +3615,7 @@ setSeed(seed: DataBlob): void **示例：** -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" var rand; diff --git a/zh-cn/application-dev/security/cryptoFramework-guidelines.md b/zh-cn/application-dev/security/cryptoFramework-guidelines.md index 8522b2a10e2787f99e0e8aa3c8bda3bc1547c411..50c7abdba951998d3691c26a57222f78ff44d619 100644 --- a/zh-cn/application-dev/security/cryptoFramework-guidelines.md +++ b/zh-cn/application-dev/security/cryptoFramework-guidelines.md @@ -1,6 +1,6 @@ # 加解密算法库框架开发指导 -> **说明** +> **说明：** > > 本开发指导基于API version 9，OH SDK版本3.2.7以上，适用于JS语言开发 @@ -15,8 +15,10 @@ 3. 根据指定数据生成算法库密钥对象（也就是将外部或存储的二进制数据转换为算法库的密钥对象）。该对象可用于后续的加解密等操作。 4. 获取算法库密钥对象的二进制数据，用于存储或传输。 5. 对于非对称密钥，获取密钥对象的参数属性，用于存储或运输。 -> **说明**：密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 +> **说明：** +> +> 密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 ### 接口及参数说明 @@ -40,15 +42,16 @@ | Key | getEncoded() : DataBlob; | 获取Key密钥对象的二进制数据（Key的子类实例包括对称密钥SymKey、公钥PubKey、私钥PriKey） | ### 随机生成RSA密钥对，并获得二进制数据 + 示例1：随机生成非对称密钥KeyPair，并获得二进制数据（场景1、3） -1. 创建非对称密钥生成器； -2. 通过非对称密钥生成器随机生成非对称密钥； -3. 获取密钥对象的二进制数据； +1. 创建非对称密钥生成器。 +2. 通过非对称密钥生成器随机生成非对称密钥。 +3. 获取密钥对象的二进制数据。 以使用Promise方式随机生成RSA密钥（1024位，素数个数为2）为例： -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; function generateAsyKey() { @@ -70,15 +73,16 @@ function generateAsyKey() { ``` ### 随机生成AES密钥，并获得二进制数据 + 示例2：随机生成对称密钥SymKey，并获得二进制数据（场景1、3） -1. 创建对称密钥生成器； -2. 通过对称密钥生成器随机生成对称密钥； -3. 获取算法库密钥对象的二进制数据； +1. 创建对称密钥生成器。 +2. 通过对称密钥生成器随机生成对称密钥。 +3. 获取算法库密钥对象的二进制数据。 以使用Promise方式随机生成AES密钥（256位）为例： -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; // 字节流以16进制输出 @@ -108,7 +112,7 @@ function testGenerateAesKey() { 1. 获取RSA公钥或私钥二进制数据，公钥需满足ASN.1语法、X.509规范、DER编码格式，私钥需满足ASN.1语法、PKCS#8规范、DER编码格式。 2. 创建AsyKeyGenerator对象，调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; function convertAsyKey() { @@ -124,18 +128,18 @@ function convertAsyKey() { } ``` -**说明** - - 当前convertKey操作，公钥只支持转换满足X.509规范的DER格式，私钥只支持PKCS#8规范的DER格式； - +> **说明：** +> +> 当前convertKey操作，公钥只支持转换满足X.509规范的DER格式，私钥只支持PKCS#8规范的DER格式。 ### 根据ECC密钥二进制数据，生成密钥对 + 示例4：根据指定的ECC非对称密钥二进制数据，生成KeyPair对象（场景2、3） 1. 获取ECC二进制密钥数据，封装成DataBlob对象。 2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 -```javascript +```js 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]); @@ -152,15 +156,16 @@ function convertEccAsyKey() { ``` ### 根据3DES密钥二进制数据，生成密钥 + 示例5：根据指定的对称密钥二进制数据，生成SymKey对象（场景2、3） -1. 创建对称密钥生成器； -2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象； -3. 获取算法库密钥对象的二进制数据； +1. 创建对称密钥生成器。 +2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象。 +3. 获取算法库密钥对象的二进制数据。 以使用callback方式生成3DES密钥（3DES密钥只能为192位）为例： -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; // 字节流以16进制输出 @@ -201,19 +206,20 @@ function testConvertAesKey() { } } ``` + ## 非对称密钥对象根据参数生成与获取参数 ### 场景说明 使用密钥生成操作中，典型的场景有： - 1. 根据非对称密钥参数生成指定的算法库密钥对象。该对象可用于后续的加解密等操作。 2. 对于非对称密钥，获取密钥对象的参数属性，用于存储或运输。 -> **说明**：
+ +> **说明：** +> > 1. 从API version 10开始， 支持使用密钥参数来生成非对称密钥。 > 2. 非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。非对称密钥参数具体可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - ### 接口及参数说明 详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md#asykeygeneratorbyspec10)。 @@ -232,14 +238,16 @@ function testConvertAesKey() { | PubKey | getAsyKeySpec(itemType: AsyKeySpecItem): bigint \| string \| number; | 获取非对称密钥公钥对象的密钥参数属性 | ### 根据参数生成ECC密钥对，并获得密钥参数开发步骤 + 示例1：根据参数生成ECC密钥对，并获得密钥参数（场景1、2） -1. 创建根据密钥参数的非对称密钥生成器； -2. 通过根据密钥参数的非对称密钥生成器由指定密钥参数生成非对称密钥对； -3. 获取密钥对象的密钥参数属性； +1. 创建根据密钥参数的非对称密钥生成器。 +2. 通过根据密钥参数的非对称密钥生成器由指定密钥参数生成非对称密钥对。 +3. 获取密钥对象的密钥参数属性。 以使用Promise方式根据密钥参数生成ECC密钥为例： -```javascript + +```js import cryptoFramework from '@ohos.security.cryptoFramework'; // 打印bigint信息 @@ -346,14 +354,15 @@ function testEccUseCommKeySpecGet() ``` ### 根据参数生成RSA公钥，并获得密钥参数属性 + 示例2：根据参数生成RSA公钥，并获得密钥参数（场景1、2） -1. 创建根据密钥参数的非对称密钥生成器； -2. 通过根据密钥参数的非对称密钥生成器由指定密钥参数生成非对称密钥的公钥； -3. 获取密钥对象的密钥参数属性； +1. 创建根据密钥参数的非对称密钥生成器。 +2. 通过根据密钥参数的非对称密钥生成器由指定密钥参数生成非对称密钥的公钥。 +3. 获取密钥对象的密钥参数属性。 以使用Callback方式根据密钥参数生成RSA公钥为例： -``` javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; // RSA公钥密钥参数生成函数 @@ -406,11 +415,12 @@ function rsaUsePubKeySpecGetCallback() { ### 场景说明 在数据存储或传输场景中，可以使用加解密操作用于保证数据的机密性，防止敏感数据泄露。使用加解密操作中，典型的场景有： -1. 使用对称密钥的加解密操作 -2. 使用非对称密钥的加解密操作 -3. 使用RSA, PKCS1_OAEP填充模式时，获取、设置CipherSpecItem参数 +1. 使用对称密钥的加解密操作。 +2. 使用非对称密钥的加解密操作。 +3. 使用RSA, PKCS1_OAEP填充模式时，获取、设置CipherSpecItem参数。 -> **说明**：
+> **说明：** +> > 1. 从API version 10开始， 支持RSA使用PKCS1_OAEP填充模式时，获取、设置[CipherSpecItem](../reference/apis/js-apis-cryptoFramework.md#cipherspecitem10)参数。 > 2. 从API version 10开始，支持加解密时字符串参数不带密钥长度。 @@ -441,7 +451,7 @@ function rsaUsePubKeySpecGetCallback() { 3. 创建加解密生成器。 4. 通过加解密生成器加密或解密数据。 -``` javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; var globalCipher; @@ -570,7 +580,7 @@ function testAesGcm() { 示例2：使用3DES对称密钥的加解密操作 1. 创建对称密钥生成器。 -2. 通过已有二进制数据生成密钥 +2. 通过已有二进制数据生成密钥。 3. 创建加解密生成器。 4. 通过加解密生成器加密或解密数据。 @@ -703,13 +713,13 @@ function test3DesEcb() { 示例3：使用AES对称密钥的分段update()加解密操作 1. 创建对称密钥生成器。 -2. 通过已有二进制数据生成密钥 +2. 通过已有二进制数据生成密钥。 3. 创建加解密生成器。 4. 通过加解密生成器加密或解密数据。 以AES GCM以promise方式，分段update()实现加解密为例： -```javascript +```js import cryptoFramework from '@ohos.security.cryptoFramework'; var globalCipher; @@ -848,14 +858,16 @@ function testAesMultiUpdate() { }) } ``` + ### RSA加解密开发步骤 + 示例4：使用RSA非对称密钥的加解密操作 1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式。 3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let plan = "This is cipher test."; @@ -991,13 +1003,16 @@ function decryptMessageCallback() { }); } ``` + ### RSA分段加解密开发步骤 + 示例5：使用RSA非对称密钥的分段加解密操作 1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式。 3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文，多次调用doFinal实现分段。 -```javascript + +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1081,19 +1096,21 @@ function encryptLongMessagePromise() { } ``` -**说明** - -1. 使用RSA加解密时，Cipher对象不可重复调用init方法初始化，在创建了一个加密Cipher对象后，如果要进行解密，则需要重新创建另一个Cipher对象执行解密操作。 -2. RSA加密有长度限制，允许加密明文的最大长度见[加解密算法库框架概述](cryptoFramework-overview.md)中的基本概念加解密章节。 -3. RSA解密每次允许解密的密文长度为，RSA密钥的位数/8。 +> **说明：** +> +> 1. 使用RSA加解密时，Cipher对象不可重复调用init方法初始化，在创建了一个加密Cipher对象后，如果要进行解密，则需要重新创建另一个Cipher对象执行解密操作。 +> 2. RSA加密有长度限制，允许加密明文的最大长度见[加解密算法库框架概述](cryptoFramework-overview.md)中的基本概念加解密章节。 +> 3. RSA解密每次允许解密的密文长度为，RSA密钥的位数/8。 ### RSA加解密PKCS1_OAEP模式开发步骤 + 示例6：使用RSA非对称密钥使用PKCS1_OAEP模式的以Promise形式的加解密操作 -1. 根据密钥参数生成RSA密钥。通过createAsyKeyGeneratorBySpec接口创建AsyKeyGeneratorBySpec对象，并生成RSA非对称密钥对。（也可以使用createAsyKeyGenerator接口随机生成或转换得到RSA密钥对象） +1. 根据密钥参数生成RSA密钥。通过createAsyKeyGeneratorBySpec接口创建AsyKeyGeneratorBySpec对象，并生成RSA非对称密钥对（也可以使用createAsyKeyGenerator接口随机生成或转换得到RSA密钥对象）。 2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式，在Update前通过setCipherSpec设置PKCS1_OAEP填充字节流P。 3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文，需要加解密Cipher对象的字节流P一致。 -``` javascript + +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1192,7 +1209,6 @@ function rsaUseSpecDecryptOAEPPromise() { } ``` - ## 使用签名验签操作 ### 场景说明 @@ -1202,7 +1218,8 @@ function rsaUseSpecDecryptOAEPPromise() { 2. 使用ECC签名验签操作 3. 使用RSA签名验签，PSS模式时，获取、设置SignSpecItem参数。 -> **说明**：
+> **说明：** +> > 1. 从API version 10开始，支持RSA使用PSS填充模式时，获取、设置[SignSpecItem](../reference/apis/js-apis-cryptoFramework.md#signspecitem10)参数。 > 2. 从API version 10开始，支持签名验签时字符串参数不带密钥长度。 @@ -1234,12 +1251,14 @@ function rsaUseSpecDecryptOAEPPromise() { ### RSA签名验签开发步骤 示例1：使用RSA签名验签操作 + 1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用sign接口生成数据的签名。 4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。 -```javascript + +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1320,13 +1339,14 @@ function verifyMessageCallback() { ### ECDSA签名验签开发步骤 示例2：使用ECDSA操作 + 1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用doFinal接口生成数据的签名。 4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用doFinal接口传入签名进行验签。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1407,13 +1427,14 @@ function verifyMessageCallback() { ### RSA分段签名验签开发步骤 示例3：使用RSA签名验签操作 + 1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 3. 执行签名操作。通过Sign类提供的update接口，多次添加签名数据，并调用sign接口生成数据的签名，完成分段签名。 4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 5. 执行验签操作。多次通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签，完成分段验签。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1489,7 +1510,7 @@ function signLongMessagePromise() { 4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥，可以获得、设置PSS模式相关参数，验签成功需要保证盐值长度一致。 5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1585,7 +1606,8 @@ function verifyMessageCallbackPSS() { 通信双方可以在一个公开的信道上通过相互传送一些消息，共同建立一个安全的共享秘密密钥。 -> **说明**：
+> **说明：** +> > 从API version 10开始，支持密钥协商时字符串参数不带密钥长度。 ### 接口及参数说明 @@ -1603,7 +1625,7 @@ function verifyMessageCallbackPSS() { 1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 2. 基于ECC密钥的私钥及公钥执行ECDH操作。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" let globalKeyPair; @@ -1664,12 +1686,12 @@ function ecdhCallback() { ### 摘要算法开发步骤 -1. 设置算法，通过接口`createMd`生成摘要操作实例 -2. 接受用户数据，通过接口`update`，更新摘要，此步骤可重复，算法库不限制单次update的长度 -3. 通过接口`digest`，返回摘要计算结果 -4. 获取当前摘要算法名与摘要计算长度 +1. 设置算法，通过接口`createMd`生成摘要操作实例。 +2. 接受用户数据，通过接口`update`，更新摘要，此步骤可重复，算法库不限制单次update的长度。 +3. 通过接口`digest`，返回摘要计算结果。 +4. 获取当前摘要算法名与摘要计算长度。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1743,12 +1765,12 @@ function doMdByCallback() { ### 分段摘要算法开发步骤 -1. 设置算法，通过接口`createMd`生成摘要操作实例 -2. 接受用户数据，多次通过接口`update`，更新摘要，实现分段 -3. 通过接口`digest`，返回摘要计算结果 -4. 获取当前摘要算法名与摘要计算长度 +1. 设置算法，通过接口`createMd`生成摘要操作实例。 +2. 接受用户数据，多次通过接口`update`，更新摘要，实现分段。 +3. 通过接口`digest`，返回摘要计算结果。 +4. 获取当前摘要算法名与摘要计算长度。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1760,7 +1782,6 @@ function stringToUint8Array(str) { return new Uint8Array(arr); } - // 使用Promise方式，完成分段摘要 async function doLoopMdPromise() { let mdAlgName = "SHA256"; // 摘要算法名 @@ -1813,7 +1834,7 @@ async function doLoopMdPromise() { 消息认证码操作主要应用于身份认证的场景： -Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为 +Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为。 用户指定摘要算法（如SHA256）生成消息认证码Mac实例，输入对称密钥初始化Mac，并传入单段或多段需要摘要的信息，进行消息认证码计算，并获取消息认证码计算结果，在指定算法后可获取当前算法名与消息认证码计算长度（字节）。 @@ -1835,13 +1856,13 @@ Mac(message authentication code)可以对消息进行完整性校验，通过使 ### HMAC开发步骤 -1. 设置算法，通过接口`createMac`生成消息认证码操作实例 -2. 接受输入对称密钥，通过接口`init`，初始化Mac -3. 接受数据，通过接口`update`，更新Mac，此步骤可重复 -4. 通过接口`doFinal`，返回Mac计算结果 -5. 获取当前摘要算法名与Mac计算长度 +1. 设置算法，通过接口`createMac`生成消息认证码操作实例。 +2. 接受输入对称密钥，通过接口`init`，初始化Mac。 +3. 接受数据，通过接口`update`，更新Mac，此步骤可重复。 +4. 通过接口`doFinal`，返回Mac计算结果。 +5. 获取当前摘要算法名与Mac计算长度。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 可理解的字符串转成字节流 @@ -1941,14 +1962,16 @@ function doHmacByCallback() { ``` ### 分段HMAC开发步骤 + 以HMAC更新MAC时多次调用update实现分段为例： -1. 设置算法，通过接口`createMac`生成消息认证码操作实例 -2. 接受输入对称密钥，通过接口`init`，初始化Mac -3. 接受数据，多次通过接口`update`，以实现分段： -4. 通过接口`doFinal`，返回Mac计算结果 -5. 获取当前摘要算法名与Mac计算长度 -```javascript +1. 设置算法，通过接口`createMac`生成消息认证码操作实例。 +2. 接受输入对称密钥，通过接口`init`，初始化Mac。 +3. 接受数据，多次通过接口`update`，以实现分段。 +4. 通过接口`doFinal`，返回Mac计算结果。 +5. 获取当前摘要算法名与Mac计算长度。 + +```js import cryptoFramework from "@ohos.security.cryptoFramework" function stringToUint8Array(str) { @@ -2018,7 +2041,6 @@ function doLoopHmacPromise() { } ``` - ## 使用随机数操作 ### 场景说明 @@ -2029,6 +2051,7 @@ function doLoopHmacPromise() { - 用户使用生成的随机数作为参数，进行种子设置。 ### 接口及参数说明 + 详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 | 实例名 | 接口名 | 描述 | @@ -2041,11 +2064,11 @@ function doLoopHmacPromise() { ### 开发步骤 -1. 通过接口`createRandom`生成随机数操作实例 -2. 接受输入长度，通过接口`generateRandom`，生成指定长度的随机数 -3. 接受DataBlob数据，通过接口`setSeed`，为随机数生成池设置种子 +1. 通过接口`createRandom`生成随机数操作实例。 +2. 接受输入长度，通过接口`generateRandom`，生成指定长度的随机数。 +3. 接受DataBlob数据，通过接口`setSeed`，为随机数生成池设置种子。 -```javascript +```js import cryptoFramework from "@ohos.security.cryptoFramework" // 通过Promise方式生成随机数 diff --git a/zh-cn/application-dev/security/cryptoFramework-overview.md b/zh-cn/application-dev/security/cryptoFramework-overview.md index d9ef74fa7af11c8a6269a69b5ec9260c575cbcf3..75252b6e410846aeea49aaedab354ce7dc42f9e4 100644 --- a/zh-cn/application-dev/security/cryptoFramework-overview.md +++ b/zh-cn/application-dev/security/cryptoFramework-overview.md @@ -1,12 +1,16 @@ # 加解密算法库框架概述 加解密算法库框架是一个屏蔽了第三方密码学算法库实现差异的算法框架，提供加解密、签名验签、消息验证码、哈希、安全随机数等相关功能。开发者可以通过调用加解密算法库框架，忽略底层不同三方算法库的差异，实现迅捷开发。 -> **说明：** 加解密算法库框架仅提供密钥的密码学操作，而不提供密钥管理功能。因此，使用算法库时，需要应用自己来保管密钥（适用于临时会话密钥等仅在内存中使用的场景，或者应用自己实现密钥安全存储的场景）。如果业务需要由系统提供密钥管理功能（密钥存储等），请使用[HUKS部件](huks-overview.md)。 +> **说明：** +> +> 加解密算法库框架仅提供密钥的密码学操作，而不提供密钥管理功能。因此，使用算法库时，需要应用自己来保管密钥（适用于临时会话密钥等仅在内存中使用的场景，或者应用自己实现密钥安全存储的场景）。如果业务需要由系统提供密钥管理功能（密钥存储等），请使用[HUKS部件](huks-overview.md)。 ## 框架实现原理 + 加解密算法库框架提供的组件分为三层：接口层，Framework层和插件层。接口层负责对外提供统一的JS接口，插件层实现针对具体三方算法库的功能，Framework层通过灵活加载插件层的插件适配并屏蔽三方算法库差异。 ## 基本概念 + ### 对称密钥 对称密钥使用同一个密钥对数据进行加密解密操作。即对称加密算法中，数据发送方使用加密密钥对明文进行特殊加密算法处理后，使其变成复杂的加密密文发送出去。接收方收到密文后，若想解读原文，则需要使用同一个加密密钥以及相同算法的逆算法对密文进行解密，才能使其恢复成可读明文。 @@ -14,6 +18,7 @@ - **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速度更快、安全性更高。 @@ -72,35 +77,40 @@ pk：公钥，pk = (g ^ sk) mod p。 - ### 加解密 - **对称AES加解密** 算法库目前提供了AES加解密常用的7种加密模式：ECB、CBC、OFB、CFB、CTR、GCM和CCM。AES为分组加密算法，分组长度大小为128位。实际应用中明文最后一组可能不足128位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充； - - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； - - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； + - NoPadding：不带填充。 + - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充。 + - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充。 + + > **说明：** + > + > ECB、CBC加密模式，明文长度不是128位整数倍，必须使用填充方法补足。
+ > 由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即AES加密填充至16字节。 - > **说明：** 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字节。 + - NoPadding：不带填充。 + - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充。 + - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充。 + > **说明：** + > + > ECB、CBC加密模式，明文长度不是64位整数倍，必须使用填充方法补足。
+ > 由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即3DES加密填充至8字节。 - **非对称RSA加解密** RSA为块加密算法，加密长度需要在固定长度进行，实际应用中会使用各种padding模式做数据填充。算法库目前提供了RSA加解密常用的三种模式：NoPadding、PKCS1和PKCS1_OAEP。下文中描述了各个padding的区别： - - NoPadding：不带填充，输入的数据必须与RSA钥模一样长，输出数据长度与RSA钥模一样长； - - PKCS1：即RFC3447规范中的RSAES-PKCS1-V1_5模式（对应于OpenSSL中的RSA_PKCS1_PADDING）在进行RSA运算时需要将源数据D转化为Encryption block（EB），加密时，输入的数据最大长度 <= RSA钥模 - 11，输出数据长度与RSA钥模一样长； - - PKCS1_OAEP：即RFC3447规范中的RSAES-OAEP模式（对应于OpenSSL中的RSA_PKCS1_OAEP_PADDING），是PKCS#1推出的新填充方式，此模式需要设置两个摘要（md和mgf1_md），加密时，输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2（摘要长度以字节为单位），输出数据长度与RSA钥模一样长；此模式还可额外设置pSource字节流，来定义OAEP填充的编码输入P，并且可以获取PKCS1_OAEP的相关参数。
+ - NoPadding：不带填充，输入的数据必须与RSA钥模一样长，输出数据长度与RSA钥模一样长。 + - PKCS1：即RFC3447规范中的RSAES-PKCS1-V1_5模式（对应于OpenSSL中的RSA_PKCS1_PADDING）在进行RSA运算时需要将源数据D转化为Encryption block（EB），加密时，输入的数据最大长度 <= RSA钥模 - 11，输出数据长度与RSA钥模一样长。 + - PKCS1_OAEP：即RFC3447规范中的RSAES-OAEP模式（对应于OpenSSL中的RSA_PKCS1_OAEP_PADDING），是PKCS#1推出的新填充方式，此模式需要设置两个摘要（md和mgf1_md），加密时，输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2（摘要长度以字节为单位），输出数据长度与RSA钥模一样长；此模式还可额外设置pSource字节流，来定义OAEP填充的编码输入P，并且可以获取PKCS1_OAEP的相关参数。 PKCS1_OAEP的相关参数包括： @@ -112,15 +122,17 @@ pSource: 字节流，用于编码输入。 - > **说明：** RSA钥模 = (RSA的bits + 7) / 8 + > **说明：** + > + > RSA钥模 = (RSA的bits + 7) / 8 ### 签名验签 - **RSA签名验签** 算法库框架目前提供了两种RSA签名验签的padding模式：PKCS1和PSS。下面对两种模式做详细描述： - - PKCS1: 即RFC3447规范中的RSASSA-PKCS1-V1_5模式（对应于OpenSSL中的RSA_PKCS1_PADDING），在签名验签时，使用该模式时需要设置摘要（md），摘要算法输出的长度（字节）需要小于RSA的钥模； - - PSS: 即RFC3447规范中的RSASSA-PSS模式（对应于OpenSSL中的RSA_PKCS1_PSS_PADDING），此模式需要设置两个摘要（md和mgf1_md），且md和mgf1_md长度之和（字节）需要小于RSA的钥模；此模式还可额外设置以字节为单位的盐长度(saltLen)，并且可以获取PSS的相关参数； + - PKCS1: 即RFC3447规范中的RSASSA-PKCS1-V1_5模式（对应于OpenSSL中的RSA_PKCS1_PADDING），在签名验签时，使用该模式时需要设置摘要（md），摘要算法输出的长度（字节）需要小于RSA的钥模。 + - PSS: 即RFC3447规范中的RSASSA-PSS模式（对应于OpenSSL中的RSA_PKCS1_PSS_PADDING），此模式需要设置两个摘要（md和mgf1_md），且md和mgf1_md长度之和（字节）需要小于RSA的钥模；此模式还可额外设置以字节为单位的盐长度(saltLen)，并且可以获取PSS的相关参数。 PSS的相关参数包括： @@ -134,7 +146,10 @@ trailer_field：用于编码操作的整数，其值只支持为1。 - > **说明：** RSA钥模 = (RSA的bits + 7) / 8 + > **说明：** + > + > RSA钥模 = (RSA的bits + 7) / 8 + - **ECDSA** 椭圆曲线数字签名算法（ECDSA）是基于椭圆曲线密码（ECC）的数字签名算法（DSA）。相比普通的离散对数问题（DLP）和大数分解问题（IFP），椭圆曲线密码的单位比特强度要高于其他公钥体制。算法库框架提供了多种椭圆曲线及摘要算法组合的椭圆曲线数字签名算法（ECDSA）能力。 @@ -154,11 +169,11 @@ 消息摘要MD算法是一种能将任意长度的输入消息，通过哈希算法生成长度固定的摘要的算法。消息摘要算法通过其不可逆的特性能被用于敏感信息的加密。消息摘要算法也被称为哈希算法或单向散列算法。 在摘要算法相同时，生成的摘要值主要有下列特点： -- 当输入消息相同时，生成摘要序列相同； -- 当输入消息的长度不一致时，生成摘要序列长度固定（摘要长度由算法决定）； -- 当输入消息不一致时，生成摘要序列几乎不会相同（依然存在相同概率，由摘要长度决定相同概率）； +- 当输入消息相同时，生成摘要序列相同。 +- 当输入消息的长度不一致时，生成摘要序列长度固定（摘要长度由算法决定）。 +- 当输入消息不一致时，生成摘要序列几乎不会相同（依然存在相同概率，由摘要长度决定相同概率）。 -消息摘要算法主要分为三类：MD，SHA与MAC（详见HMAC章节） +消息摘要算法主要分为三类：MD，SHA与MAC（详见HMAC章节）。 MD算法包括MD2，MD4和MD5。 SHA算法主要包括SHA1，SHA224，SHA256，SHA384，SHA512。 @@ -168,12 +183,11 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 ### 随机数 -随机数在加解密过程中主要用于临时会话密钥的生成与非对称加密算法中密钥的生成。随机数由硬件生成的硬件随机数生成器或由软件生成的伪随机数生成器进行生成。在加解密的场景中，安全随机数生成器需要具备随机性，不可预测性，与不可重现性。密码学安全伪随机数生成器CSPRNG（Cryptography Secure Random Number Generators）生成的随机数满足密码学安全伪随机性 +随机数在加解密过程中主要用于临时会话密钥的生成与非对称加密算法中密钥的生成。随机数由硬件生成的硬件随机数生成器或由软件生成的伪随机数生成器进行生成。在加解密的场景中，安全随机数生成器需要具备随机性，不可预测性，与不可重现性。密码学安全伪随机数生成器CSPRNG（Cryptography Secure Random Number Generators）生成的随机数满足密码学安全伪随机性。 -- **内部状态**代表随机数生成器内存中的数值，当内部状态相同时，随机数生成器会生成固定的随机数序列 +- **内部状态**代表随机数生成器内存中的数值，当内部状态相同时，随机数生成器会生成固定的随机数序列。 - **种子**（seed）是一个用来对伪随机数的内部状态进行初始化的数据，随机数生成器通过种子来生成一系列的随机序列。 - ## 约束与限制 - 算法库框架不支持多线程并发操作。 @@ -197,7 +211,9 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |AES|192|AES192| |AES|256|AES256| - > **说明**：“字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 + > **说明：** + > + > “字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 ### 3DES密钥生成规格 @@ -207,10 +223,14 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |---|---|---| |3DES|192|3DES192| - > **说明**：“字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 + > **说明：** + > + > “字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 ### RSA密钥生成规格 - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持使用密钥参数来生成RSA密钥。 - 支持以字符串参数来生成RSA密钥，其生成参数如下表所示： @@ -233,28 +253,36 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |RSA8192|4|RSA8192\|PRIMES_4| |RSA8192|5|RSA8192\|PRIMES_5| - > **说明**：“字符串参数”是“RSA密钥类型”和“素数个数”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 + > **说明：** + > + > “字符串参数”是“RSA密钥类型”和“素数个数”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 - 支持以密钥参数来生成RSA密钥，其密钥参数种类和各个密钥参数的密码学规格要求如下表所示： + | |公共参数|公钥参数|私钥参数|公私钥对参数| |---|---------|---|---|---| |n |× |√ |× |√ | |pk| |√ | |√ | |sk| | |× |√ | - > **说明**：密钥参数用于在创建非对称密钥生成器时，指定密钥规格。
+ > **说明：** + > + > 密钥参数用于在创建非对称密钥生成器时，指定密钥规格。
> 上表说明了算法库对于指定公/私钥参数生成RSA密钥的支持情况。
打√的表示需要指定这一列中的具体属性，来构成密钥参数。
打×的表示这一列中的具体属性对应于某种密钥参数，但是算法库当前不支持通过该密钥参数生成密钥。 - > **注意**： - > 1. RSA不支持通过指定公共参数（n）来随机生成密钥。
+ > **注意：** + > + > 1. RSA不支持通过指定公共参数（n）来随机生成密钥。 > 2. RSA不支持通过指定私钥参数（n, sk）来生成私钥。 ### ECC密钥生成规格 - > **说明**：
+ > **说明：** + > > 从API version 10开始， 支持使用密钥参数来生成ECC密钥。 + - 支持以字符串参数来生成ECC密钥，其生成参数如下表所示： |非对称密钥算法|密钥长度（bit）|曲线名|字符串参数| @@ -264,10 +292,11 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |ECC|384|NID_secp384r1|ECC384| |ECC|521|NID_secp521r1|ECC521| - > **说明**：“字符串参数”是“非对称密钥算法”和“密钥长度”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。
+ > **说明：** + > + > “字符串参数”是“非对称密钥算法”和“密钥长度”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。
> 当前支持的ECC均为Fp域曲线。 - - 支持以密钥参数来生成ECC密钥，其密钥参数种类和各个密钥参数的密码学规格要求如下表所示： | |公共参数|公钥参数|私钥参数|公私钥对参数| |---|---|---|---|---| @@ -281,16 +310,21 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |pk | | √| | √| |sk | | | √| √| - > **说明**：密钥参数用于在创建非对称密钥生成器时，指定密钥规格。
+ > **说明：** + > + > 密钥参数用于在创建非对称密钥生成器时，指定密钥规格。
> 上表说明了算法库对于指定公/私钥参数生成ECC密钥的支持情况。
> 打√的表示需要指定这一列中的具体属性，来构成密钥参数。 - > **注意**： - > 1. 当前ECC只支持Fp域，因此fieldType固定为"Fp"。fieldType和p构成了属性field，当前field只支持[ECFieldFp](../reference/apis/js-apis-cryptoFramework.md#ecfieldfp10)。
+ > **注意：** + > + > 1. 当前ECC只支持Fp域，因此fieldType固定为"Fp"。fieldType和p构成了属性field，当前field只支持[ECFieldFp](../reference/apis/js-apis-cryptoFramework.md#ecfieldfp10)。 > 2. g和pk为ECC曲线上的点，属于[Point](../reference/apis/js-apis-cryptoFramework.md#point10)类型，需要指定具体X，Y坐标。 ### DSA密钥生成规格 - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持DSA算法，包括密钥生成和签名验签。 - 支持以字符串参数来生成DSA密钥，其生成参数如下表所示： @@ -301,9 +335,12 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |DSA|2048|DSA2048| |DSA|3072|DSA3072| - > **说明**：“字符串参数”是“非对称密钥算法”和“密钥长度”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。
+ > **说明：** + > + > “字符串参数”是“非对称密钥算法”和“密钥长度”拼接而成，用于在创建非对称密钥生成器时，指定密钥规格。 - 支持以密钥参数来生成RSA密钥，其密钥参数种类和各个密钥参数的密码学规格要求如下表所示： + | |公共参数|公钥参数|私钥参数|公私钥对参数| |---|---------|---|---|---| |p |√ |√ |× |√ | @@ -312,19 +349,24 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 |pk | |√ | |√ | |sk | | |× |√ | - > **说明**：密钥参数用于在创建非对称密钥生成器时，指定密钥规格。
+ > **说明：** + > + > 密钥参数用于在创建非对称密钥生成器时，指定密钥规格。
> 上表说明了算法库对于指定公/私钥参数生成DSA密钥的支持情况。
- 打√的表示需要指定这一列中的具体属性，来构成密钥参数。
- 打×的表示这一列中的具体属性对应于某种密钥参数，但是算法库当前不支持通过该密钥参数生成密钥。 + > 打√的表示需要指定这一列中的具体属性，来构成密钥参数。
+ > 打×的表示这一列中的具体属性对应于某种密钥参数，但是算法库当前不支持通过该密钥参数生成密钥。 - > **注意**： - > 1. DSA不支持通过指定私钥参数（p, q, g, sk）来生成私钥。
+ > **注意：** + > + > 1. DSA不支持通过指定私钥参数（p, q, g, sk）来生成私钥。 > 2. 当使用公共参数（p, q, g）来生成DSA密钥对时，DSA密钥长度至少需要1024位。 - ## 加解密规格 + ### 对称加解密 - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持对称加解密不带密钥长度的规格。 - 支持的对称加密算法： @@ -348,7 +390,9 @@ HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息 > 2. “字符串参数”是“对称加解密算法（含密钥长度）”、“分组模式”、“填充模式”拼接而成，用于在创建对称加解密实例时，指定对称加解密算法规格。 ### 非对称RSA加解密 - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持非对称RSA加解密不带密钥长度的规格。 RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 @@ -436,13 +480,14 @@ RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 > **说明：** > - > 1. []内的参数只能任选一项，非[]内的为固定值； - > 2. 使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成“字符串参数”，用于在创建非对称加解密实例时，指定非对称加解密算法规格。 - > 例如："RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256" + > 1. []内的参数只能任选一项，非[]内的为固定值。 + > 2. 使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成“字符串参数”，用于在创建非对称加解密实例时，指定非对称加解密算法规格。
+ > 例如："RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256" > 3. 在上表最后一行，为了兼容由密钥参数生成的密钥，RSA加解密参数输入密钥类型时支持不带长度，加解密运算取决于实际输入的密钥长度。 > 4. 输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2，如RSA密钥为512位时,不支持SHA512，RSA钥模和摘要长度定义，详见[加解密](#加解密)中RSA的相关描述。 - 使用PKCS1_OAEP模式时，可以通过获取加解密OAEP填充模式的各个[参数](../reference/apis/js-apis-cryptoFramework.md#cipherspecitem10)，并设置OAEP填充的编码输入P。 + | OAEP参数 |枚举值| 获取 | 设置 | |---|---|---|---| |md|OAEP_MD_NAME_STR |√|| @@ -450,16 +495,20 @@ RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 |mgf1_md|OAEP_MGF1_MD_STR |√|| |pSource|OAEP_MGF1_PSRC_UINT8ARR|√|√| - > **说明**：
+ > **说明：** + > > 上表说明了算法库对于OAEP参数的获取和设置支持情况，打√的表示需要对该参数具有获取或设置的能力。 ## 签名验签规格 ### RSA签名验签 - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持RSA签名验签不带密钥长度的规格。 RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 + - 使用PKCS1模式时可以指定的参数: | 非对称密钥类型 | 填充模式 | 摘要 | 字符串参数 | @@ -474,7 +523,8 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |RSA|PKCS1|符合长度要求的摘要算法|RSA\|PKCS1\|符合长度要求的摘要算法| > **说明：** - > 1. []内的参数只能任选一项，非[]内的为固定值； + > + > 1. []内的参数只能任选一项，非[]内的为固定值。 > 2. 在上表最后一行，为了兼容由密钥参数生成的密钥，RSA签名验签参数输入密钥类型时支持不带长度，签名验签运算取决于实际输入的密钥长度。 > 3. RSA签名验签时，摘要算法输出的长度，需要小于RSA的钥模, 如RSA密钥为512位时，不支持SHA512，详见[签名验签](#签名验签)中RSA的相关描述。 @@ -526,13 +576,14 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 > **说明：** > - > 1. []内的参数只能任选一项，非[]内的为固定值； - > 2. 使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成“字符串参数”，用于在创建非对称签名验签实例时，指定非对称签名验签算法规格。 - > 例如："RSA2048|PSS|SHA256|MGF1_SHA256" + > 1. []内的参数只能任选一项，非[]内的为固定值。 + > 2. 使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成“字符串参数”，用于在创建非对称签名验签实例时，指定非对称签名验签算法规格。
+ > 例如："RSA2048|PSS|SHA256|MGF1_SHA256" > 3. 在上表最后一行，为了兼容由密钥参数生成的密钥，RSA签名验签参数输入密钥类型时支持不带长度，签名验签运算取决于实际输入的密钥长度。 > 4. RSA签名验签时，对于PSS模式，md和mgf1_md长度之和（字节）需要小于RSA的钥模。如RSA密钥为512位时，无法支持md和mgf1_md同时为SHA256。RSA钥模和摘要长度定义，详见[签名验签](#签名验签)中RSA的相关描述。 - 使用PSS模式时，可以通过获取签名验签PSS填充模式的各个[参数](../reference/apis/js-apis-cryptoFramework.md#signspecitem10)，并设置PSS的以字节为单位的盐长度(saltLen)。 + | PSS参数 |枚举值| 获取 | 设置 | |---|---|---|---| |md|PSS_MD_NAME_STR |√|| @@ -541,10 +592,12 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |saltLen|PSS_SALT_LEN_NUM|√|√| |trailer_field|PSS_TRAILER_FIELD_NUM|√|| - > **说明**：
+ > **说明：** + > > 上表说明了算法库对于PSS参数的获取和设置支持情况，打√的表示需要对该参数具有获取或设置的能力。 ### ECDSA签名验签 + > **说明**：
> 从API version 10开始， 支持ECDSA签名验签不带密钥长度的规格。 - 支持的ECDSA参数： @@ -558,13 +611,16 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |ECC|[SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|ECC\|[SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| > **说明：** - > 1. []内的参数只能任选一项，非[]内的为固定值； - > 2. 使用时请从表格中选择非对称密钥类型、摘要二个数据，用|拼接成“字符串参数”，用于在创建非对称签名验签实例时，指定非对称签名验签算法规格。 - > 例如："ECC224|SHA256" + > + > 1. []内的参数只能任选一项，非[]内的为固定值。 + > 2. 使用时请从表格中选择非对称密钥类型、摘要二个数据，用|拼接成“字符串参数”，用于在创建非对称签名验签实例时，指定非对称签名验签算法规格。
+ > 例如："ECC224|SHA256" > 3. 在上表最后一行，为了兼容由密钥参数生成的密钥，ECDSA签名验签参数输入密钥类型时支持不带长度，签名验签运算取决于实际输入的密钥长度。 ### DSA签名验签 - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持DSA签名验签规格。 - 支持的DSA参数： @@ -577,15 +633,18 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |DSA|[NoHash\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|DSA\|[NoHash\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| > **说明：** - > 1. []内的参数只能任选一项，非[]内的为固定值； - > 2. 使用时请从表格中选择非对称密钥类型、摘要二个数据，用|拼接成“字符串参数”，用于在创建非对称签名验签实例时，指定非对称签名验签算法规格。 - > 例如："DSA1024|SHA256" + > + > 1. []内的参数只能任选一项，非[]内的为固定值。 + > 2. 使用时请从表格中选择非对称密钥类型、摘要二个数据，用|拼接成“字符串参数”，用于在创建非对称签名验签实例时，指定非对称签名验签算法规格。
+ > 例如："DSA1024|SHA256" > 3. 在上表最后一行，为了兼容由密钥参数生成的密钥，DSA签名验签参数输入密钥类型时支持不带长度，签名验签运算取决于实际输入的密钥长度。 ## 密钥协商规格 ### ECDH - > **说明**：
+ + > **说明：** + > > 从API version 10开始， 支持ECDH不带密钥长度的规格。 - 支持的ECDH参数： @@ -599,11 +658,13 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |ECC|ECC| > **说明：** + > > 1. “字符串参数”，用于在创建密钥协商时，指定密钥协商算法规格。 > 2. 在上表最后一行，为了兼容由密钥参数生成的密钥，ECDH密钥协商参数输入密钥类型时支持不带长度，密钥协商运算取决于实际输入的密钥长度。 ## MD消息摘要算法规格 + - 加解密算法库框架当前支持的MD算法参数： |摘要算法|支持种类| @@ -616,9 +677,11 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |HASH|MD5| > **说明：** + > > “支持种类”，用于在创建MD消息摘要时，指定MD消息摘要算法规格。 ## HMAC消息认证码算法规格 + - 加解密算法库框架当前支持的HMAC算法参数： |摘要算法|支持种类| @@ -630,11 +693,13 @@ RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 |HASH|SHA512| > **说明：** + > > “支持种类”，用于在创建HMAC消息认证码时，指定HMAC消息认证码算法规格。 ## 随机数 - 加解密算法库框架支持随机数生成算法，目前只支持“CTR_DRBG"算法规格 > **说明：** + > > 1. 随机数生成算法目前支持生成长度为[1, INT_MAX]的安全随机数，长度单位为byte。 > 2. 随机数生成算法使用openssl的RAND_priv_bytes接口生成安全随机数。 \ No newline at end of file