!12558 【HUKS】开发资料架构优化

Merge pull request !12558 from wkyrong/master

zh-cn/application-dev/security/Readme-CN.md

@@ -8,9 +8,10 @@
 - 用户认证
   - [用户认证开发概述](userauth-overview.md)
   - [用户认证开发指导](userauth-guidelines.md)
-- 密钥管理
-  - [HUKS开发概述](huks-overview.md)
-  - [HUKS开发指导](huks-guidelines.md)
+- 通用密钥库
+  - [通用密钥库开发概述](huks-overview.md)
+  - [通用密钥库开发指导](huks-guidelines.md)
+  - [通用密钥库密码算法规格](huks-appendix.md)
 - 加密算法库框架
   - [加密算法库框架概述](cryptoFramework-overview.md)
   - [加密算法框架开发指导](cryptoFramework-guidelines.md)

zh-cn/application-dev/security/huks-appendix.md

+# 通用密钥库密码算法规格
+
+## 支持的算法类型及参数组合
+
+### 导入\生成密钥规格
+
+| 算法                        | API级别 | 支持的密钥长度     |
+| -------------- | :---------------: | ------------------ |
+| AES    |        8+         | 128、192、256 |
+| RSA    |        8+         | 512、768、1024、2048、3072、4096 |
+| HMAC   |        8+         | 8-1024（含），必须是8的倍数   |
+| ECC    |        8+         | 224、256、384、521 |
+| ED25519 |        8+         | 256    |
+| X25519  |        8+         | 256    |
+| DSA    |        8+         | 8-1024（含），8的倍数    |
+| DH    |        8+         | 2048、3072、4096                |
+| SM2    |        9+         | 256                |
+| SM3    |        9+         | 256                |
+| SM4    |        9+         | 128                |
+
+### 加密解密
+
+| 算法                     | API级别 | 备注                                                         |
+| ----------------------- | :----: | ---------------- |
+| AES/CBC/NoPadding<br>AES/ECB/NoPadding<br>AES/CTR/NoPadding<br>AES/GCM/NoPadding<br>AES/CBC/PKCS7<br>AES/ECB/PKCS7 | 8+                | 1. CBC\ECB\CTR模式IV参数必选<br>2. GCM模式下Nonce、AAD、AEAD参数必选   |
+| RSA/ECB/NoPadding<br>RSA/ECB/PKCS1_V1_5<br>RSA/ECB/OAEP             | 8+                |    |
+| SM4/CTR/NoPadding<br>SM4/ECB/NoPadding<br>SM4/CBC/NoPadding<br>SM4/ECB/PKCS7<br>SM4/CBC/PKCS7 | 9+                |   |
+
+
+
+### 签名验签
+
+
+| 算法      | API级别 | 备注     |
+| --------- | :----------: | ----------------- |
+| RSA/MD5/PKCS1_V1_5<br>RSA/SHA1/PKCS1_V1_5<br>RSA/SHA224/PKCS1_V1_5<br>RSA/SHA256/PKCS1_V1_5<br>RSA/SHA384/PKCS1_V1_5<br>RSA/SHA512/PKCS1_V1_5<br>RSA/SHA1/PSS<br>RSA/SHA224/PSS<br>RSA/SHA256/PSS<br>RSA/SHA384/PSS | 8+                | | 
+| RSA/NoDigest/PKCS1_V1_5 | 9+                | | 
+| DSA/SHA1<br>DSA/SHA224<br>DSA/SHA256<br>DSA/SHA384<br>DSA/SHA512     |  8+                | |
+| DSA/NoDigest     |  9+                | |
+| ECC/SHA1<br>ECC/SHA224<br>ECC/SHA256<br>ECC/SHA384<br>ECC/SHA512      | 8+                | |
+| ECC/NoDigest     |  9+                | |
+| ED25519/SHA1<br>ED25519/SHA224<br>ED25519/SHA256<br>ED25519/SHA384<br>ED25519/SHA512 |8+                | |
+| ED25519/NoDigest     |  9+                | |
+| SM2/SM3<br>SM2/NoDigest |9+                | |
+
+### 密钥协商
+
+| 算法   &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   | API级别 | 备注     |
+| ------ | :-----------: | ------------------------------ |
+| ECDH    | 8+   |  协商密钥类型为ECC类型密钥  |
+| DH        | 8+  |             |
+| X25519  | 8+  |             |
+
+### 密钥派生
+
+| 算法 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |API级别         | 派生密钥及长度              | 备注                  |
+| ------------------------- | :-----------: | ------------ | ----------------- |
+| HKDF/SHA256<br>HKDF/SHA384<br>HKDF/SHA512   | 8+ | 算法：AES、HMAC、SM4 长度：256、384、512 | 派生出的密钥可以存储到HUKS或者直接返回明文 |
+| PBKDF2/SHA256<br>PBKDF2/SHA384<br>PBKDF2/SHA512    | 8+ | 算法：AES、HMAC、SM4 长度：256、384、512 | 派生出的密钥可以存储到HUKS或者直接返回明文 |
+
+### 密钥证明
+
+| 算法 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |API级别	| 备注                                            |
+| ------------------ | :-----: | ------------------------------------------------------------ |
+| RSA | 9+ |  仅支持Padding为PSS的密钥 |
+| ECC                | 9+ |   |
+| X25519             | 9+ |   |
+
+## 密钥材料格式
+针对不同密码算法的密钥对、公钥、私钥，HUKS定义了一套密钥材料格式。
+
+### 密钥对材料
+**密钥对材料 = 密钥对材料Header + 密钥对材料原文**
+
+以RSA密钥为例，应用需要申请一个Uint8Array，按照RSA密钥对材料内存格式，将各个变量赋值到对应的位置：
+
+**图4** RSA密钥材料内存结构
+
+![huks_keymaterial_struct](figures/huks_keymaterial_struct.png)
+
+```ts
+let rsa2048KeyPairMaterial = new Uint8Array([
+    0x01, 0x00, 0x00, 0x00, // 密钥算法：huks.HuksKeyAlg.HUKS_ALG_RSA = 1
+    0x00, 0x08, 0x00, 0x00, // 密钥大小（比特）：2048
+    0x00, 0x01, 0x00, 0x00, // 模数n长度（字节）：256
+    0x03, 0x00, 0x00, 0x00, // 公钥指数e长度（字节）：3
+    0x00, 0x01, 0x00, 0x00, // 私钥指数d长度（字节）：256
+    // 模数n
+    0xc5, 0x35, 0x62, 0x48, 0xc4, 0x92, 0x87, 0x73, 0x0d, 0x42, 0x96, 0xfc, 0x7b, 0x11, 0x05, 0x06,
+    0x0f, 0x8d, 0x66, 0xc1, 0x0e, 0xad, 0x37, 0x44, 0x92, 0x95, 0x2f, 0x6a, 0x55, 0xba, 0xec, 0x1d,
+    0x54, 0x62, 0x0a, 0x4b, 0xd3, 0xc7, 0x05, 0xe4, 0x07, 0x40, 0xd9, 0xb7, 0xc2, 0x12, 0xcb, 0x9a,
+    0x90, 0xad, 0xe3, 0x24, 0xe8, 0x5e, 0xa6, 0xf8, 0xd0, 0x6e, 0xbc, 0xd1, 0x69, 0x7f, 0x6b, 0xe4,
+    0x2b, 0x4e, 0x1a, 0x65, 0xbb, 0x73, 0x88, 0x6b, 0x7c, 0xaf, 0x7e, 0xd0, 0x47, 0x26, 0xeb, 0xa5,
+    0xbe, 0xd6, 0xe8, 0xee, 0x9c, 0xa5, 0x66, 0xa5, 0xc9, 0xd3, 0x25, 0x13, 0xc4, 0x0e, 0x6c, 0xab,
+    0x50, 0xb6, 0x50, 0xc9, 0xce, 0x8f, 0x0a, 0x0b, 0xc6, 0x28, 0x69, 0xe9, 0x83, 0x69, 0xde, 0x42,
+    0x56, 0x79, 0x7f, 0xde, 0x86, 0x24, 0xca, 0xfc, 0xaa, 0xc0, 0xf3, 0xf3, 0x7f, 0x92, 0x8e, 0x8a,
+    0x12, 0x52, 0xfe, 0x50, 0xb1, 0x5e, 0x8c, 0x01, 0xce, 0xfc, 0x7e, 0xf2, 0x4f, 0x5f, 0x03, 0xfe,
+    0xa7, 0xcd, 0xa1, 0xfc, 0x94, 0x52, 0x00, 0x8b, 0x9b, 0x7f, 0x09, 0xab, 0xa8, 0xa4, 0xf5, 0xb4,
+    0xa5, 0xaa, 0xfc, 0x72, 0xeb, 0x17, 0x40, 0xa9, 0xee, 0xbe, 0x8f, 0xc2, 0xd1, 0x80, 0xc2, 0x0d,
+    0x44, 0xa9, 0x59, 0x44, 0x59, 0x81, 0x3b, 0x5d, 0x4a, 0xde, 0xfb, 0xae, 0x24, 0xfc, 0xa3, 0xd9,
+    0xbc, 0x57, 0x55, 0xc2, 0x26, 0xbc, 0x19, 0xa7, 0x9a, 0xc5, 0x59, 0xa3, 0xee, 0x5a, 0xef, 0x41,
+    0x80, 0x7d, 0xf8, 0x5e, 0xc1, 0x1d, 0x32, 0x38, 0x41, 0x5b, 0xb6, 0x92, 0xb8, 0xb7, 0x03, 0x0d,
+    0x3e, 0x59, 0x0f, 0x1c, 0xb3, 0xe1, 0x2a, 0x95, 0x1a, 0x3b, 0x50, 0x4f, 0xc4, 0x1d, 0xcf, 0x73,
+    0x7c, 0x14, 0xca, 0xe3, 0x0b, 0xa7, 0xc7, 0x1a, 0x41, 0x4a, 0xee, 0xbe, 0x1f, 0x43, 0xdd, 0xf9,
+    // 公钥指数e
+    0x01, 0x00, 0x01,
+    // 私钥指数d
+    0x88, 0x4b, 0x82, 0xe7, 0xe3, 0xe3, 0x99, 0x75, 0x6c, 0x9e, 0xaf, 0x17, 0x44, 0x3e, 0xd9, 0x07,
+    0xfd, 0x4b, 0xae, 0xce, 0x92, 0xc4, 0x28, 0x44, 0x5e, 0x42, 0x79, 0x08, 0xb6, 0xc3, 0x7f, 0x58,
+    0x2d, 0xef, 0xac, 0x4a, 0x07, 0xcd, 0xaf, 0x46, 0x8f, 0xb4, 0xc4, 0x43, 0xf9, 0xff, 0x5f, 0x74,
+    0x2d, 0xb5, 0xe0, 0x1c, 0xab, 0xf4, 0x6e, 0xd5, 0xdb, 0xc8, 0x0c, 0xfb, 0x76, 0x3c, 0x38, 0x66,
+    0xf3, 0x7f, 0x01, 0x43, 0x7a, 0x30, 0x39, 0x02, 0x80, 0xa4, 0x11, 0xb3, 0x04, 0xd9, 0xe3, 0x57,
+    0x23, 0xf4, 0x07, 0xfc, 0x91, 0x8a, 0xc6, 0xcc, 0xa2, 0x16, 0x29, 0xb3, 0xe5, 0x76, 0x4a, 0xa8,
+    0x84, 0x19, 0xdc, 0xef, 0xfc, 0xb0, 0x63, 0x33, 0x0b, 0xfa, 0xf6, 0x68, 0x0b, 0x08, 0xea, 0x31,
+    0x52, 0xee, 0x99, 0xef, 0x43, 0x2a, 0xbe, 0x97, 0xad, 0xb3, 0xb9, 0x66, 0x7a, 0xae, 0xe1, 0x8f,
+    0x57, 0x86, 0xe5, 0xfe, 0x14, 0x3c, 0x81, 0xd0, 0x64, 0xf8, 0x86, 0x1a, 0x0b, 0x40, 0x58, 0xc9,
+    0x33, 0x49, 0xb8, 0x99, 0xc6, 0x2e, 0x94, 0x70, 0xee, 0x09, 0x88, 0xe1, 0x5c, 0x4e, 0x6c, 0x22,
+    0x72, 0xa7, 0x2a, 0x21, 0xdd, 0xd7, 0x1d, 0xfc, 0x63, 0x15, 0x0b, 0xde, 0x06, 0x9c, 0xf3, 0x28,
+    0xf3, 0xac, 0x4a, 0xa8, 0xb5, 0x50, 0xca, 0x9b, 0xcc, 0x0a, 0x04, 0xfe, 0x3f, 0x98, 0x68, 0x81,
+    0xac, 0x24, 0x53, 0xea, 0x1f, 0x1c, 0x6e, 0x5e, 0xca, 0xe8, 0x31, 0x0d, 0x08, 0x12, 0xf3, 0x26,
+    0xf8, 0x5e, 0xeb, 0x10, 0x27, 0xae, 0xaa, 0xc3, 0xad, 0x6c, 0xc1, 0x89, 0xdb, 0x7d, 0x5a, 0x12,
+    0x55, 0xad, 0x11, 0x19, 0xa1, 0xa9, 0x8f, 0x0b, 0x6d, 0x78, 0x8d, 0x1c, 0xdf, 0xe5, 0x63, 0x82,
+    0x0b, 0x7d, 0x23, 0x04, 0xb4, 0x75, 0x8c, 0xed, 0x77, 0xfc, 0x1a, 0x85, 0x29, 0x11, 0xe0, 0x61,
+    ]);
+```
+
+其中，密钥算法的值取自枚举类[HuksKeyAlg](../reference/apis/js-apis-huks.md#hukskeyalg)。
+
+- **RSA密钥对材料格式：**
+    | 密钥算法 | 密钥大小 | 模数n长度L<sub>n</sub> | 公钥指数e长度L<sub>e</sub> | 私钥指数d长度L<sub>d</sub> | n | e | d |
+    | :----: |:----:|:----:|:----:|:----:|:----:|:----:|:----:|
+    |4字节|4字节|4字节|4字节|4字节|L<sub>n</sub>字节 |L<sub>e</sub>字节 |L<sub>d</sub>字节 |
+
+
+- **ECC密钥对材料格式：**
+    | 密钥算法 | 密钥大小 | 坐标x长度L<sub>x</sub> | 坐标y长度L<sub>y</sub> | 坐标z长度L<sub>z</sub> | x | y | z |
+    | :----: |:----:|:----:|:----:|:----:|:----:|:----:|:----:|
+    |4字节|4字节|4字节|4字节|4字节|L<sub>x</sub>字节 |L<sub>y</sub>字节 |L<sub>z</sub>字节 |
+
+
+- **DSA密钥对材料格式：**
+    | 密钥算法 | 密钥大小 | 私钥x长度L<sub>x</sub> | 公钥y长度L<sub>y</sub> | 素数p长度L<sub>p</sub> | 素因子q长度L<sub>q</sub> | g长度L<sub>g</sub> | x | y | p | q | g |
+    | :----: |:----:|:----:|:----:|:----:|:----:|:----:|:----:|:----:|:----:|:----:|:----:|
+    |4字节|4字节|4字节|4字节|4字节|4字节|4字节|L<sub>x</sub>字节 |L<sub>y</sub>字节 |L<sub>p</sub>字节 |L<sub>q</sub>字节 |L<sub>g</sub>字节 |
+
+
+- **DH密钥对材料格式：**
+    | 密钥算法 | 密钥大小 | 公钥pk长度L<sub>pk</sub> | 私钥sk长度L<sub>sk</sub> | 保留字段 | pk | sk |
+    |:----:|:----:|:----:|:----:|:----:|:----:|:----:|
+    |4字节|4字节|4字节|4字节|4字节|L<sub>pk</sub>字节 |L<sub>sk</sub>字节 |
+
+
+- **Curve25519密钥对材料格式：**
+    | 密钥算法 | 密钥大小 | 公钥pk长度L<sub>pk</sub> | 私钥sk长度L<sub>sk</sub> | 保留字段 | pk | sk |
+    |:----:|:----:|:----:|:----:|:----:|:----:|:----:|
+    |4字节|4字节|4字节|4字节|4字节|L<sub>pk</sub>字节 |L<sub>sk</sub>字节 |
+
+
+### 公钥材料
+
+在公钥导出/导入时，密钥材料采用标准的X.509规范的DER格式封装。
+
+如下是一个DER编码的ECC公钥：
+```ts
+let eccP256PubKey = new Uint8Array([
+  0x30, 0x59, 0x30, 0x13, 0x06, 0x07, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01, 0x06, 0x08, 0x2a,
+  0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07, 0x03, 0x42, 0x00, 0x04, 0xc0, 0xfe, 0x1c, 0x67, 0xde,
+  0x86, 0x0e, 0xfb, 0xaf, 0xb5, 0x85, 0x52, 0xb4, 0x0e, 0x1f, 0x6c, 0x6c, 0xaa, 0xc5, 0xd9, 0xd2,
+  0x4d, 0xb0, 0x8a, 0x72, 0x24, 0xa1, 0x99, 0xaf, 0xfc, 0x3e, 0x55, 0x5a, 0xac, 0x99, 0x3d, 0xe8,
+  0x34, 0x72, 0xb9, 0x47, 0x9c, 0xa6, 0xd8, 0xfb, 0x00, 0xa0, 0x1f, 0x9f, 0x7a, 0x41, 0xe5, 0x44,
+  0x3e, 0xb2, 0x76, 0x08, 0xa2, 0xbd, 0xe9, 0x41, 0xd5, 0x2b, 0x9e]);
+```
+
+### 私钥材料
+
+复用密钥对的材料格式，私钥材料的封装是把密钥对材料Header中的公钥部分的长度字段置0，同时密钥对材料原文部分拼接私钥材料即可。
+
+**私钥材料 = 密钥对材料Header + 私钥材料原文**
+
+以RSA私钥材料为例：
+
+![huks_keymaterial_rsa_priv_struct](figures/huks_keymaterial_rsa_priv_struct.png)
+
+```ts
+let rsa2048PrivateKeyMaterial = new Uint8Array([
+    0x01, 0x00, 0x00, 0x00, // 密钥算法：huks.HuksKeyAlg.HUKS_ALG_RSA = 1
+    0x00, 0x08, 0x00, 0x00, // 密钥大小（比特）：2048
+    0x00, 0x01, 0x00, 0x00, // 模数n长度（字节）：256
+    0x00, 0x00, 0x00, 0x00, // 公钥指数e长度（字节）：0
+    0x00, 0x01, 0x00, 0x00, // 私钥指数d长度（字节）：256
+    // 模数n
+    0xc5, 0x35, 0x62, 0x48, 0xc4, 0x92, 0x87, 0x73, 0x0d, 0x42, 0x96, 0xfc, 0x7b, 0x11, 0x05, 0x06,
+    0x0f, 0x8d, 0x66, 0xc1, 0x0e, 0xad, 0x37, 0x44, 0x92, 0x95, 0x2f, 0x6a, 0x55, 0xba, 0xec, 0x1d,
+    0x54, 0x62, 0x0a, 0x4b, 0xd3, 0xc7, 0x05, 0xe4, 0x07, 0x40, 0xd9, 0xb7, 0xc2, 0x12, 0xcb, 0x9a,
+    0x90, 0xad, 0xe3, 0x24, 0xe8, 0x5e, 0xa6, 0xf8, 0xd0, 0x6e, 0xbc, 0xd1, 0x69, 0x7f, 0x6b, 0xe4,
+    0x2b, 0x4e, 0x1a, 0x65, 0xbb, 0x73, 0x88, 0x6b, 0x7c, 0xaf, 0x7e, 0xd0, 0x47, 0x26, 0xeb, 0xa5,
+    0xbe, 0xd6, 0xe8, 0xee, 0x9c, 0xa5, 0x66, 0xa5, 0xc9, 0xd3, 0x25, 0x13, 0xc4, 0x0e, 0x6c, 0xab,
+    0x50, 0xb6, 0x50, 0xc9, 0xce, 0x8f, 0x0a, 0x0b, 0xc6, 0x28, 0x69, 0xe9, 0x83, 0x69, 0xde, 0x42,
+    0x56, 0x79, 0x7f, 0xde, 0x86, 0x24, 0xca, 0xfc, 0xaa, 0xc0, 0xf3, 0xf3, 0x7f, 0x92, 0x8e, 0x8a,
+    0x12, 0x52, 0xfe, 0x50, 0xb1, 0x5e, 0x8c, 0x01, 0xce, 0xfc, 0x7e, 0xf2, 0x4f, 0x5f, 0x03, 0xfe,
+    0xa7, 0xcd, 0xa1, 0xfc, 0x94, 0x52, 0x00, 0x8b, 0x9b, 0x7f, 0x09, 0xab, 0xa8, 0xa4, 0xf5, 0xb4,
+    0xa5, 0xaa, 0xfc, 0x72, 0xeb, 0x17, 0x40, 0xa9, 0xee, 0xbe, 0x8f, 0xc2, 0xd1, 0x80, 0xc2, 0x0d,
+    0x44, 0xa9, 0x59, 0x44, 0x59, 0x81, 0x3b, 0x5d, 0x4a, 0xde, 0xfb, 0xae, 0x24, 0xfc, 0xa3, 0xd9,
+    0xbc, 0x57, 0x55, 0xc2, 0x26, 0xbc, 0x19, 0xa7, 0x9a, 0xc5, 0x59, 0xa3, 0xee, 0x5a, 0xef, 0x41,
+    0x80, 0x7d, 0xf8, 0x5e, 0xc1, 0x1d, 0x32, 0x38, 0x41, 0x5b, 0xb6, 0x92, 0xb8, 0xb7, 0x03, 0x0d,
+    0x3e, 0x59, 0x0f, 0x1c, 0xb3, 0xe1, 0x2a, 0x95, 0x1a, 0x3b, 0x50, 0x4f, 0xc4, 0x1d, 0xcf, 0x73,
+    0x7c, 0x14, 0xca, 0xe3, 0x0b, 0xa7, 0xc7, 0x1a, 0x41, 0x4a, 0xee, 0xbe, 0x1f, 0x43, 0xdd, 0xf9,
+    // 私钥指数d
+    0x88, 0x4b, 0x82, 0xe7, 0xe3, 0xe3, 0x99, 0x75, 0x6c, 0x9e, 0xaf, 0x17, 0x44, 0x3e, 0xd9, 0x07,
+    0xfd, 0x4b, 0xae, 0xce, 0x92, 0xc4, 0x28, 0x44, 0x5e, 0x42, 0x79, 0x08, 0xb6, 0xc3, 0x7f, 0x58,
+    0x2d, 0xef, 0xac, 0x4a, 0x07, 0xcd, 0xaf, 0x46, 0x8f, 0xb4, 0xc4, 0x43, 0xf9, 0xff, 0x5f, 0x74,
+    0x2d, 0xb5, 0xe0, 0x1c, 0xab, 0xf4, 0x6e, 0xd5, 0xdb, 0xc8, 0x0c, 0xfb, 0x76, 0x3c, 0x38, 0x66,
+    0xf3, 0x7f, 0x01, 0x43, 0x7a, 0x30, 0x39, 0x02, 0x80, 0xa4, 0x11, 0xb3, 0x04, 0xd9, 0xe3, 0x57,
+    0x23, 0xf4, 0x07, 0xfc, 0x91, 0x8a, 0xc6, 0xcc, 0xa2, 0x16, 0x29, 0xb3, 0xe5, 0x76, 0x4a, 0xa8,
+    0x84, 0x19, 0xdc, 0xef, 0xfc, 0xb0, 0x63, 0x33, 0x0b, 0xfa, 0xf6, 0x68, 0x0b, 0x08, 0xea, 0x31,
+    0x52, 0xee, 0x99, 0xef, 0x43, 0x2a, 0xbe, 0x97, 0xad, 0xb3, 0xb9, 0x66, 0x7a, 0xae, 0xe1, 0x8f,
+    0x57, 0x86, 0xe5, 0xfe, 0x14, 0x3c, 0x81, 0xd0, 0x64, 0xf8, 0x86, 0x1a, 0x0b, 0x40, 0x58, 0xc9,
+    0x33, 0x49, 0xb8, 0x99, 0xc6, 0x2e, 0x94, 0x70, 0xee, 0x09, 0x88, 0xe1, 0x5c, 0x4e, 0x6c, 0x22,
+    0x72, 0xa7, 0x2a, 0x21, 0xdd, 0xd7, 0x1d, 0xfc, 0x63, 0x15, 0x0b, 0xde, 0x06, 0x9c, 0xf3, 0x28,
+    0xf3, 0xac, 0x4a, 0xa8, 0xb5, 0x50, 0xca, 0x9b, 0xcc, 0x0a, 0x04, 0xfe, 0x3f, 0x98, 0x68, 0x81,
+    0xac, 0x24, 0x53, 0xea, 0x1f, 0x1c, 0x6e, 0x5e, 0xca, 0xe8, 0x31, 0x0d, 0x08, 0x12, 0xf3, 0x26,
+    0xf8, 0x5e, 0xeb, 0x10, 0x27, 0xae, 0xaa, 0xc3, 0xad, 0x6c, 0xc1, 0x89, 0xdb, 0x7d, 0x5a, 0x12,
+    0x55, 0xad, 0x11, 0x19, 0xa1, 0xa9, 0x8f, 0x0b, 0x6d, 0x78, 0x8d, 0x1c, 0xdf, 0xe5, 0x63, 0x82,
+    0x0b, 0x7d, 0x23, 0x04, 0xb4, 0x75, 0x8c, 0xed, 0x77, 0xfc, 0x1a, 0x85, 0x29, 0x11, 0xe0, 0x61,
+    ]);
+```
+

zh-cn/application-dev/security/huks-overview.md

-# HUKS开发概述
+# 通用密钥库开发概述
 
-## 功能简介
+## 简介
+
+OpenHarmony通用密钥库系统（英文全称：Open**H**armony **U**niversal **K**ey**S**tore，以下简称HUKS）是OpenHarmony提供的系统级的密钥管理系统服务，提供密钥的全生命周期管理能力，包括密钥生成、密钥存储、密钥使用、密钥销毁等功能，以及对存储在HUKS中的密钥提供合法性证明。
+HUKS基于系统安全能力，为业务提供密钥全生命周期的安全管理，业务无需自己实现，利用HUKS的系统能力，就能确保业务密钥的安全。
+
+
+以下目录文档主要介绍了HUKS在典型场景下的用法、原理以及支持的密码算法规格。
+
+- [生成新密钥](huks-guidelines.md#生成新密钥)
+- [导入外部密钥](huks-guidelines.md#导入外部密钥)
+- [常见密钥操作](huks-guidelines.md#常见密钥操作)
+- [密钥访问控制](huks-guidelines.md#密钥访问控制)
+- [密钥证明](huks-guidelines.md#密钥证明)
+- [支持的算法类型及参数组合](huks-appendix.md#支持的算法类型及参数组合)
+- [密钥材料格式](huks-appendix.md#密钥材料格式)
 
-HUKS（OpenHarmony Universal KeyStore）向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。HUKS所管理的密钥可以由应用导入或者由应用调用HUKS接口生成。 
 
 ## 基本概念
 
-- HUKS提供密钥管理功能，支持的主要操作包括：加密解密、签名验签、派生协商密钥、计算HMAC（Hash-based Message Authentication Code）。
-- HUKS涉及的算法主要有：AES加密解密、RSA加密解密、RSA签名验签、ECC签名验签、DSA签名验签、ED25519签名验签、PBKDF2派生、DH协商、ECDH协商、X25519协商等。
-- HUKS当前使用的算法库为OpenSSL和mbed TLS。
+在使用HUKS开发之前，建议了解以下基本概念：
+
+- **HUKS Core**
+  
+  HUKS核心组件，承载HUKS的核心功能，包括密钥的密码学运算、明文密钥的加解密、密钥访问控制等。一般运行在设备的安全环境中（如TEE、安全芯片等，不同的厂商有所不同），保证密钥明文不出HUKS Core。
+
+  
+- **密钥会话** 
+
+  应用通过指定密钥别名，给当前操作的密钥建立一个会话，HUKS为每个会话生成一个全局唯一的句柄值来索引该会话。它的作用是缓存密钥使用期间的信息，包括操作数据、密钥信息、访问控制属性等。密钥操作一般需要经过**建立会话、传入数据和参数、结束会话（中止会话）** 三个阶段。
+
 
-## 运作机制
+## 实现原理
 
-HUKS对密钥的使用主要通过InitSession、UpdateSession、FinishSession操作来实现。
 
-- **InitSession操作**：读取密钥，并为其创建Session Id返回给调用者。
+HUKS的核心安全设计包括以下几点：
+- **密钥不出安全环境**
 
-- **UpdateSession操作**：根据InitSession操作获取的Session Id对数据进行分段updateSession处理。
+  HUKS的核心特点是密钥全生命周期明文不出HUKS Core，在有硬件条件的设备上，如有TEE（Trusted Execution Environment)或安全芯片的设备，HUKS Core运行在硬件安全环境中。能确保即使REE（Rich Execution Environment）环境被攻破，密钥明文也不会泄露。
+- **系统级安全加密存储**
 
-- **FinishSession操作**：当所有待处理的数据均传入HUKS后，调用FinishSession操作完成最终数据处理，释放资源。
+  基于设备根密钥加密业务密钥，在有条件的设备上，叠加用户口令加密保护密钥。
+- **严格的访问控制**
 
-> **须知：**<br>
-> 当InitSession、UpdateSession、FinishSession操作中的任一阶段发生错误时，都需要调用AbortSession操作来终止密钥的使用。
+  只有合法的业务才有权访问密钥，同时支持用户身份认证访问控制以支持业务的高安敏感场景下安全访问密钥的诉求。
+- **密钥的合法性证明**
 
+  可为业务提供硬件厂商级别的密钥的合法性证明，证明密钥没有被篡改，并确实存在于有硬件保护的HUKS Core中，以及拥有正确的密钥属性。
+
+
+此外，密钥会话是HUKS中承载密钥使用的基础，它的主要作用是初始化密钥信息、缓存业务数据等。对数据的密码学运算和对密钥密文的加解密都是在HUKS Core中进行，以此保证密钥明文和运算过程的安全。
+
+**图1** HUKS运行机制
+
+![huks_architect](figures/huks_architect.png)
 
 ## 约束与限制
-不涉及。
+
+  - **基于别名的访问**
+      
+    由于密钥材料不出HUKS的限制，应用只能以别名的方式访问密钥材料，而且密钥的别名必须保证应用内唯一(否则已存在的同别名密钥会被覆盖），长度不能超过64个字节。
+    
+  - **数据分片大小限制** 
+  
+    所有数据需要经过IPC通道传输到HUKS，受IPC缓冲区大小限制，建议对总大小超过100K的数据进行分片传输，且分片大小不超过100K。
+    
+  - **指定必选参数** 
+
+    在**生成密钥或导入密钥时**，必须指定密码算法、密钥大小和使用目的参数，其他参数可选（如工作模式、填充模式、散列算法等），但是在**使用密钥**时必须传入密码算法相关的完整的参数。
+    
+  - **密钥材料格式** 
+  
+    导入/导出密钥时（包括密钥对、公钥、私钥），密钥材料的数据格式必须满足HUKS要求的格式，具体各个密码算法密钥材料见[密钥材料格式](huks-appendix.md#密钥材料格式)。
+