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