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