From cee03f591d2febc1c78ea9f6edcf02d85b3e2d76 Mon Sep 17 00:00:00 2001 From: lcc Date: Tue, 19 Mar 2024 20:20:36 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=A2=9E=E5=8A=A0HKDF?= =?UTF-8?q?=E5=AF=86=E9=92=A5=E6=B4=BE=E7=94=9F=E7=AE=97=E6=B3=95=E7=9A=84?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: lcc --- .../Readme-Crypto-Architecture-Kit.md | 51 +++++++++++++ .../crypto-key-derivation-overview.md | 40 +++++++++++ .../crypto-key-derivation-using-hkdf.md | 72 +++++++++++++++++++ .../crypto-key-derivation-using-pbkdf2.md | 67 +++++++++++++++++ 4 files changed, 230 insertions(+) create mode 100644 zh-cn/application-dev/kit-readme/Readme-Crypto-Architecture-Kit.md create mode 100644 zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-overview.md create mode 100644 zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-hkdf.md create mode 100644 zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-using-pbkdf2.md diff --git a/zh-cn/application-dev/kit-readme/Readme-Crypto-Architecture-Kit.md b/zh-cn/application-dev/kit-readme/Readme-Crypto-Architecture-Kit.md new file mode 100644 index 00000000000..fd02463d748 --- /dev/null +++ b/zh-cn/application-dev/kit-readme/Readme-Crypto-Architecture-Kit.md @@ -0,0 +1,51 @@ +# Crypto Architecture Kit（加解密算法框架服务） + +- [Crypto Architecture Kit简介](../security/CryptoArchitectureKit/crypto-architecture-kit-intro.md) +- 密钥生成和转换 + - [密钥生成与转换介绍](../security/CryptoArchitectureKit/crypto-key-generation-conversion-overview.md) + - 密钥生成和转换规格 + - [对称密钥生成和转换规格](../security/CryptoArchitectureKit/crypto-sym-key-generation-conversion-spec.md) + - [非对称密钥生成和转换规格](../security/CryptoArchitectureKit/crypto-asym-key-generation-conversion-spec.md) + - 密钥生成和转换开发指导 + - [随机生成对称密钥](../security/CryptoArchitectureKit/crypto-generate-sym-key-randomly.md) + - [指定二进制数据转换对称密钥](../security/CryptoArchitectureKit/crypto-convert-binary-data-to-sym-key.md) + - [随机生成非对称密钥对](../security/CryptoArchitectureKit/crypto-generate-asym-key-pair-randomly.md) + - [指定二进制数据转换非对称密钥对](../security/CryptoArchitectureKit/crypto-convert-binary-data-to-asym-key-pair.md) + - [指定密钥参数生成非对称密钥对](../security/CryptoArchitectureKit/crypto-generate-asym-key-pair-from-key-spec.md) +- 加解密 + - [加解密介绍](../security/CryptoArchitectureKit/crypto-encryption-decryption-overview.md) + - 加解密算法规格 + - [对称密钥加解密算法规格](../security/CryptoArchitectureKit/crypto-sym-encrypt-decrypt-spec.md) + - [非对称密钥加解密算法规格](../security/CryptoArchitectureKit/crypto-asym-encrypt-decrypt-spec.md) + - 加解密开发指导 + - [使用AES对称密钥（GCM模式）加解密](../security/CryptoArchitectureKit/crypto-aes-sym-encrypt-decrypt-gcm.md) + - [使用AES对称密钥（CBC模式）加解密](../security/CryptoArchitectureKit/crypto-aes-sym-encrypt-decrypt-cbc.md) + - [使用AES对称密钥（GCM模式）分段加解密](../security/CryptoArchitectureKit/crypto-aes-sym-encrypt-decrypt-gcm-by-segment.md) + - [使用3DES对称密钥（ECB模式）加解密](../security/CryptoArchitectureKit/crypto-3des-sym-encrypt-decrypt-ecb.md) + - [使用SM4对称密钥（ECB模式）加解密](../security/CryptoArchitectureKit/crypto-sm4-sym-encrypt-decrypt-ecb.md) + - [使用RSA非对称密钥（PKCS1模式）加解密](../security/CryptoArchitectureKit/crypto-rsa-asym-encrypt-decrypt-pkcs1.md) + - [使用RSA非对称密钥分段加解密](../security/CryptoArchitectureKit/crypto-rsa-asym-encrypt-decrypt-by-segment.md) + - [使用RSA非对称密钥（PKCS1_OAEP模式）加解密](../security/CryptoArchitectureKit/crypto-rsa-asym-encrypt-decrypt-pkcs1_oaep.md) + - [使用SM2非对称密钥加解密](../security/CryptoArchitectureKit/crypto-sm2-asym-encrypt-decrypt.md) + - [使用SM2密文格式转换](../security/CryptoArchitectureKit/crypto-sm2-ciphertext-conversion.md) +- 签名验签 + - [签名验签介绍及算法规格](../security/CryptoArchitectureKit/crypto-sign-sig-verify-overview.md) + - 签名验签开发指导 + - [使用RSA密钥对（PKCS1模式）签名验签](../security/CryptoArchitectureKit/crypto-rsa-sign-sig-verify-pkcs1.md) + - [使用RSA密钥对（PKCS1模式）签名及签名恢复](../security/CryptoArchitectureKit/crypto-rsa-sign-sig-verify-recover-pkcs1.md) + - [使用RSA密钥对分段签名验签（PKCS1模式）](../security/CryptoArchitectureKit/crypto-rsa-sign-sig-verify-pkcs1-by-segment.md) + - [使用RSA密钥对签名验签（PSS模式）](../security/CryptoArchitectureKit/crypto-rsa-sign-sig-verify-pss.md) + - [使用ECDSA密钥对签名验签](../security/CryptoArchitectureKit/crypto-ecdsa-sign-sig-verify.md) + - [使用SM2密钥对签名验签](../security/CryptoArchitectureKit/crypto-sm2-sign-sig-verify-pkcs1.md) +- 密钥协商 + - [密钥协商介绍及算法规格](../security/CryptoArchitectureKit/crypto-key-agreement-overview.md) + - 密钥协商开发指导 + - [使用ECDH进行密钥协商](../security/CryptoArchitectureKit/crypto-key-agreement-using-ecdh.md) + - [使用X25519进行密钥协商](../security/CryptoArchitectureKit/crypto-key-agreement-using-x25519.md) + - [使用DH进行密钥协商](../security/CryptoArchitectureKit/crypto-key-agreement-using-dh.md) +- [消息摘要计算](../security/CryptoArchitectureKit/crypto-generate-message-digest.md) +- [消息认证码计算](../security/CryptoArchitectureKit/crypto-compute-mac.md) +- [安全随机数生成](../security/CryptoArchitectureKit/crypto-generate-random-number.md) +- 密钥派生 + - [使用PBKDF2进行密钥派生](../security/CryptoArchitectureKit/crypto-key-derivation-using-pbkdf2.md) + - [使用HKDF进行密钥派生](../security/CryptoArchitectureKit/crypto-key-derivation-using-hkdf.md) \ No newline at end of file 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 00000000000..f2eac200fd2 --- /dev/null +++ b/zh-cn/application-dev/security/CryptoArchitectureKit/crypto-key-derivation-overview.md @@ -0,0 +1,40 @@ +# 密钥派生 +密钥派生函数（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 | PBKDF2\|SHA1 | 11+ | +| HKDF | SHA224 | PBKDF2\|SHA224 | 11+ | +| HKDF | SHA256 | PBKDF2\|SHA256 | 11+ | +| HKDF | SHA384 | PBKDF2\|SHA384 | 11+ | +| HKDF | SHA512 | PBKDF2\|SHA512 | 11+ | +| HKDF | SM3 | PBKDF2\|SM3 | 11+ | \ 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 00000000000..8a5e22ba07a --- /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 00000000000..308df37c917 --- /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."); + }); + } + ``` -- Gitee