1# 非对称密钥生成和转换规格
2
3
4当前章节将说明系统目前支持的算法及其对应的规格。密钥生成有两种指定规格的方式,分别是:
5
6
7- 字符串参数:以字符串的形式描述开发者需要生成的密钥规格。
8
9- 密钥参数:使用密钥的详细密码学信息,构造密钥对象。
10
11
12对于每种算法采用哪种方式,将会在具体的每个算法规格中介绍。
13
14## RSA
15
16RSA(Rivest–Shamir–Adleman),当前支持使用字符串参数和密钥参数两种方式生成RSA密钥。
17
18### 使用字符串参数生成
19
20以字符串参数生成RSA密钥,具体的“字符串参数”由“RSA密钥类型”和“素数个数”使用符号“|”拼接而成,用于在创建非对称密钥生成器时,指定密钥规格。
21
22> **说明:**
23>
24> 生成RSA非对称密钥时,默认素数为2,PRIMES_2参数可省略。
25
26| RSA密钥类型 | 素数个数 | 字符串参数 | API版本 |
27| -------- | -------- | -------- | -------- |
28| RSA512 | 2 | RSA512\|PRIMES_2 | 9+ |
29| RSA768 | 2 | RSA768\|PRIMES_2 | 9+ |
30| RSA1024 | 2 | RSA1024\|PRIMES_2 | 9+ |
31| RSA1024 | 3 | RSA1024\|PRIMES_3 | 9+ |
32| RSA2048 | 2 | RSA2048\|PRIMES_2 | 9+ |
33| RSA2048 | 3 | RSA2048\|PRIMES_3 | 9+ |
34| RSA3072 | 2 | RSA3072\|PRIMES_2 | 9+ |
35| RSA3072 | 3 | RSA3072\|PRIMES_3 | 9+ |
36| RSA4096 | 2 | RSA4096\|PRIMES_2 | 9+ |
37| RSA4096 | 3 | RSA4096\|PRIMES_3 | 9+ |
38| RSA4096 | 4 | RSA4096\|PRIMES_4 | 9+ |
39| RSA8192 | 2 | RSA8192\|PRIMES_2 | 9+ |
40| RSA8192 | 3 | RSA8192\|PRIMES_3 | 9+ |
41| RSA8192 | 4 | RSA8192\|PRIMES_4 | 9+ |
42| RSA8192 | 5 | RSA8192\|PRIMES_5 | 9+ |
43
44
45> **注意:**
46>
47> 使用同步接口生成RSA2048、RSA3072、RSA4096、RSA8192非对称密钥会导致耗时增加。
48>
49> 由于系统对主线程有时间限制,耗时较长会导致失败,建议开发者在生成位数较大的密钥时,使用对应的异步接口,或是[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)进行开发。
50>
51> 创建的RSA非对称密钥生成器,如果用于随机生成密钥,则生成的RSA密钥的规格与创建密钥生成器时参数中指定的密钥规格一致;如果用于密钥转换,则生成的RSA密钥的规格与密钥转换时参数中指定的密钥数据的密钥规格一致。
52
53### 使用密钥参数生成
54
55从API版本10开始支持,使用密钥参数生成RSA密钥。
56
57RSA密钥参数,涉及三个整数,包括:
58
59- n:模数(Modulus),是私钥和公钥的公共参数。
60
61- sk:私钥指数(privateExponent),公式中常写作d。
62
63- pk:公钥指数(publicExponent),公式中常写作e。
64
65当创建非对称密钥生成器时,对于指定公/私钥参数生成RSA密钥的支持情况如表所示:
66
67- √:表示需要指定这一列中的具体属性,来构成密钥参数。
68
69- ×:表示这一列中的具体属性对应某种密钥参数,但是当前不支持通过该密钥参数生成密钥。
70
71|  | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 |
72| -------- | -------- | -------- | -------- | -------- |
73| n | × | √ | × | √ |
74| pk | - | √ | - | √ |
75| sk | - | - | × | √ |
76
77由上表可知:
78
79- RSA不支持通过指定公共参数(n)来随机生成密钥。
80
81- RSA不支持通过指定私钥参数(n, sk)来生成私钥。
82
83
84## ECC
85
86ECC(Elliptic Curve Cryptography),是一种基于椭圆曲线数学的公钥密码算法。
87
88椭圆曲线算法可以看作是定义在特殊集合下数的运算,当前算法库支持的ECC密钥均为Fp域的椭圆曲线,p为素数,Fp域也称素数域。
89
90当前支持使用字符串参数和密钥参数两种方式生成ECC密钥,且支持通过曲线名生成公共密钥参数。
91
92
93### 使用字符串参数生成
94
95以字符串参数生成ECC密钥,具体的“字符串参数”由“非对称密钥算法”和“密钥长度”拼接而成,用于在创建非对称密钥生成器时,指定密钥规格。
96
97| 非对称密钥算法 | 密钥长度(bit) | 曲线名 | 字符串参数 | API版本 |
98| -------- | -------- | -------- | -------- | -------- |
99| ECC | 224 | NID_secp224r1 | ECC224 | 9+ |
100| ECC | 256 | NID_X9_62_prime256v1 | ECC256 | 9+ |
101| ECC | 384 | NID_secp384r1 | ECC384 | 9+ |
102| ECC | 521 | NID_secp521r1 | ECC521 | 9+ |
103| ECC | 160 | NID_brainpoolP160r1 | ECC_BrainPoolP160r1 | 11+ |
104| ECC | 160 | NID_brainpoolP160t1 | ECC_BrainPoolP160t1 | 11+ |
105| ECC | 192 | NID_brainpoolP192r1 | ECC_BrainPoolP192r1 | 11+ |
106| ECC | 192 | NID_brainpoolP192t1 | ECC_BrainPoolP192t1 | 11+ |
107| ECC | 224 | NID_brainpoolP224r1 | ECC_BrainPoolP224r1 | 11+ |
108| ECC | 224 | NID_brainpoolP224t1 | ECC_BrainPoolP224t1 | 11+ |
109| ECC | 256 | NID_brainpoolP256r1 | ECC_BrainPoolP256r1 | 11+ |
110| ECC | 256 | NID_brainpoolP256t1 | ECC_BrainPoolP256t1 | 11+ |
111| ECC | 320 | NID_brainpoolP320r1 | ECC_BrainPoolP320r1 | 11+ |
112| ECC | 320 | NID_brainpoolP320t1 | ECC_BrainPoolP320t1 | 11+ |
113| ECC | 384 | NID_brainpoolP384r1 | ECC_BrainPoolP384r1 | 11+ |
114| ECC | 384 | NID_brainpoolP384t1 | ECC_BrainPoolP384t1 | 11+ |
115| ECC | 512 | NID_brainpoolP512r1 | ECC_BrainPoolP512r1 | 11+ |
116| ECC | 512 | NID_brainpoolP512t1 | ECC_BrainPoolP512t1 | 11+ |
117| ECC | 256 | NID_secp256k1 | ECC_Secp256k1 | 14+ |
118
119> **注意:**
120>
121> 创建的ECC非对称密钥生成器,如果用于随机生成密钥,则生成的ECC密钥的规格与创建密钥生成器时参数中指定的密钥规格一致;如果用于密钥转换,则生成的ECC密钥的规格与密钥转换时参数中指定的密钥数据的密钥规格一致。
122
123### 使用密钥参数生成
124
125从API版本10开始支持,使用密钥参数生成ECC密钥。
126
127Fp域下的ECC密钥参数,包括:
128
129- p:素数,用于确定Fp。
130
131- a, b:确定椭圆曲线的方程。
132
133- g:椭圆曲线的一个基点(base point),可由gx,gy表示。
134
135- n:基点g的阶(order)。
136
137- h:余因子(cofactor)。
138
139- sk:私钥,是一个随机整数,小于n。
140
141- pk:公钥,是椭圆曲线上的一个点, pk = sk \* g。
142
143当创建非对称密钥生成器时,对于指定公/私钥参数生成ECC密钥的支持情况如表所示:
144
145- √:表示需要指定这一列中的具体属性,来构成密钥参数。
146
147|  | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 |
148| -------- | -------- | -------- | -------- | -------- |
149| fieldType | √ | √ | √ | √ |
150| p | √ | √ | √ | √ |
151| a | √ | √ | √ | √ |
152| b | √ | √ | √ | √ |
153| g | √ | √ | √ | √ |
154| n | √ | √ | √ | √ |
155| h | √ | √ | √ | √ |
156| pk | - | √ | - | √ |
157| sk | - | - | √ | √ |
158
159> **说明:**
160> - 当前ECC只支持Fp域,因此fieldType固定为"Fp"。fieldType和p构成了属性field,当前field只支持[ECFieldFp](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#ecfieldfp10)。
161>
162> - g和pk为ECC曲线上的点,属于[Point](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#point10)类型,需要指定具体X,Y坐标。
163
164
165### 使用曲线名生成密钥参数
166
167从API版本11开始支持,使用曲线名来生成ECC公共密钥参数。
168
169
170> **说明:**
171> - 曲线名为要求输入的字符串参数,支持的曲线名请参考[ECC密钥字符串参数表](#使用字符串参数生成-1)中的“曲线名”一列。
172>
173> - 生成的公共密钥参数可以直接随机生成公私钥,也可用于构造公、私以及公私钥对密钥参数。
174
175
176## DSA
177
178DSA(Digital Signature Algorithm),是一种基于模算数和整数有限域离散对数难题的一种公钥密码算法,常用于数字签名和验签,不能用于加解密。
179
180当前支持使用字符串参数和密钥参数两种方式生成DSA密钥。
181
182### 约束与限制
183
184使用同步接口生成DSA2048、DSA3072非对称密钥或者明文长度超过2048会导致耗时增加。
185
186由于系统对主线程有时间限制,耗时较长会导致失败,建议开发者在生成位数较大的密钥时,使用对应的异步接口,或是[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)进行开发。
187
188### 使用字符串参数生成
189
190以字符串参数生成DSA密钥,具体的“字符串参数”由“非对称密钥算法”和“密钥长度”拼接而成,用于在创建非对称密钥生成器时,指定密钥规格。
191
192| 非对称密钥算法 | 密钥长度(bit) | 字符串参数 | API版本 |
193| -------- | -------- | -------- | -------- |
194| DSA | 1024 | DSA1024 | 10+ |
195| DSA | 2048 | DSA2048 | 10+ |
196| DSA | 3072 | DSA3072 | 10+ |
197
198> **注意:**
199>
200> 使用同步接口生成DSA2048、DSA3072非对称密钥或者明文长度超过2048会导致耗时增加。
201>
202> 由于系统对主线程有时间限制,耗时较长会导致失败,建议开发者在生成位数较大的密钥时,使用对应的异步接口,或是[使用多线程并发能力](../../arkts-utils/multi-thread-concurrency-overview.md)进行开发。
203>
204> 创建的DSA非对称密钥生成器,如果用于随机生成密钥,则生成的DSA密钥的规格与创建密钥生成器时参数中指定的密钥规格一致;如果用于密钥转换,则生成的DSA密钥的规格与密钥转换时参数中指定的密钥数据的密钥规格一致。
205
206### 使用密钥参数生成
207
208从API版本10开始支持,使用密钥参数生成DSA密钥。
209
210DSA密钥参数,包括:
211
212- p:一个素模数,比特长度为64的整数倍。
213
214- q:p-1的素因子,长度与p的长度有关。
215
216- g:g = (h ^ ((p - 1) / q)) mod p,h为满足1 < h < p -1的任意整数。
217
218- sk:私钥,为随机生成的整数,满足0 < sk < q。
219
220- pk:公钥,pk = (g ^ sk) mod p。
221
222当创建非对称密钥生成器时,对于指定公/私钥参数生成DSA密钥的支持情况如表所示:
223
224- √:表示需要指定这一列中的具体属性,来构成密钥参数。
225
226- ×:表示这一列中的具体属性对应某种密钥参数,但是当前不支持通过该密钥参数生成密钥。
227
228|  | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 |
229| -------- | -------- | -------- | -------- | -------- |
230| p | √ | √ | × | √ |
231| q | √ | √ | × | √ |
232| g | √ | √ | × | √ |
233| pk | - | √ | - | √ |
234| sk | - | - | × | √ |
235
236> **说明:**
237> - DSA不支持通过指定私钥参数(p, q, g, sk)来生成私钥。
238>
239> - 当使用公共参数(p, q, g)来生成DSA密钥对时,DSA密钥长度至少需要1024位。
240
241
242## SM2
243
244SM2,是一种基于椭圆曲线的公钥密码算法。采用的Fp域上的椭圆曲线。
245
246当前支持使用字符串参数和密钥参数两种方式生成SM2密钥,且支持通过曲线名生成公共密钥参数。
247
248
249### 使用字符串参数生成
250
251当前支持以字符串参数生成SM2密钥,具体的“字符串参数”由“非对称密钥算法”和“密钥长度”使用符号“_”拼接而成,用于在创建非对称密钥生成器时,指定密钥规格。
252
253| 非对称密钥算法 | 密钥长度(bit) | 曲线名 | 字符串参数 | API版本 |
254| -------- | -------- | -------- | -------- | -------- |
255| SM2 | 256 | NID_sm2 | SM2_256 | 10+ |
256
257
258### 使用密钥参数生成
259
260从API版本11开始支持,使用密钥参数生成SM2密钥。
261
262Fp域下的SM2密钥参数,包括:
263
264- p:素数,用于确定Fp。
265
266- a, b:确定椭圆曲线的方程。
267
268- g:椭圆曲线的一个基点(base point),可由gx,gy表示。
269
270- n:基点g的阶(order)。
271
272- h:余因子(cofactor)。
273
274- sk:私钥,是一个随机整数,小于n。
275
276- pk:公钥,是椭圆曲线上的一个点, pk = sk \* g。
277
278当创建非对称密钥生成器时,对于指定公/私钥参数生成SM2密钥的支持情况如表所示:
279
280- √:表示需要指定这一列中的具体属性,来构成密钥参数。
281
282|  | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 |
283| -------- | -------- | -------- | -------- | -------- |
284| fieldType | √ | √ | √ | √ |
285| p | √ | √ | √ | √ |
286| a | √ | √ | √ | √ |
287| b | √ | √ | √ | √ |
288| g | √ | √ | √ | √ |
289| n | √ | √ | √ | √ |
290| h | √ | √ | √ | √ |
291| pk | - | √ | - | √ |
292| sk | - | - | √ | √ |
293
294> **说明:**
295> - 当前SM2只支持Fp域,因此fieldType固定为"Fp"。fieldType和p构成了属性field,当前field只支持[ECFieldFp](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#ecfieldfp10)。
296>
297> - g和pk为SM2曲线上的点,属于[Point](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#point10)类型,需要指定具体X,Y坐标。
298
299
300### 使用曲线名生成密钥参数
301
302从API版本11开始支持,使用曲线名来生成SM2公共密钥参数。
303
304
305> **说明:**
306> - 曲线名为要求输入的字符串参数,支持的曲线名为"NID_sm2"。
307>
308> - 生成的公共密钥参数可以直接随机生成公私钥,也可用于构造公、私以及公私钥对密钥参数。
309
310
311## Ed25519
312
313Ed25519算法是一个基于 EdDSA 算法的数字签名算法,密钥长度为256位,使用 Edwards 曲线来实现,不能用于加解密,一般用于数字签名和验签。
314
315当前支持使用字符串参数和密钥参数两种方式生成Ed25519密钥。
316
317
318### 使用字符串参数生成
319
320以字符串参数生成Ed25519密钥,用于在创建非对称密钥生成器时,指定密钥规格。
321
322| 非对称密钥算法 | 字符串参数 | API版本 |
323| -------- | -------- | -------- |
324| Ed25519 | Ed25519 | 11+ |
325
326
327### 使用密钥参数生成
328
329从API版本11开始支持,使用密钥参数生成Ed25519密钥。
330
331Ed22519密钥参数,包括:
332
333- sk:私钥,一个 32 字节的随机值。
334
335- pk:公钥,一个 32 字节的值,从私钥派生而来。
336
337当创建非对称密钥生成器时,对于指定公/私钥参数生成Ed25519密钥的支持情况如表所示:
338
339- √:表示需要指定这一列中的具体属性,来构成密钥参数。
340
341|  | 公钥参数 | 私钥参数 | 公私钥对参数 |
342| -------- | -------- | -------- | -------- |
343| pk | √ | - | √ |
344| sk | - | √ | √ |
345
346> **说明:**
347>
348> Ed25519密钥参数没有公共参数,不支持通过公共参数生成密钥。
349
350
351## X25519
352
353X25519算法是一种 Diffie-Hellman 密钥交换算法,用于密钥协商。
354
355当前支持使用字符串参数和密钥参数两种方式生成X25519密钥。
356
357
358### 使用字符串参数生成
359
360以字符串参数生成X25519密钥,用于在创建非对称密钥生成器时,指定密钥规格。
361
362| 非对称密钥算法 | 字符串参数 | API版本 |
363| -------- | -------- | -------- |
364| X25519 | X25519 | 11+ |
365
366
367### 使用密钥参数生成
368
369从API版本11开始支持,使用密钥参数生成X25519密钥。
370
371X22519密钥参数,包括:
372
373- sk:私钥,一个 32 字节的随机值。
374
375- pk:公钥,一个 32 字节的值,从私钥派生而来。
376
377当创建非对称密钥生成器时,对于指定公/私钥参数生成X25519密钥的支持情况如表所示:
378
379- √:表示需要指定这一列中的具体属性,来构成密钥参数。
380
381|  | 公钥参数 | 私钥参数 | 公私钥对参数 |
382| -------- | -------- | -------- | -------- |
383| pk | √ | - | √ |
384| sk | - | √ | √ |
385
386> **说明:**
387>
388> X25519没有公共密钥参数,不支持通过公共参数生成密钥。
389
390
391## DH
392
393DH(Diffie–Hellman key exchange),是一种密钥协商算法,只涉及公钥的交换,它可以提供前向安全性,即使在通信渠道被监听的情况下,也不会暴露双方的私钥。
394
395当前支持使用字符串参数和密钥参数两种方式生成DH密钥,且支持根据素数长度和私钥长度生成公共密钥参数。
396
397
398### 使用字符串参数生成
399
400以字符串参数生成DH密钥,具体的“字符串参数”由“非对称密钥算法”和“知名安全素数群参数”使用符号“_”拼接而成,用于在创建非对称密钥生成器时,指定密钥规格。
401
402| 非对称密钥算法 | 知名安全素数群参数 | 密钥长度(bit) | 字符串参数 | API版本 |
403| -------- | -------- | -------- | -------- | -------- |
404| DH | modp1536 | 1536 | DH_modp1536 | 11+ |
405| DH | modp2048 | 2048 | DH_modp2048 | 11+ |
406| DH | modp3072 | 3072 | DH_modp3072 | 11+ |
407| DH | modp4096 | 4096 | DH_modp4096 | 11+ |
408| DH | modp6144 | 6144 | DH_modp6144 | 11+ |
409| DH | modp8192 | 8192 | DH_modp8192 | 11+ |
410| DH | ffdhe2048 | 2048 | DH_ffdhe2048 | 11+ |
411| DH | ffdhe3072 | 3072 | DH_ffdhe3072 | 11+ |
412| DH | ffdhe4096 | 4096 | DH_ffdhe4096 | 11+ |
413| DH | ffdhe6144 | 6144 | DH_ffdhe6144 | 11+ |
414| DH | ffdhe8192 | 8192 | DH_ffdhe8192 | 11+ |
415
416> **注意:**
417>
418> 创建的DH非对称密钥生成器,如果用于随机生成密钥,则生成的DH密钥的规格与创建密钥生成器时参数中指定的密钥规格一致;如果用于密钥转换,则生成的DH密钥的规格与密钥转换时参数中指定的密钥数据的密钥规格一致。
419
420### 使用密钥参数生成
421
422从API版本11开始支持,使用密钥参数生成DH密钥。
423
424DH密钥参数,包括:
425
426- p:一个足够大的素数,用作有限域的模数。它被所有通信双方共享。
427
428- g:g是DH算法的生成元,是素数p的原根。它被所有通信双方共享。
429
430- l:length,表示私钥长度,以bit为单位。当l为0时,代表不指定私钥长度。
431
432- sk:私钥,一个随机生成的私钥值。
433
434- pk:公钥,通过使用公共参数(p 和 g)和私钥进行计算得到。
435
436当创建非对称密钥生成器时,对于指定公/私钥参数生成DH密钥的支持情况如表所示:
437
438- √:表示需要指定这一列中的具体属性,来构成密钥参数。
439
440|  | 公共参数 | 公钥参数 | 私钥参数 | 公私钥对参数 |
441| -------- | -------- | -------- | -------- | -------- |
442| p | √ | √ | √ | √ |
443| g | √ | √ | √ | √ |
444| l | √ | √ | √ | √ |
445| pk | - | √ | - | √ |
446| sk | - | - | √ | √ |
447
448
449### 使用素数长度和私钥长度生成公共密钥参数
450
451从API版本11开始支持,使用素数长度和私钥长度生成DH公共密钥参数。
452
453如果素数长度与安全素数组素数长度一致,则选用对应的知名安全素数群,对应关系如表所示:
454
455| 素数长度(bit) | 知名安全素数群 |
456| -------- | -------- |
457| 2048 | ffdhe2048 |
458| 3072 | ffdhe3072 |
459| 4096 | ffdhe4096 |
460| 6144 | ffdhe6144 |
461| 8192 | ffdhe8192 |
462
463- 素数p的比特长度必须大于等于512,小于等于10000。
464
465- 私钥长度l为可选参数,默认为0,l值的设置范围需大于2\*(96+(素数P位数-1)/1024\*16)。
466
467- 生成的公共密钥参数可以直接随机生成公私钥,也可用于构造公、私以及公私钥对密钥参数。
468
469- 生成非知名群的密钥参数较为耗时,建议优先选用知名安全素数群。
470