1# Asymmetric Key Generation and Conversion Specifications
2
3
4This topic describes the supported algorithms and specifications for asymmetric key generation and conversion. The specifications for key generation can be specified via either of the following:
5
6
7- String parameter: presents the specifications of the key to generate in the form of a string.
8
9- Key parameter: constructs the detailed cryptographic information of the key to generate in an object.
10
11
12For details, see the specifications of each algorithm.
13
14## RSA
15
16Rivest-Shamir-Adleman (RSA) is an asymmetric encryption algorithm widely used for secure data transmission. An RSA key can be generated based on a string parameter or key parameters.
17
18### String Parameter
19
20When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter. The string parameter consists of the RSA key type and prime count with a vertical bar (|) in between.
21
22> **NOTE**
23> When an RSA asymmetric key is generated, the default number of primes is 2 and the **PRIMES_2** parameter can be omitted.
24
25| RSA Key Type| Prime Count| String Parameter| API Version|
26| -------- | -------- | -------- | -------- |
27| RSA512 | 2 | RSA512\|PRIMES_2 | 9+ |
28| RSA768 | 2 | RSA768\|PRIMES_2 | 9+ |
29| RSA1024 | 2 | RSA1024\|PRIMES_2 | 9+ |
30| RSA1024 | 3 | RSA1024\|PRIMES_3 | 9+ |
31| RSA2048 | 2 | RSA2048\|PRIMES_2 | 9+ |
32| RSA2048 | 3 | RSA2048\|PRIMES_3 | 9+ |
33| RSA3072 | 2 | RSA3072\|PRIMES_2 | 9+ |
34| RSA3072 | 3 | RSA3072\|PRIMES_3 | 9+ |
35| RSA4096 | 2 | RSA4096\|PRIMES_2 | 9+ |
36| RSA4096 | 3 | RSA4096\|PRIMES_3 | 9+ |
37| RSA4096 | 4 | RSA4096\|PRIMES_4 | 9+ |
38| RSA8192 | 2 | RSA8192\|PRIMES_2 | 9+ |
39| RSA8192 | 3 | RSA8192\|PRIMES_3 | 9+ |
40| RSA8192 | 4 | RSA8192\|PRIMES_4 | 9+ |
41| RSA8192 | 5 | RSA8192\|PRIMES_5 | 9+ |
42
43
44> **NOTE**
45>
46> It takes time to generate an RSA2048, RSA3072, RSA4096, or RSA8192 asymmetric key. Since the execution of the main thread has a time limit, the operation may fail if you use a synchronous API. You are advised to use asynchronous APIs or use [multithread concurrent tasks](../../arkts-utils/multi-thread-concurrency-overview.md) to generate a key of a large size.
47>
48> If the created RSA asymmetric key generator is used to randomly generate keys, the specifications of the RSA keys generated are the same as the key specifications set when the key generator is created. If it is used to convert keys, the specifications of the RSA keys generated are the same as the key specifications set in key conversion parameters.
49
50### Key Parameter
51
52Since API version 10, key parameters can be used to generate an RSA key.
53
54The RSA key includes the following integers:
55
56- **n**: modulus for both the private and public keys.
57
58- **sk**: private exponent, which is often written as **d** in the formula.
59
60- **pk**: public exponent, which is often written as **e** in the formula.
61
62The following table illustrates the composition of the RSA key parameters.
63
64- √ indicates the property used to construct a key parameter.
65
66- x indicates that the property that cannot be used to construct a key parameter.
67
68|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
69| -------- | -------- | -------- | -------- | -------- |
70| n | × | √ | × | √ |
71| pk | - | √ | - | √ |
72| sk | - | - | × | √ |
73
74According to the preceding table:
75
76- The RSA key cannot be generated based on the common parameter (**n**).
77
78- The RSA private key cannot be generated based on the private key parameter, which consists of **n** and **sk**.
79
80
81## ECC
82
83Elliptic-curve cryptography (ECC) is a public-key encryption algorithm based on elliptic curve mathematics.
84
85The ECC algorithm can be regarded as an operation of numbers defined in a special set. Currently, the Crypto framework supports only elliptic curves in the **Fp** field for ECC keys, where **p** indicates a prime. The **Fp** field is also called prime field.
86
87An ECC key can be generated based on a string parameter or key parameters, and the common parameter can be generated based on the curve name.
88
89
90### String Parameter
91
92When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter. The string parameter consists of the asymmetric key algorithm and key length.
93
94| Asymmetric Key Algorithm| Key Length (Bit)| Curve Name| String Parameter| API Version|
95| -------- | -------- | -------- | -------- | -------- |
96| ECC | 224 | NID_secp224r1 | ECC224 | 9+ |
97| ECC | 256 | NID_X9_62_prime256v1 | ECC256 | 9+ |
98| ECC | 384 | NID_secp384r1 | ECC384 | 9+ |
99| ECC | 521 | NID_secp521r1 | ECC521 | 9+ |
100| ECC | 160 | NID_brainpoolP160r1 | ECC_BrainPoolP160r1 | 11+ |
101| ECC | 160 | NID_brainpoolP160t1 | ECC_BrainPoolP160t1 | 11+ |
102| ECC | 192 | NID_brainpoolP192r1 | ECC_BrainPoolP192r1 | 11+ |
103| ECC | 192 | NID_brainpoolP192t1 | ECC_BrainPoolP192t1 | 11+ |
104| ECC | 224 | NID_brainpoolP224r1 | ECC_BrainPoolP224r1 | 11+ |
105| ECC | 224 | NID_brainpoolP224t1 | ECC_BrainPoolP224t1 | 11+ |
106| ECC | 256 | NID_brainpoolP256r1 | ECC_BrainPoolP256r1 | 11+ |
107| ECC | 256 | NID_brainpoolP256t1 | ECC_BrainPoolP256t1 | 11+ |
108| ECC | 320 | NID_brainpoolP320r1 | ECC_BrainPoolP320r1 | 11+ |
109| ECC | 320 | NID_brainpoolP320t1 | ECC_BrainPoolP320t1 | 11+ |
110| ECC | 384 | NID_brainpoolP384r1 | ECC_BrainPoolP384r1 | 11+ |
111| ECC | 384 | NID_brainpoolP384t1 | ECC_BrainPoolP384t1 | 11+ |
112| ECC | 512 | NID_brainpoolP512r1 | ECC_BrainPoolP512r1 | 11+ |
113| ECC | 512 | NID_brainpoolP512t1 | ECC_BrainPoolP512t1 | 11+ |
114
115> **NOTE**
116>
117> If the created ECC asymmetric key generator is used to randomly generate keys, the specifications of the ECC keys generated are the same as the key specifications set when the key generator is created. If it is used to convert keys, the specifications of the ECC keys generated are the same as the key specifications set in key conversion parameters.
118
119### Key Parameter
120
121Since API version 10, key parameters can be used to generate an ECC key.
122
123The ECC key in the **Fp** field includes the following properties:
124
125- **p**: prime used to determine **Fp**.
126
127- **a**, **b**: determine the elliptic curve equation.
128
129- **g**: base point of the elliptic curve, which can be represented as **gx** or **gy**.
130
131- **n**: order of the base point **g**.
132
133- **h**: cofactor.
134
135- **sk**: private key, which is a random integer less than **n**.
136
137- **pk**: public key, which is a point on the elliptic curve. **pk** = **sk** x **g**.
138
139The following table illustrates the composition of the ECC key parameters.
140
141- √ indicates the property used to construct a key parameter.
142
143|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
144| -------- | -------- | -------- | -------- | -------- |
145| fieldType | √ | √ | √ | √ |
146| p | √ | √ | √ | √ |
147| a | √ | √ | √ | √ |
148| b | √ | √ | √ | √ |
149| g | √ | √ | √ | √ |
150| n | √ | √ | √ | √ |
151| h | √ | √ | √ | √ |
152| pk | - | √ | - | √ |
153| sk | - | - | √ | √ |
154
155> **NOTE**
156> - Currently, only the **Fp** field is supported. Therefore, **fieldType** has a fixed value of **Fp**. **fieldType** and **p** constitute the property **field**, which supports only [ECFieldFp](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#ecfieldfp10) currently.
157> 
158> - **g** and **pk** are points of the [Point](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#point10) type on the ECC curve. You need to specify their X and Y coordinates.
159
160
161### Curve Name
162
163Since API version 11, the ECC common parameter can be generated based on a curve name.
164
165
166> **NOTE**
167> - The curve name is a string parameter. For details about the supported curve names, see the **Curve Name** column in [ECC String Parameter](#string-parameter-1).
168> 
169> - The generated common parameter can be used to randomly generate public and private keys, or used to construct the public key parameter, private key parameter, or key pair parameter.
170
171
172## DSA
173
174Digital Signature Algorithm (DSA) is a public-key algorithm based on the modular exponentiation and discrete logarithm problem. It is used for digital signatures and signature verification, but not for encryption and decryption.
175
176A DSA key can be generated based on a string parameter or key parameters.
177
178### Constraints
179
180It takes time to generate a DSA2048 or DSA3072 asymmetric key pair or when the plaintext length exceeds 2048 bits. Since the execution of the main thread has a time limit, the operation may fail if you use a synchronous API. You are advised to use asynchronous APIs or use [multithread concurrent tasks](../../arkts-utils/multi-thread-concurrency-overview.md) to generate a key of a large size.
181
182### String Parameter
183
184When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter. The string parameter consists of the asymmetric key algorithm and key length.
185
186| Asymmetric Key Algorithm| Key Length (Bit)| String Parameter| API Version|
187| -------- | -------- | -------- | -------- |
188| DSA | 1024 | DSA1024 | 10+ |
189| DSA | 2048 | DSA2048 | 10+ |
190| DSA | 3072 | DSA3072 | 10+ |
191
192> **NOTE**
193>
194> It takes time to generate a DSA2048 or DSA3072 asymmetric key pair or when the plaintext length exceeds 2048 bits. Since the execution of the main thread has a time limit, the operation may fail if you use a synchronous API. You are advised to use asynchronous APIs or use [multithread concurrent tasks](../../arkts-utils/multi-thread-concurrency-overview.md) to generate a key of a large size.
195>
196> If the created DSA asymmetric key generator is used to randomly generate keys, the specifications of the DSA keys generated are the same as the key specifications set when the key generator is created. If it is used to convert keys, the specifications of the DSA keys generated are the same as the key specifications set in key conversion parameters.
197
198### Key Parameter
199
200Since API version 10, key parameters can be used to generate a DSA key.
201
202The DSA key includes the following properties:
203
204- **p**: prime modulus, whose length is an integer multiple of 64.
205
206- **q**: prime factor of **p** – 1. The length varies depending on the length of **p**.
207
208- **g**: g = (h ^ ((p – 1)/q)) mod p, where **h** is an integer greater than 1 and less than **p** minus 1.
209
210- **sk**: private key, which is a randomly generated integer greater than 0 and less than **q**.
211
212- **pk**: public key. pk = (g ^ sk) mod p
213
214The following table illustrates the composition of the DSA key parameters.
215
216- √ indicates the property used to construct a key parameter.
217
218- x indicates that the property that cannot be used to construct a key parameter.
219
220|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
221| -------- | -------- | -------- | -------- | -------- |
222| p | √ | √ | × | √ |
223| q | √ | √ | × | √ |
224| g | √ | √ | × | √ |
225| pk | - | √ | - | √ |
226| sk | - | - | × | √ |
227
228> **NOTE**
229> - The DSA private key cannot be generated based on the private key parameter, which consists of **p**, **q**, **g**, and **sk**.
230> 
231> - When the common parameter (**p**, **q**, **g**) is used to generate a DSA key pair, the DSA key length must be at least 1024 bits.
232
233
234## SM2
235
236ShangMi 2 (SM2) is a public key cryptographic algorithm based on ECC. The SM2 algorithm uses the elliptic curves over the **Fp** field.
237
238An SM2 key can be generated based on a string parameter or key parameters, and the common parameter can be generated based on the curve name.
239
240
241### String Parameter
242
243When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter. The string parameter consists of the asymmetric key algorithm and key length with an underscore (_) in between.
244
245| Asymmetric Key Algorithm| Key Length (Bit)| Curve Name| String Parameter| API Version|
246| -------- | -------- | -------- | -------- | -------- |
247| SM2 | 256 | NID_sm2 | SM2_256 | 10+ |
248
249
250### Key Parameter
251
252Since API version 11, key parameters can be used to generate an SM2 key.
253
254The SM2 key in the **Fp** field includes the following properties:
255
256- **p**: prime used to determine **Fp**.
257
258- **a**, **b**: determine the elliptic curve equation.
259
260- **g**: base point of the elliptic curve, which can be represented as **gx** or **gy**.
261
262- **n**: order of the base point **g**.
263
264- **h**: cofactor.
265
266- **sk**: private key, which is a random integer less than **n**.
267
268- **pk**: public key, which is a point on the elliptic curve. **pk** = **sk** x **g**.
269
270The following table illustrates the composition of the SM2 key parameters.
271
272- √ indicates the property used to construct a key parameter.
273
274|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
275| -------- | -------- | -------- | -------- | -------- |
276| fieldType | √ | √ | √ | √ |
277| p | √ | √ | √ | √ |
278| a | √ | √ | √ | √ |
279| b | √ | √ | √ | √ |
280| g | √ | √ | √ | √ |
281| n | √ | √ | √ | √ |
282| h | √ | √ | √ | √ |
283| pk | - | √ | - | √ |
284| sk | - | - | √ | √ |
285
286> **NOTE**
287> - Currently, only the **Fp** field is supported. Therefore, **fieldType** has a fixed value of **Fp**. **fieldType** and **p** constitute **field**, which supports only [ECFieldFp](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#ecfieldfp10) currently.
288> 
289> - **g** and **pk** are points of the [Point](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#point10) type on the SM2 curve. You need to specify their X and Y coordinates.
290
291
292### Curve Name
293
294Since API version 11, the SM2 common parameter can be generated based on a curve name.
295
296
297> **NOTE**
298> - The curve name is a string parameter. The supported curve name is **NID_sm2**.
299> 
300> - The generated common parameter can be used to randomly generate public and private keys, or used to construct the public key parameter, private key parameter, or key pair parameter.
301
302
303## Ed25519
304
305Ed25519 is a digital signature algorithm based on EdDSA. The key is of 256 bits and is implemented using Edwards curves. Ed25519 is used for signing and signature verification, and cannot be used for encryption or decryption.
306
307An Ed25519 key can be generated based on a string parameter or key parameters.
308
309
310### String Parameter
311
312When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter.
313
314| Asymmetric Key Algorithm| String Parameter| API Version|
315| -------- | -------- | -------- |
316| Ed25519 | Ed25519 | 11+ |
317
318
319### Key Parameter
320
321Since API version 11, key parameters can be used to generate an Ed25519 key.
322
323The Ed25519 key includes the following properties:
324
325- **sk**: private key, which is a 32-byte random value.
326
327- **pk**: public key, a 32-byte value derived from the private key.
328
329The following table illustrates the composition of the Ed25519 key parameters.
330
331- √ indicates the property used to construct a key parameter.
332
333|  | Public Key Parameter| Private Key Parameter| Key Pair Parameter|
334| -------- | -------- | -------- | -------- |
335| pk | √ | - | √ |
336| sk | - | √ | √ |
337
338> **NOTE**
339> Ed25519 does not have the common parameter.
340
341
342## X25519
343
344X25519 is a Diffie-Hellman key exchange algorithm used for key agreement.
345
346An X25519 key can be generated based on a string parameter or key parameters.
347
348
349### String Parameter
350
351When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter.
352
353| Asymmetric Key Algorithm| String Parameter| API Version|
354| -------- | -------- | -------- |
355| X25519 | X25519 | 11+ |
356
357
358### Key Parameter
359
360Since API version 11, key parameters can be used to generate an X25519 key.
361
362The X22519 key includes the following properties:
363
364- **sk**: private key, which is a 32-byte random value.
365
366- **pk**: public key, a 32-byte value derived from the private key.
367
368The following table illustrates the composition of the X25519 key parameters.
369
370- √ indicates the property used to construct a key parameter.
371
372|  | Public Key Parameter| Private Key Parameter| Key Pair Parameter|
373| -------- | -------- | -------- | -------- |
374| pk | √ | - | √ |
375| sk | - | √ | √ |
376
377> **NOTE**
378> X25519 does not have the common parameter.
379
380
381## DH
382
383Diffie–Hellman key exchange (DH) is a key agreement algorithm used to exchange the public key only. It provides forward secrecy, which protects the session keys against compromises even if the communication channel is intercepted.
384
385A DH key can be generated based on a string parameter or key parameters, and the common parameter can be generated based on the prime length and private key length.
386
387
388### String Parameter
389
390When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter. The string parameter consists of the asymmetric key algorithm and named DH group with an underscore (_) in between.
391
392| Asymmetric Key Algorithm| Named DH Group| Key Length (Bit)| String Parameter| API Version|
393| -------- | -------- | -------- | -------- | -------- |
394| DH | modp1536 | 1536 | DH_modp1536 | 11+ |
395| DH | modp2048 | 2048 | DH_modp2048 | 11+ |
396| DH | modp3072 | 3072 | DH_modp3072 | 11+ |
397| DH | modp4096 | 4096 | DH_modp4096 | 11+ |
398| DH | modp6144 | 6144 | DH_modp6144 | 11+ |
399| DH | modp8192 | 8192 | DH_modp8192 | 11+ |
400| DH | ffdhe2048 | 2048 | DH_ffdhe2048 | 11+ |
401| DH | ffdhe3072 | 3072 | DH_ffdhe3072 | 11+ |
402| DH | ffdhe4096 | 4096 | DH_ffdhe4096 | 11+ |
403| DH | ffdhe6144 | 6144 | DH_ffdhe6144 | 11+ |
404| DH | ffdhe8192 | 8192 | DH_ffdhe8192 | 11+ |
405
406> **NOTE**
407>
408> If the created DH asymmetric key generator is used to randomly generate keys, the specifications of the DH keys generated are the same as the key specifications set when the key generator is created. If it is used to convert keys, the specifications of the DH keys generated are the same as the key specifications set in key conversion parameters.
409
410### Key Parameter
411
412Since API version 11, key parameters can be used to generate a DH key.
413
414The DH key includes the following properties:
415
416- **p**: a large prime used as a modulus of a finite field. It is shared by all communicating parties.
417
418- **g**: a primitive root modulo **p**. It is shared by all communicating parties.
419
420- **l**: length of the private key, in bits. The value **0** means the length of the private key is not specified.
421
422- **sk**: private key, which is a randomly generated value.
423
424- **pk**: public key, which is calculated using the common parameter (**p** and **g**) and the private key.
425
426The following table illustrates the composition of the DH key parameters.
427
428- √ indicates the property used to construct a key parameter.
429
430|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
431| -------- | -------- | -------- | -------- | -------- |
432| p | √ | √ | √ | √ |
433| g | √ | √ | √ | √ |
434| l | √ | √ | √ | √ |
435| pk | - | √ | - | √ |
436| sk | - | - | √ | √ |
437
438
439### Common Parameter Generated Based on the Prime Length and Private Key Length
440
441Since API version 11, the DH common parameter can be generated based on the prime length and private key length.
442
443If the prime length is the same as that of the DH group, the DH group is used. The following table lists the mappings between the prime lengths and DH groups.
444
445| Prime Length (Bit)| Named DH Group|
446| -------- | -------- |
447| 2048 | ffdhe2048 |
448| 3072 | ffdhe3072 |
449| 4096 | ffdhe4096 |
450| 6144 | ffdhe6144 |
451| 8192 | ffdhe8192 |
452
453- The number of bits for **p** must be greater than or equal to 512 and less than or equal to 10000.
454
455- The parameter **l** (private key length) is optional. The default value is **0**. The value of **l** must meet the following requirements:<br>**l** > 2\*(96 + (Length of p – 1)/1024 x 16)
456
457- The generated common parameter can be used to randomly generate public and private keys, or used to construct the public key parameter, private key parameter, or key pair parameter.
458
459- Named DH groups are recommended because generating a key parameter with an unnamed DH group is time-consuming.
460