diff --git a/zh-cn/application-dev/reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md b/zh-cn/application-dev/reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md index 02be603c1799c4ab5b7ca8be97af0f9f66c53c28..3b4e9bba9cb77342c8907c901f1244532209d3b3 100644 --- a/zh-cn/application-dev/reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md +++ b/zh-cn/application-dev/reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md @@ -540,6 +540,27 @@ buffer数组，提供blob数据类型。 > > password指的是原始密码，如果使用string类型，需要直接传入用于密钥派生的数据，而不是HexString、base64等字符串类型，同时需要确保该字符串为utf-8编码，否则派生结果会有差异。 +## HKDFSpec12+ + +密钥派生函数参数[KdfSpec](#kdfspec11)的子类，作为HKDF密钥派生函数进行密钥派生时的输入。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------------------------------------------------------ | +| key | string \| Uint8Array | 是 | 是 | 密钥材料。| +| salt | Uint8Array | 是 | 是 | 盐值。 | +| info | Uint8Array | 是 | 是 | 拓展信息。 | +| keySize | number | 是 | 是 | 派生得到的密钥字节长度。 | + +> **说明：** +> +> key指的是用户输入的最初的密钥材料。info与salt是可选参数，根据模式的不同可以传空，但是不可不传。 +> +> 例如：EXTRACT_AND_EXPAND模式需要输入全部的值，EXTRACT_ONLY模式info可以为空，在构建HKDFspec的时候，info传入null值。 +> +> 默认的模式为EXTRACT_AND_EXPAND，"HKDF|SHA256|EXTRACT_AND_EXPAND"等价于"HKDF|SHA256". + ## SM2CipherTextSpec12+ SM2密文参数，使用SM2密文格式转换函数进行格式转换时，需要用到此对象。可以通过指定此参数，生成符合国密标准的ASN.1格式的SM2密文，反之，也可以从ASN.1格式的SM2密文中获取具体参数。 @@ -4385,7 +4406,7 @@ createKdf(algName: string): Kdf | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | --------------------------------- | -| algName | string | 是 | 指定密钥派生算法（包含HMAC配套的散列函数）：目前仅支持PBKDF2算法，如"PBKDF2\|SHA1"。 | +| algName | string | 是 | 指定密钥派生算法（包含HMAC配套的散列函数）：目前支持PBKDF2、HKDF算法，如"PBKDF2\|SHA1", "HKDF\|SHA1"。 | **返回值**： @@ -4403,10 +4424,14 @@ createKdf(algName: string): Kdf | 17620001 | memory error. | **示例：** - +- PBKDF2算法 ```ts let kdf = cryptoFramework.createKdf('PBKDF2|SHA1'); +``` +- HKDF算法 +```ts +let kdf = cryptoFramework.createKdf('HKDF|SHA1'); ``` ## Kdf11+ @@ -4447,6 +4472,7 @@ generateSecret(params: KdfSpec, callback: AsyncCallback\): void **示例：** +- PBKDF2算法 ```ts let spec: cryptoFramework.PBKDF2Spec = { algName: 'PBKDF2', @@ -4465,6 +4491,25 @@ kdf.generateSecret(spec, (err, secret) => { }); ``` +- HKDF算法 +```ts +let spec: cryptoFramework.HKDFSpec = { + algName: 'HKDF', + key: '123456', + salt: new Uint8Array(16), + info: new Uint8Array(16), + keySize: 32 +}; +let kdf = cryptoFramework.createKdf('HKDF|SHA256|EXTRACT_AND_EXPAND'); +kdf.generateSecret(spec, (err, secret) => { + if (err) { + console.error("key derivation error."); + return; + } + console.info('key derivation output is ' + secret.data); +}); +``` + ### generateSecret generateSecret(params: KdfSpec): Promise\ @@ -4496,6 +4541,7 @@ generateSecret(params: KdfSpec): Promise\ **示例：** +- PBKDF2算法 ```ts import { BusinessError } from '@ohos.base'; @@ -4513,4 +4559,24 @@ kdfPromise.then(secret => { }).catch((error: BusinessError) => { console.error("key derivation error."); }); +``` + +- HKDF算法 +```ts +import { BusinessError } from '@ohos.base'; + +let spec: cryptoFramework.HKDFSpec = { + algName: 'HKDF', + key: '123456', + salt: new Uint8Array(16), + info: 10000, + keySize: 32 +}; +let kdf = cryptoFramework.createKdf('HKDF|SHA256|EXTRACT_AND_EXPAND'); +let kdfPromise = kdf.generateSecret(spec); +kdfPromise.then(secret => { + console.info('key derivation output is ' + secret.data); +}).catch((error: BusinessError) => { + console.error("key derivation error."); +}); ``` \ No newline at end of file diff --git a/zh-cn/application-dev/security/CryptoArchitectureKit/Readme-CN.md b/zh-cn/application-dev/security/CryptoArchitectureKit/Readme-CN.md index 0b6c0a8340afc161f4b61b9655f2782a27d8c9ab..d3c3f93c5a7c532e6ec6e70dc08b1cc3b773025e 100644 --- a/zh-cn/application-dev/security/CryptoArchitectureKit/Readme-CN.md +++ b/zh-cn/application-dev/security/CryptoArchitectureKit/Readme-CN.md @@ -46,4 +46,7 @@ - [消息摘要计算](crypto-generate-message-digest.md) - [消息认证码计算](crypto-compute-mac.md) - [安全随机数生成](crypto-generate-random-number.md) -- [密钥派生](crypto-key-derivation.md) +- 密钥派生 + - [密钥派生介绍及算法规格](crypto-key-derivation-overview.md) + - [使用PBKDF2进行密钥派生](crypto-key-derivation-using-pbkdf2.md) + - [使用HKDF进行密钥派生](crypto-key-derivation-using-hkdf.md) diff --git a/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-overview.md b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..efe947a46f1b2d8fef524de8984d9b413ab97068 --- /dev/null +++ b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-overview.md @@ -0,0 +1,38 @@ +# 密钥派生 +密钥派生函数（key derivation function）是指使用伪随机函数从秘密值（如主密钥）中导出一个或多个密钥。密钥派生函数可用于将密钥扩展到更长的密钥或获得所需格式的密钥。 + +## 支持的算法与规格 + +## PBKDF2算法。 + +PBKDF（Password-Based Key Derivation Function）是具有可变计算成本的密钥派生函数；PBKDF2是PKCS系列的标准之一。 + +PBKDF2是将伪随机函数PRF（Pseudo-Random Function，例如基于散列的[HMAC](crypto-compute-mac.md)），输入密码明文和盐值，重复多次运算来进行密钥派生。 + +当前支持以字符串参数进行密钥派生，具体的“字符串参数”由“密钥派生函数”和“HMAC函数摘要算法”使用符号“|”拼接而成，用于在创建密钥派生函数生成器时，指定算法规格。 +| 密钥派生算法 | HMAC函数摘要算法 | 字符串参数 | API版本 | +| -------- | -------- | -------- | -------- | +| PBKDF2 | SHA1 | PBKDF2\|SHA1 | 11+ | +| PBKDF2 | SHA224 | PBKDF2\|SHA224 | 11+ | +| PBKDF2 | SHA256 | PBKDF2\|SHA256 | 11+ | +| PBKDF2 | SHA384 | PBKDF2\|SHA384 | 11+ | +| PBKDF2 | SHA512 | PBKDF2\|SHA512 | 11+ | +| PBKDF2 | SM3 | PBKDF2\|SM3 | 11+ | + +## HKDF算法 + +HKDF是HMAC-based Extract-and-Expand Key Derivation Function的缩写,意为例如基于散列的[HMAC](crypto-compute-mac.md)），输入密码明文和盐值来提取和输入密码明文和拓展信息来扩展。它是一种密钥派生函数,用于从较短的输入密钥中派生出更长的输出密钥。 + +HKDF包含俩个基本模块，提取（Extract）、拓展（Expand） +提取：使用原始的密钥材料，派生出一个符合密码学强度的伪随机密钥。 +拓展：将短密钥经过拓展变长，使用提取出的伪随机密钥，拓展出指定长度的密钥，同时保证随机性。 + +当前支持以字符串参数进行密钥派生，具体的“字符串参数”由“密钥派生函数”、“HMAC函数摘要算法”和“模式”使用符号“|”拼接而成，用于在创建密钥派生函数生成器时，指定算法规格 +| 密钥派生算法 | HMAC函数摘要算法 | 字符串参数 | API版本 | +| -------- | -------- | -------- | -------- | +| HKDF | SHA1 | HKDF\|SHA1 | 12+ | +| HKDF | SHA224 | HKDF\|SHA224 | 12+ | +| HKDF | SHA256 | HKDF\|SHA256 | 12+ | +| HKDF | SHA384 | HKDF\|SHA384 | 12+ | +| HKDF | SHA512 | HKDF\|SHA512 | 12+ | +| HKDF | SM3 | HKDF\|SM3 | 12+ | \ No newline at end of file diff --git a/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-hkdf.md b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-hkdf.md new file mode 100644 index 0000000000000000000000000000000000000000..8a5e22ba07a8423222a629a52c06412f9d00807b --- /dev/null +++ b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-hkdf.md @@ -0,0 +1,72 @@ +# 使用HKDF进行密钥派生 +对应算法规格请查看[密钥派生算法规格：HKDF](crypto-key-derivation-overview.md#HKDF) + +# 开发步骤 +1. 构造[HKDFSpec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#hkdfspec12)对象，作为密钥派生参数进行密钥派生。 + + HKDFSpec是KdfSpec的子类，需要指定： + + - algName：指定算法'HKDF'。 + - key：原始密钥材料。 + 如果使用string类型，需要直接传入用于密钥派生的数据，而不是HexString、base64等字符串类型。同时需要确保该字符串为utf-8编码，否则派生结果会有差异。 + - salt：盐值。 + - info：可选的上下文与应用相关信息， 可为空，用于拓展短密钥。 + - keySize：目标密钥的字节长度，需要为正整数。 + + 2. 调用[cryptoFramework.createKdf](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatekdf11)，指定字符串参数'HKDF|SHA256|EXTRACT_AND_EXPAND'，创建密钥派生算法为HKDF、HMAC函数摘要算法为SHA256、模式为提取和拓展的密钥派生函数对象（Kdf）。 + + 3. 输入HKDFSpec对象，调用[Kdf.generateSecret](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#generatesecret-2)进行密钥派生。 + + Kdf.generateSecret的多种调用形式如表所示。 + + | 接口名 | 返回方式 | + | -------- | -------- | + | generateSecret(params: KdfSpec, callback: AsyncCallback<DataBlob>): void | callback异步生成 | + | generateSecret(params: KdfSpec): Promise<DataBlob> | Promise异步生成 | + + - 通过await返回结果： + ```ts + import cryptoFramework from '@ohos.security.cryptoFramework'; + + async function kdfAwait() { + let keyData = new Uint8Array(buffer.from("012345678901234567890123456789", "utf-8").buffer); + let saltData = new Uint8Array(buffer.from("0123456789", "utf-8").buffer); + let infoData = new Uint8Array(buffer.from("infostring", "utf-8").buffer); + let spec: cryptoFramework.HKDFSpec = { + algName: 'HKDF', + key: keyData, + salt: saltData, + info: infoData, + keySize: 32 + }; + let kdf = cryptoFramework.createKdf('HKDF|SHA256|EXTRACT_AND_EXPAND'); + let secret = await kdf.generateSecret(spec); + console.info("key derivation output is " + secret.data); + } + ``` + +- 通过Promise返回结果： + ```ts + import cryptoFramework from '@ohos.security.cryptoFramework'; + import { BusinessError } from '@ohos.base'; + + function kdfPromise() { + let keyData = new Uint8Array(buffer.from("012345678901234567890123456789", "utf-8").buffer); + let saltData = new Uint8Array(buffer.from("0123456789", "utf-8").buffer); + let infoData = new Uint8Array(buffer.from("infostring", "utf-8").buffer); + let spec: cryptoFramework.HKDFSpec = { + algName: 'HKDF', + key: keyData, + salt: saltData, + info: infoData, + keySize: 32 + }; + let kdf = cryptoFramework.createKdf('HKDF|SHA256|EXTRACT_AND_EXPAND'); + let kdfPromise = kdf.generateSecret(spec); + kdfPromise.then((secret) => { + console.info("key derivation output is " + secret.data); + }).catch((error: BusinessError) => { + console.error("key derivation error."); + }); + } + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-pbkdf2.md b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-pbkdf2.md new file mode 100644 index 0000000000000000000000000000000000000000..308df37c917850fa10fd6b48fb109a134779de0a --- /dev/null +++ b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-pbkdf2.md @@ -0,0 +1,67 @@ +# 使用PBKDF2算法派生密钥 +对应的算法规格请查看[密钥派生算法规格：PBKDF2](crypto-key-derivation-overview.md#PBDKF2) + +## 开发步骤 + +1. 构造[PBKDF2Spec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#pbkdf2spec11)对象，作为密钥派生参数进行密钥派生。 + + PBKDF2Spec是KdfSpec的子类，需要指定： + + - algName：指定算法'PBKDF2'。 + - password：用于生成派生密钥的原始密码。 + 如果使用string类型，需要直接传入用于密钥派生的数据，而不是HexString、base64等字符串类型。同时需要确保该字符串为utf-8编码，否则派生结果会有差异。 + - salt：盐值。 + - iterations：重复运算的次数，需要为正整数。 + - keySize：目标密钥的字节长度，需要为正整数。 + +2. 调用[cryptoFramework.createKdf](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#cryptoframeworkcreatekdf11)，指定字符串参数'PBKDF2|SHA256'，创建密钥派生算法为PBKDF2、HMAC函数摘要算法为SHA256的密钥派生函数对象（Kdf）。 + +3. 输入PBKDF2Spec对象，调用[Kdf.generateSecret](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#generatesecret-2)进行密钥派生。 + + Kdf.generateSecret的多种调用形式如表所示。 + + | 接口名 | 返回方式 | + | -------- | -------- | + | generateSecret(params: KdfSpec, callback: AsyncCallback<DataBlob>): void | callback异步生成 | + | generateSecret(params: KdfSpec): Promise<DataBlob> | Promise异步生成 | + +- 通过await返回结果： + ```ts + import cryptoFramework from '@ohos.security.cryptoFramework'; + + async function kdfAwait() { + let spec: cryptoFramework.PBKDF2Spec = { + algName: 'PBKDF2', + password: '123456', + salt: new Uint8Array(16), + iterations: 10000, + keySize: 32 + }; + let kdf = cryptoFramework.createKdf('PBKDF2|SHA256'); + let secret = await kdf.generateSecret(spec); + console.info("key derivation output is " + secret.data); + } + ``` + +- 通过Promise返回结果： + ```ts + import cryptoFramework from '@ohos.security.cryptoFramework'; + import { BusinessError } from '@ohos.base'; + + function kdfPromise() { + let spec: cryptoFramework.PBKDF2Spec = { + algName: 'PBKDF2', + password: '123456', + salt: new Uint8Array(16), + iterations: 10000, + keySize: 32 + }; + let kdf = cryptoFramework.createKdf('PBKDF2|SHA256'); + let kdfPromise = kdf.generateSecret(spec); + kdfPromise.then((secret) => { + console.info("key derivation output is " + secret.data); + }).catch((error: BusinessError) => { + console.error("key derivation error."); + }); + } + ```