1# 非对称密钥加解密算法规格
2
3
4当前章节将说明系统目前支持的算法及其对应的规格。
5
6
7对于每种算法采用支持的加密模式，将会在具体的每个算法规格中介绍。
8
9
10## RSA
11
12[RSA](crypto-asym-key-generation-conversion-spec.md#rsa)为非对称加密算法，加密长度需要在固定长度进行，在实际应用中，数据量可能无法达到固定的长度要求，此时可以通过不同的填充模式进行数据填充。
13
14算法库目前提供了RSA加解密常用的三种模式有：
15
16- [NoPadding](#填充模式为nopadding)：不带填充，输入的数据必须与RSA钥模（即RSA模数n的字节长度）一样长；输出数据长度与RSA钥模一样长。
17
18- [PKCS1](#填充模式为pkcs1)：即RFC3447规范中的RSAES-PKCS1-V1_5模式，对应OpenSSL中的RSA_PKCS1_PADDING。
19
20  在进行RSA运算时需要将源数据D转化为Encryption block（EB），加密时，输入的数据最大长度 <= RSA钥模 - 11；输出数据长度与RSA钥模一样长。
21
22- [PKCS1_OAEP](#填充模式为pkcs1_oaep)：即RFC3447规范中的RSAES-OAEP模式，对应OpenSSL中的RSA_PKCS1_OAEP_PADDING。
23
24  此模式需要设置两个摘要（md和mgf1_md），加密时，输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2（摘要长度以字节为单位）；输出数据长度与RSA钥模一样长。
25
26  此模式还可额外设置pSource字节流来定义OAEP填充的编码输入，并且可以获取PKCS1_OAEP的相关参数（如表所示）。
27
28  | PKCS1_OAEP的相关参数 | 说明 |
29  | -------- | -------- |
30  | md | 摘要算法。 |
31  | mgf | 掩码生成算法，目前仅支持MGF1。 |
32  | mgf1_md | MGF1算法中使用的摘要算法。 |
33  | pSource | 字节流，用于编码输入。 |
34
35> **注意：**
36>
37> 使用同步接口生成RSA2048、RSA3072、RSA4096、RSA8192非对称密钥或者明文长度超过2048会导致耗时增加。
38>
39> 由于系统对主线程有时间限制，耗时较长会导致失败，建议开发者在生成位数较大的密钥时，使用对应的异步接口，或是[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)进行开发。
40
41### 填充模式为NoPadding
42
43以字符串参数完成RSA加解密，具体的“字符串参数”由“非对称密钥类型”和“填充模式 NoPadding”使用符号“|”拼接而成，用于在创建非对称加解密实例时，指定算法规格。
44
45| 非对称密钥类型 | 字符串参数 | API版本 |
46| -------- | -------- | -------- |
47| RSA512 | RSA512\|NoPadding | 9+ |
48| RSA768 | RSA768\|NoPadding | 9+ |
49| RSA1024 | RSA1024\|NoPadding | 9+ |
50| RSA2048 | RSA2048\|NoPadding | 9+ |
51| RSA3072 | RSA3072\|NoPadding | 9+ |
52| RSA4096 | RSA4096\|NoPadding | 9+ |
53| RSA8192 | RSA8192\|NoPadding | 9+ |
54| RSA | RSA\|NoPadding | 10+ |
55
56如表中最后一行所示，为了兼容由密钥参数生成的密钥，RSA加解密参数输入密钥类型时支持不带长度，加解密运算取决于实际输入的密钥长度。
57
58
59### 填充模式为PKCS1
60
61以字符串参数完成RSA加解密，具体的“字符串参数”由“非对称密钥类型”和“填充模式 PKCS1”使用符号“|”拼接而成，用于在创建非对称加解密实例时，指定算法规格。
62
63| 非对称密钥类型 | 字符串参数 | API版本 |
64| -------- | -------- | -------- |
65| RSA512 | RSA512\|PKCS1 | 9+ |
66| RSA768 | RSA768\|PKCS1 | 9+ |
67| RSA1024 | RSA1024\|PKCS1 | 9+ |
68| RSA2048 | RSA2048\|PKCS1 | 9+ |
69| RSA3072 | RSA3072\|PKCS1 | 9+ |
70| RSA4096 | RSA4096\|PKCS1 | 9+ |
71| RSA8192 | RSA8192\|PKCS1 | 9+ |
72| RSA | RSA\|PKCS1 | 10+ |
73
74如表中最后一行所示，为了兼容由密钥参数生成的密钥，RSA加解密参数输入密钥类型时支持不带长度，加解密运算取决于实际输入的密钥长度。
75
76
77### 填充模式为PKCS1_OAEP
78
79以字符串参数完成RSA加解密，具体的“字符串参数”由“非对称密钥类型”、“填充模式 PKCS1_OAEP”、摘要、掩码摘要，使用符号“|”拼接而成，用于在创建非对称加解密实例时，指定算法规格。
80
81如表所示，各取值范围（即[]中的内容）中，只能选取一项完成字符串拼接。
82
83举例说明，当需要非对称密钥类型为RSA2048、填充模式为PKCS1_OAEP、摘要算法为SHA256、掩码摘要为MGF1_SHA256的RSA密钥，其字符串参数为"RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256"。
84
85> **说明：**
86>
87> 输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2。比如，当RSA密钥为512位时，不支持SHA512。
88
89| 非对称密钥类型 | 填充模式 | 摘要 | 掩码摘要 | API版本 |
90| -------- | -------- | -------- | -------- | -------- |
91| RSA512 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ |
92| RSA512 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ |
93| RSA512 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ |
94| RSA768 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
95| RSA768 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
96| RSA768 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
97| RSA768 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384] | 9+ |
98| RSA1024 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
99| RSA1024 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
100| RSA1024 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
101| RSA1024 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
102| RSA1024 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
103| RSA2048 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
104| RSA2048 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
105| RSA2048 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
106| RSA2048 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
107| RSA2048 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
108| RSA2048 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
109| RSA3072 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
110| RSA3072 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
111| RSA3072 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
112| RSA3072 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
113| RSA3072 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
114| RSA3072 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
115| RSA4096 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
116| RSA4096 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
117| RSA4096 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
118| RSA4096 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
119| RSA4096 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
120| RSA4096 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
121| RSA8192 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
122| RSA8192 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
123| RSA8192 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
124| RSA8192 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
125| RSA8192 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
126| RSA8192 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ |
127| RSA | PKCS1_OAEP | 符合长度要求的摘要算法 | MGF1_符合长度要求的摘要算法 | 10+ |
128
129如表中最后一行所示，为了兼容由密钥参数生成的密钥，RSA加解密参数输入密钥类型时支持不带长度，加解密运算取决于实际输入的密钥长度。
130
131
132### 获取/设置OAEP填充模式的参数
133
134从API版本10开始支持RSA使用PKCS1_OAEP填充模式时，获取、设置相关参数，“√”表示支持对获取或设置该参数。
135
136| OAEP参数 | 枚举值 | 获取 | 设置 |
137| -------- | -------- | -------- | -------- |
138| md | OAEP_MD_NAME_STR | √ | - |
139| mgf | OAEP_MGF_NAME_STR | √ | - |
140| mgf1_md | OAEP_MGF1_MD_STR | √ | - |
141| pSource | OAEP_MGF1_PSRC_UINT8ARR | √ | √ |
142
143
144## SM2
145
146[SM2](crypto-asym-key-generation-conversion-spec.md#sm2)为非对称加密算法，加密长度需要在固定长度进行。算法库目前支持以GM/T 0009-2012定义的格式加密或解密数据。
147
148SM2非对称加密的结果由C1,C2,C3三部分组成。其中C1是根据生成的随机数计算出的椭圆曲线点，C2是密文数据，C3是通过指定摘要算法计算的值。
149
150当前支持以字符串参数完成SM2加解密，具体的“字符串参数”由“非对称密钥类型（加解密算法+密钥长度）”、“摘要算法”使用符号“|”拼接而成，用于在创建对称加解密实例时，指定算法规格。
151
152如表所示，各取值范围（即[]中的内容）中，只能选取一项完成字符串拼接。SM2算法和密钥长度中间采用符号“_”拼接。
153
154举例说明，当密钥长度为256bit、摘要算法为MD5的SM2密钥，其字符串参数为"SM2_256|MD5"。
155| 非对称密钥类型 | 摘要算法 | API版本 |
156| -------- | -------- | -------- |
157| SM2_256 | [MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3] | 10+ |
158| SM2 | [MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3] | 10+ |
159
160如表中最后一行所示，为了兼容由密钥参数生成的密钥，SM2加解密参数输入密钥类型时支持不带长度，加解密运算取决于实际输入的密钥长度。
161
162
163### 获取SM2摘要算法参数
164
165从API版本11开始支持SM2获取摘要算法参数，“√”表示支持对获取或设置该参数。
166
167| SM2加解密参数 | 枚举值 | 获取 | 设置 |
168| -------- | -------- | -------- | -------- |
169| md | SM2_MD_NAME_STR | √ | - |
170
171
172### 转换SM2密文格式
173
174从API版本12开始，支持SM2格式转换。当前支持的SM2密文格式为国密标准的ASN.1格式，其中各参数组合顺序为C1C3C2。
175
176开发者可指定SM2密文的参数，将其转换成符合国密标准的ASN.1格式密文。反之，也可以从国密标准的ASN.1格式密文中提取具体的SM2密文参数，便于开发者自行组合成其他格式的SM2密文。
177
178SM2密文参数，包括：
179
180- xCoordinate：x分量，即C1_X。
181
182- yCoordinate：y分量，即C1_Y。xCoordinate和yCoordinate可以转换成C1。
183
184- cipherTextData：密文，即C2。
185
186- hashData：杂凑值，即C3。
187
188当前支持以字符串参数指定SM2密文格式转换的模式，如下表所示：
189
190| SM2密文格式转换模式 | 基于参数生成SM2密文 | 从SM2密文中获取参数 |
191| --------  | -------- | -------- |
192| C1C3C2 | √ | √ |