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>
24> When an RSA asymmetric key is generated, the default number of primes is 2 and the **PRIMES_2** parameter can be omitted.
25
26| RSA Key Type| Prime Count| String Parameter| API Version|
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> **NOTE**
46>
47> 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.
48>
49> 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.
50
51### Key Parameter
52
53Since API version 10, key parameters can be used to generate an RSA key.
54
55The RSA key includes the following integers:
56
57- **n**: modulus for both the private and public keys.
58
59- **sk**: private exponent, which is often written as **d** in the formula.
60
61- **pk**: public exponent, which is often written as **e** in the formula.
62
63The following table illustrates the composition of the RSA key parameters.
64
65- √ indicates the property used to construct a key parameter.
66
67- x indicates that the property that cannot be used to construct a key parameter.
68
69|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
70| -------- | -------- | -------- | -------- | -------- |
71| n | × | √ | × | √ |
72| pk | - | √ | - | √ |
73| sk | - | - | × | √ |
74
75According to the preceding table:
76
77- The RSA key cannot be generated based on the common parameter (**n**).
78
79- The RSA private key cannot be generated based on the private key parameter, which consists of **n** and **sk**.
80
81
82## ECC
83
84Elliptic-curve cryptography (ECC) is a public-key encryption algorithm based on elliptic curve mathematics.
85
86The 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.
87
88An 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.
89
90
91### String Parameter
92
93When 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.
94
95| Asymmetric Key Algorithm| Key Length (Bit)| Curve Name| String Parameter| API Version|
96| -------- | -------- | -------- | -------- | -------- |
97| ECC | 224 | NID_secp224r1 | ECC224 | 9+ |
98| ECC | 256 | NID_X9_62_prime256v1 | ECC256 | 9+ |
99| ECC | 384 | NID_secp384r1 | ECC384 | 9+ |
100| ECC | 521 | NID_secp521r1 | ECC521 | 9+ |
101| ECC | 160 | NID_brainpoolP160r1 | ECC_BrainPoolP160r1 | 11+ |
102| ECC | 160 | NID_brainpoolP160t1 | ECC_BrainPoolP160t1 | 11+ |
103| ECC | 192 | NID_brainpoolP192r1 | ECC_BrainPoolP192r1 | 11+ |
104| ECC | 192 | NID_brainpoolP192t1 | ECC_BrainPoolP192t1 | 11+ |
105| ECC | 224 | NID_brainpoolP224r1 | ECC_BrainPoolP224r1 | 11+ |
106| ECC | 224 | NID_brainpoolP224t1 | ECC_BrainPoolP224t1 | 11+ |
107| ECC | 256 | NID_brainpoolP256r1 | ECC_BrainPoolP256r1 | 11+ |
108| ECC | 256 | NID_brainpoolP256t1 | ECC_BrainPoolP256t1 | 11+ |
109| ECC | 320 | NID_brainpoolP320r1 | ECC_BrainPoolP320r1 | 11+ |
110| ECC | 320 | NID_brainpoolP320t1 | ECC_BrainPoolP320t1 | 11+ |
111| ECC | 384 | NID_brainpoolP384r1 | ECC_BrainPoolP384r1 | 11+ |
112| ECC | 384 | NID_brainpoolP384t1 | ECC_BrainPoolP384t1 | 11+ |
113| ECC | 512 | NID_brainpoolP512r1 | ECC_BrainPoolP512r1 | 11+ |
114| ECC | 512 | NID_brainpoolP512t1 | ECC_BrainPoolP512t1 | 11+ |
115| ECC | 256 | NID_secp256k1 | ECC_Secp256k1 | 14+ |
116
117> **NOTE**
118>
119> 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.
120
121### Key Parameter
122
123Since API version 10, key parameters can be used to generate an ECC key.
124
125The ECC key in the **Fp** field includes the following properties:
126
127- **p**: prime used to determine **Fp**.
128
129- **a**, **b**: determine the elliptic curve equation.
130
131- **g**: base point of the elliptic curve, which can be represented as **gx** or **gy**.
132
133- **n**: order of the base point **g**.
134
135- **h**: cofactor.
136
137- **sk**: private key, which is a random integer less than **n**.
138
139- **pk**: public key, which is a point on the elliptic curve. **pk** = **sk** x **g**.
140
141The following table illustrates the composition of the ECC key parameters.
142
143- √ indicates the property used to construct a key parameter.
144
145|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
146| -------- | -------- | -------- | -------- | -------- |
147| fieldType | √ | √ | √ | √ |
148| p | √ | √ | √ | √ |
149| a | √ | √ | √ | √ |
150| b | √ | √ | √ | √ |
151| g | √ | √ | √ | √ |
152| n | √ | √ | √ | √ |
153| h | √ | √ | √ | √ |
154| pk | - | √ | - | √ |
155| sk | - | - | √ | √ |
156
157> **NOTE**
158> - 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.
159>
160> - **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.
161
162
163### Curve Name
164
165Since API version 11, the ECC common parameter can be generated based on a curve name.
166
167
168> **NOTE**
169> - 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).
170>
171> - 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.
172
173
174## DSA
175
176Digital 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.
177
178A DSA key can be generated based on a string parameter or key parameters.
179
180### Constraints
181
182It 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.
183
184### String Parameter
185
186When 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.
187
188| Asymmetric Key Algorithm| Key Length (Bit)| String Parameter| API Version|
189| -------- | -------- | -------- | -------- |
190| DSA | 1024 | DSA1024 | 10+ |
191| DSA | 2048 | DSA2048 | 10+ |
192| DSA | 3072 | DSA3072 | 10+ |
193
194> **NOTE**
195>
196> 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.
197>
198> 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.
199
200### Key Parameter
201
202Since API version 10, key parameters can be used to generate a DSA key.
203
204The DSA key includes the following properties:
205
206- **p**: prime modulus, whose length is an integer multiple of 64.
207
208- **q**: prime factor of **p** – 1. The length varies depending on the length of **p**.
209
210- **g**: g = (h ^ ((p – 1)/q)) mod p, where **h** is an integer greater than 1 and less than **p** minus 1.
211
212- **sk**: private key, which is a randomly generated integer greater than 0 and less than **q**.
213
214- **pk**: public key. pk = (g ^ sk) mod p
215
216The following table illustrates the composition of the DSA key parameters.
217
218- √ indicates the property used to construct a key parameter.
219
220- x indicates that the property that cannot be used to construct a key parameter.
221
222|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
223| -------- | -------- | -------- | -------- | -------- |
224| p | √ | √ | × | √ |
225| q | √ | √ | × | √ |
226| g | √ | √ | × | √ |
227| pk | - | √ | - | √ |
228| sk | - | - | × | √ |
229
230> **NOTE**
231> - The DSA private key cannot be generated based on the private key parameter, which consists of **p**, **q**, **g**, and **sk**.
232>
233> - 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.
234
235
236## SM2
237
238ShangMi 2 (SM2) is a public key cryptographic algorithm based on ECC. The SM2 algorithm uses the elliptic curves over the **Fp** field.
239
240An 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.
241
242
243### String Parameter
244
245When 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.
246
247| Asymmetric Key Algorithm| Key Length (Bit)| Curve Name| String Parameter| API Version|
248| -------- | -------- | -------- | -------- | -------- |
249| SM2 | 256 | NID_sm2 | SM2_256 | 10+ |
250
251
252### Key Parameter
253
254Since API version 11, key parameters can be used to generate an SM2 key.
255
256The SM2 key in the **Fp** field includes the following properties:
257
258- **p**: prime used to determine **Fp**.
259
260- **a**, **b**: determine the elliptic curve equation.
261
262- **g**: base point of the elliptic curve, which can be represented as **gx** or **gy**.
263
264- **n**: order of the base point **g**.
265
266- **h**: cofactor.
267
268- **sk**: private key, which is a random integer less than **n**.
269
270- **pk**: public key, which is a point on the elliptic curve. **pk** = **sk** x **g**.
271
272The following table illustrates the composition of the SM2 key parameters.
273
274- √ indicates the property used to construct a key parameter.
275
276|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
277| -------- | -------- | -------- | -------- | -------- |
278| fieldType | √ | √ | √ | √ |
279| p | √ | √ | √ | √ |
280| a | √ | √ | √ | √ |
281| b | √ | √ | √ | √ |
282| g | √ | √ | √ | √ |
283| n | √ | √ | √ | √ |
284| h | √ | √ | √ | √ |
285| pk | - | √ | - | √ |
286| sk | - | - | √ | √ |
287
288> **NOTE**
289> - 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.
290>
291> - **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.
292
293
294### Curve Name
295
296Since API version 11, the SM2 common parameter can be generated based on a curve name.
297
298
299> **NOTE**
300> - The curve name is a string parameter. The supported curve name is **NID_sm2**.
301>
302> - 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.
303
304
305## Ed25519
306
307Ed25519 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.
308
309An Ed25519 key can be generated based on a string parameter or key parameters.
310
311
312### String Parameter
313
314When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter.
315
316| Asymmetric Key Algorithm| String Parameter| API Version|
317| -------- | -------- | -------- |
318| Ed25519 | Ed25519 | 11+ |
319
320
321### Key Parameter
322
323Since API version 11, key parameters can be used to generate an Ed25519 key.
324
325The Ed25519 key includes the following properties:
326
327- **sk**: private key, which is a 32-byte random value.
328
329- **pk**: public key, a 32-byte value derived from the private key.
330
331The following table illustrates the composition of the Ed25519 key parameters.
332
333- √ indicates the property used to construct a key parameter.
334
335|  | Public Key Parameter| Private Key Parameter| Key Pair Parameter|
336| -------- | -------- | -------- | -------- |
337| pk | √ | - | √ |
338| sk | - | √ | √ |
339
340> **NOTE**
341>
342> Ed25519 does not have the common parameter.
343
344
345## X25519
346
347X25519 is a Diffie-Hellman key exchange algorithm used for key agreement.
348
349An X25519 key can be generated based on a string parameter or key parameters.
350
351
352### String Parameter
353
354When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter.
355
356| Asymmetric Key Algorithm| String Parameter| API Version|
357| -------- | -------- | -------- |
358| X25519 | X25519 | 11+ |
359
360
361### Key Parameter
362
363Since API version 11, key parameters can be used to generate an X25519 key.
364
365The X22519 key includes the following properties:
366
367- **sk**: private key, which is a 32-byte random value.
368
369- **pk**: public key, a 32-byte value derived from the private key.
370
371The following table illustrates the composition of the X25519 key parameters.
372
373- √ indicates the property used to construct a key parameter.
374
375|  | Public Key Parameter| Private Key Parameter| Key Pair Parameter|
376| -------- | -------- | -------- | -------- |
377| pk | √ | - | √ |
378| sk | - | √ | √ |
379
380> **NOTE**
381>
382> X25519 does not have the common parameter.
383
384
385## DH
386
387Diffie–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.
388
389A 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.
390
391
392### String Parameter
393
394When 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.
395
396| Asymmetric Key Algorithm| Named DH Group| Key Length (Bit)| String Parameter| API Version|
397| -------- | -------- | -------- | -------- | -------- |
398| DH | modp1536 | 1536 | DH_modp1536 | 11+ |
399| DH | modp2048 | 2048 | DH_modp2048 | 11+ |
400| DH | modp3072 | 3072 | DH_modp3072 | 11+ |
401| DH | modp4096 | 4096 | DH_modp4096 | 11+ |
402| DH | modp6144 | 6144 | DH_modp6144 | 11+ |
403| DH | modp8192 | 8192 | DH_modp8192 | 11+ |
404| DH | ffdhe2048 | 2048 | DH_ffdhe2048 | 11+ |
405| DH | ffdhe3072 | 3072 | DH_ffdhe3072 | 11+ |
406| DH | ffdhe4096 | 4096 | DH_ffdhe4096 | 11+ |
407| DH | ffdhe6144 | 6144 | DH_ffdhe6144 | 11+ |
408| DH | ffdhe8192 | 8192 | DH_ffdhe8192 | 11+ |
409
410> **NOTE**
411>
412> 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.
413
414### Key Parameter
415
416Since API version 11, key parameters can be used to generate a DH key.
417
418The DH key includes the following properties:
419
420- **p**: a large prime used as a modulus of a finite field. It is shared by all communicating parties.
421
422- **g**: a primitive root modulo **p**. It is shared by all communicating parties.
423
424- **l**: length of the private key, in bits. The value **0** means the length of the private key is not specified.
425
426- **sk**: private key, which is a randomly generated value.
427
428- **pk**: public key, which is calculated using the common parameter (**p** and **g**) and the private key.
429
430The following table illustrates the composition of the DH key parameters.
431
432- √ indicates the property used to construct a key parameter.
433
434|  | Common Parameter| Public Key Parameter| Private Key Parameter| Key Pair Parameter|
435| -------- | -------- | -------- | -------- | -------- |
436| p | √ | √ | √ | √ |
437| g | √ | √ | √ | √ |
438| l | √ | √ | √ | √ |
439| pk | - | √ | - | √ |
440| sk | - | - | √ | √ |
441
442
443### Common Parameter Generated Based on the Prime Length and Private Key Length
444
445Since API version 11, the DH common parameter can be generated based on the prime length and private key length.
446
447If 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.
448
449| Prime Length (Bit)| Named DH Group|
450| -------- | -------- |
451| 2048 | ffdhe2048 |
452| 3072 | ffdhe3072 |
453| 4096 | ffdhe4096 |
454| 6144 | ffdhe6144 |
455| 8192 | ffdhe8192 |
456
457- The number of bits for **p** must be greater than or equal to 512 and less than or equal to 10000.
458
459- 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)
460
461- 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.
462
463- Named DH groups are recommended because generating a key parameter with an unnamed DH group is time-consuming.
464