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