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