Asymmetric Key Generation and Conversion Specifications

This 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:

  • String parameter: presents the specifications of the key to generate in the form of a string.

  • Key parameter: constructs the detailed cryptographic information of the key to generate in an object.

For details, see the specifications of each algorithm.

RSA

Rivest-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.

String Parameter

When 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.

NOTE When an RSA asymmetric key is generated, the default number of primes is 2 and the PRIMES_2 parameter can be omitted.

RSA Key Type Prime Count String Parameter API Version
RSA512 2 RSA512|PRIMES_2 9+
RSA768 2 RSA768|PRIMES_2 9+
RSA1024 2 RSA1024|PRIMES_2 9+
RSA1024 3 RSA1024|PRIMES_3 9+
RSA2048 2 RSA2048|PRIMES_2 9+
RSA2048 3 RSA2048|PRIMES_3 9+
RSA3072 2 RSA3072|PRIMES_2 9+
RSA3072 3 RSA3072|PRIMES_3 9+
RSA4096 2 RSA4096|PRIMES_2 9+
RSA4096 3 RSA4096|PRIMES_3 9+
RSA4096 4 RSA4096|PRIMES_4 9+
RSA8192 2 RSA8192|PRIMES_2 9+
RSA8192 3 RSA8192|PRIMES_3 9+
RSA8192 4 RSA8192|PRIMES_4 9+
RSA8192 5 RSA8192|PRIMES_5 9+

Key Parameter

Since API version 10, key parameters can be used to generate an RSA key.

The RSA key includes the following integers:

  • n: modulus for both the private and public keys.

  • sk: private exponent, which is often written as d in the formula.

  • pk: public exponent, which is often written as e in the formula.

The following table illustrates the composition of the RSA key parameters.

  • √ indicates the property used to construct a key parameter.

  • x indicates that the property that cannot be used to construct a key parameter.

Common Parameter Public Key Parameter Private Key Parameter Key Pair Parameter
n × √ × √
pk - √ - √
sk - - × √

According to the preceding table:

  • The RSA key cannot be generated based on the common parameter (n).

  • The RSA private key cannot be generated based on the private key parameter, which consists of n and sk.

ECC

Elliptic-curve cryptography (ECC) is a public-key encryption algorithm based on elliptic curve mathematics.

The 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.

An 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.

String Parameter

When 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.

Asymmetric Key Algorithm Key Length (Bit) Curve Name String Parameter API Version
ECC 224 NID_secp224r1 ECC224 9+
ECC 256 NID_X9_62_prime256v1 ECC256 9+
ECC 384 NID_secp384r1 ECC384 9+
ECC 521 NID_secp521r1 ECC521 9+
ECC 160 NID_brainpoolP160r1 ECC_BrainPoolP160r1 11+
ECC 160 NID_brainpoolP160t1 ECC_BrainPoolP160t1 11+
ECC 192 NID_brainpoolP192r1 ECC_BrainPoolP192r1 11+
ECC 192 NID_brainpoolP192t1 ECC_BrainPoolP192t1 11+
ECC 224 NID_brainpoolP224r1 ECC_BrainPoolP224r1 11+
ECC 224 NID_brainpoolP224t1 ECC_BrainPoolP224t1 11+
ECC 256 NID_brainpoolP256r1 ECC_BrainPoolP256r1 11+
ECC 256 NID_brainpoolP256t1 ECC_BrainPoolP256t1 11+
ECC 320 NID_brainpoolP320r1 ECC_BrainPoolP320r1 11+
ECC 320 NID_brainpoolP320t1 ECC_BrainPoolP320t1 11+
ECC 384 NID_brainpoolP384r1 ECC_BrainPoolP384r1 11+
ECC 384 NID_brainpoolP384t1 ECC_BrainPoolP384t1 11+
ECC 512 NID_brainpoolP512r1 ECC_BrainPoolP512r1 11+
ECC 512 NID_brainpoolP512t1 ECC_BrainPoolP512t1 11+

Key Parameter

Since API version 10, key parameters can be used to generate an ECC key.

The ECC key in the Fp field includes the following properties:

  • p: prime used to determine Fp.

  • a, b: determine the elliptic curve equation.

  • g: base point of the elliptic curve, which can be represented as gx or gy.

  • n: order of the base point g.

  • h: cofactor.

  • sk: private key, which is a random integer less than n.

  • pk: public key, which is a point on the elliptic curve. pk = sk x g.

The following table illustrates the composition of the ECC key parameters.

  • √ indicates the property used to construct a key parameter.
Common Parameter Public Key Parameter Private Key Parameter Key Pair Parameter
fieldType √ √ √ √
p √ √ √ √
a √ √ √ √
b √ √ √ √
g √ √ √ √
n √ √ √ √
h √ √ √ √
pk - √ - √
sk - - √ √

NOTE

  • 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 currently.

  • g and pk are points of the Point type on the ECC curve. You need to specify their X and Y coordinates.

Curve Name

Since API version 11, the ECC common parameter can be generated based on a curve name.

NOTE

  • The curve name is a string parameter. For details about the supported curve names, see the Curve Name column in ECC String Parameter.

  • 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.

DSA

Digital 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.

A DSA key can be generated based on a string parameter or key parameters.

String Parameter

When 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.

Asymmetric Key Algorithm Key Length (Bit) String Parameter API Version
DSA 1024 DSA1024 10+
DSA 2048 DSA2048 10+
DSA 3072 DSA3072 10+

Key Parameter

Since API version 10, key parameters can be used to generate a DSA key.

The DSA key includes the following properties:

  • p: prime modulus, whose length is an integer multiple of 64.

  • q: prime factor of p – 1. The length varies depending on the length of p.

  • g: g = (h ^ ((p – 1)/q)) mod p, where h is an integer greater than 1 and less than p minus 1.

  • sk: private key, which is a randomly generated integer greater than 0 and less than q.

  • pk: public key. pk = (g ^ sk) mod p

The following table illustrates the composition of the DSA key parameters.

  • √ indicates the property used to construct a key parameter.

  • x indicates that the property that cannot be used to construct a key parameter.

Common Parameter Public Key Parameter Private Key Parameter Key Pair Parameter
p √ √ × √
q √ √ × √
g √ √ × √
pk - √ - √
sk - - × √

NOTE

  • The DSA private key cannot be generated based on the private key parameter, which consists of p, q, g, and sk.

  • 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.

SM2

ShangMi 2 (SM2) is a public key cryptographic algorithm based on ECC. The SM2 algorithm uses the elliptic curves over the Fp field.

An 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.

String Parameter

When 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.

Asymmetric Key Algorithm Key Length (Bit) Curve Name String Parameter API Version
SM2 256 NID_sm2 SM2_256 10+

Key Parameter

Since API version 11, key parameters can be used to generate an SM2 key.

The SM2 key in the Fp field includes the following properties:

  • p: prime used to determine Fp.

  • a, b: determine the elliptic curve equation.

  • g: base point of the elliptic curve, which can be represented as gx or gy.

  • n: order of the base point g.

  • h: cofactor.

  • sk: private key, which is a random integer less than n.

  • pk: public key, which is a point on the elliptic curve. pk = sk x g.

The following table illustrates the composition of the SM2 key parameters.

  • √ indicates the property used to construct a key parameter.
Common Parameter Public Key Parameter Private Key Parameter Key Pair Parameter
fieldType √ √ √ √
p √ √ √ √
a √ √ √ √
b √ √ √ √
g √ √ √ √
n √ √ √ √
h √ √ √ √
pk - √ - √
sk - - √ √

NOTE

  • 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 currently.

  • g and pk are points of the Point type on the SM2 curve. You need to specify their X and Y coordinates.

Curve Name

Since API version 11, the SM2 common parameter can be generated based on a curve name.

NOTE

  • The curve name is a string parameter. The supported curve name is NID_sm2.

  • 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.

Ed25519

Ed25519 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.

An Ed25519 key can be generated based on a string parameter or key parameters.

String Parameter

When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter.

Asymmetric Key Algorithm String Parameter API Version
Ed25519 Ed25519 11+

Key Parameter

Since API version 11, key parameters can be used to generate an Ed25519 key.

The Ed25519 key includes the following properties:

  • sk: private key, which is a 32-byte random value.

  • pk: public key, a 32-byte value derived from the private key.

The following table illustrates the composition of the Ed25519 key parameters.

  • √ indicates the property used to construct a key parameter.
Public Key Parameter Private Key Parameter Key Pair Parameter
pk √ - √
sk - √ √

NOTE Ed25519 does not have the common parameter.

X25519

X25519 is a Diffie-Hellman key exchange algorithm used for key agreement.

An X25519 key can be generated based on a string parameter or key parameters.

String Parameter

When creating an asymmetric key generator instance, you need to specify the key specifications in a string parameter.

Asymmetric Key Algorithm String Parameter API Version
X25519 X25519 11+

Key Parameter

Since API version 11, key parameters can be used to generate an X25519 key.

The X22519 key includes the following properties:

  • sk: private key, which is a 32-byte random value.

  • pk: public key, a 32-byte value derived from the private key.

The following table illustrates the composition of the X25519 key parameters.

  • √ indicates the property used to construct a key parameter.
Public Key Parameter Private Key Parameter Key Pair Parameter
pk √ - √
sk - √ √

NOTE X25519 does not have the common parameter.

DH

Diffie–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.

A 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.

String Parameter

When 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.

Asymmetric Key Algorithm Named DH Group Key Length (Bit) String Parameter API Version
DH modp1536 1536 DH_modp1536 11+
DH modp2048 2048 DH_modp2048 11+
DH modp3072 3072 DH_modp3072 11+
DH modp4096 4096 DH_modp4096 11+
DH modp6144 6144 DH_modp6144 11+
DH modp8192 8192 DH_modp8192 11+
DH ffdhe2048 2048 DH_ffdhe2048 11+
DH ffdhe3072 3072 DH_ffdhe3072 11+
DH ffdhe4096 4096 DH_ffdhe4096 11+
DH ffdhe6144 6144 DH_ffdhe6144 11+
DH ffdhe8192 8192 DH_ffdhe8192 11+

Key Parameter

Since API version 11, key parameters can be used to generate a DH key.

The DH key includes the following properties:

  • p: a large prime used as a modulus of a finite field. It is shared by all communicating parties.

  • g: a primitive root modulo p. It is shared by all communicating parties.

  • l: length of the private key, in bits. The value 0 means the length of the private key is not specified.

  • sk: private key, which is a randomly generated value.

  • pk: public key, which is calculated using the common parameter (p and g) and the private key.

The following table illustrates the composition of the DH key parameters.

  • √ indicates the property used to construct a key parameter.
Common Parameter Public Key Parameter Private Key Parameter Key Pair Parameter
p √ √ √ √
g √ √ √ √
l √ √ √ √
pk - √ - √
sk - - √ √

Common Parameter Generated Based on the Prime Length and Private Key Length

Since API version 11, the DH common parameter can be generated based on the prime length and private key length.

If 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.

Prime Length (Bit) Named DH Group
2048 ffdhe2048
3072 ffdhe3072
4096 ffdhe4096
6144 ffdhe6144
8192 ffdhe8192

  • The number of bits for p must be greater than or equal to 512 and less than or equal to 10000.

  • The parameter l (private key length) is optional. The default value is 0. The value of l must meet the following requirements:
    l > 2*(96 + (Length of p – 1)/1024 x 16)

  • 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.

  • Named DH groups are recommended because generating a key parameter with an unnamed DH group is time-consuming.