1# Asymmetric Key Encryption and Decryption Algorithm Specifications 2 3 4This topic describes the supported algorithms and specifications for asymmetric key encryption and decryption. 5 6 7For details about the cipher modes supported by each algorithm, see the specifications of each algorithm. 8 9 10## RSA 11 12[RSA](crypto-asym-key-generation-conversion-spec.md#rsa) is an asymmetric cipher, with fixed-length blocks. If the data length does not meet the requirement, padding is required. 13 14The Crypto framework supports the following padding modes for RSA encryption and decryption: 15 16- [NoPadding](#nopadding): No padding. The length of the input or output data must be the same as that of the RSA modulus (**n** in bytes). 17 18- [PKCS1](#pkcs1): RSAES-PKCS1-V1_5 mode in RFC3447, corresponding to RSA_PKCS1_PADDING in OpenSSL. 19 20 The RSA converts the source data (**D**) into encryption blocks (EBs). In encryption, the length of the input data must be less than or equal to the RSA modulus minus 11. The length of the output data is the same as that of the RSA modulus. 21 22- [PKCS1_OAEP](#pkcs1_oaep): RSAES-OAEP mode in RFC 3447, corresponding to RSA_PKCS1_OAEP_PADDING in OpenSSL. 23 24 In this mode, two message digests (**md** and **mgf1_md**) need to be set. In encryption, the input data must meet the following requirements:<br>Input data length < RSA modulus length – **md** length (bytes) – **mgf1_md** length (bytes) – 2<br>The length of the output data is the same as that of the RSA modulus. 25 26 You can also set the **pSource** byte stream to define the encoding input for OAEP padding and obtain the PKCS1_OAEP parameters (as listed in the following table). 27 28 | PKCS1_OAEP Parameter| Description| 29 | -------- | -------- | 30 | md | MD algorithm.| 31 | mgf | Mask generation function. Currently, only MGF1 is supported.| 32 | mgf1_md | MD algorithm used in MGF1.| 33 | pSource | byte stream, which is the source for encoding input P in OAEP padding.| 34 35> **NOTE** 36> 37> It takes time to generate an RSA2048, RSA3072, RSA4096, or RSA8192 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. 38 39### NoPadding 40 41The RSA encryption and decryption can be implemented based a string parameter. When creating a **Cipher** instance, you need to specify the algorithm specifications in a string parameter. The string parameter consists of the asymmetric key type and padding mode (which is **NoPadding**) with a vertical bar (|) in between. 42 43| Asymmetric Key Type| String Parameter| API Version| 44| -------- | -------- | -------- | 45| RSA512 | RSA512\|NoPadding | 9+ | 46| RSA768 | RSA768\|NoPadding | 9+ | 47| RSA1024 | RSA1024\|NoPadding | 9+ | 48| RSA2048 | RSA2048\|NoPadding | 9+ | 49| RSA3072 | RSA3072\|NoPadding | 9+ | 50| RSA4096 | RSA4096\|NoPadding | 9+ | 51| RSA8192 | RSA8192\|NoPadding | 9+ | 52| RSA | RSA\|NoPadding | 10+ | 53 54As indicated by the last row in the preceding table, you can specify the RSA key type without the key length to ensure compatibility with the key generated based on the key parameter. In this case, the encryption or decryption operation varies depending on the actual key length. 55 56 57### PKCS1 58 59The RSA encryption and decryption can be implemented based a string parameter. When creating a **Cipher** instance, you need to specify the algorithm specifications in a string parameter. The string parameter consists of the asymmetric key type and padding mode (which is **PKCS1**) with a vertical bar (|) in between. 60 61| Asymmetric Key Type| String Parameter| API Version| 62| -------- | -------- | -------- | 63| RSA512 | RSA512\|PKCS1 | 9+ | 64| RSA768 | RSA768\|PKCS1 | 9+ | 65| RSA1024 | RSA1024\|PKCS1 | 9+ | 66| RSA2048 | RSA2048\|PKCS1 | 9+ | 67| RSA3072 | RSA3072\|PKCS1 | 9+ | 68| RSA4096 | RSA4096\|PKCS1 | 9+ | 69| RSA8192 | RSA8192\|PKCS1 | 9+ | 70| RSA | RSA\|PKCS1 | 10+ | 71 72As indicated by the last row in the preceding table, you can specify the RSA key type without the key length to ensure compatibility with the key generated based on the key parameter. In this case, the encryption or decryption operation varies depending on the actual key length. 73 74 75### PKCS1_OAEP 76 77The RSA encryption and decryption can be implemented based a string parameter. When creating a **Cipher** instance, you need to specify the algorithm specifications in a string parameter. The string parameter consists of the asymmetric key type, padding mode (which is **PKCS1_OAEP**), MD algorithm, and mask digest algorithm with a vertical bar (|) in between. 78 79In the following table, the options included in the square brackets ([]) are mutually exclusive. You can use only one of them in a string parameter. 80 81For example, if the asymmetric key type is **RSA2048**, the padding mode is **PKCS1_OAEP**, the MD algorithm is **SHA256**, and the mask digest algorithm is **MGF1_SHA256**, the string parameter is **RSA2048|PKCS1_OAEP|SHA256|MGF1\_SHA256**. 82 83> **NOTE** 84> 85> Input data length < RSA key modulus – **md** length – **mgf1_md** length – 2<br> For example, if the RSA key is of 512 bits, **SHA512** cannot be used. 86 87| Asymmetric Key Type| Padding Mode| MD Algorithm| Mask Digest Algorithm| API Version| 88| -------- | -------- | -------- | -------- | -------- | 89| RSA512 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ | 90| RSA512 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ | 91| RSA512 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ | 92| RSA768 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 93| RSA768 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 94| RSA768 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 95| RSA768 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384] | 9+ | 96| RSA1024 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 97| RSA1024 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 98| RSA1024 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 99| RSA1024 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 100| RSA1024 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 101| RSA2048 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 102| RSA2048 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 103| RSA2048 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 104| RSA2048 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 105| RSA2048 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 106| RSA2048 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 107| RSA3072 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 108| RSA3072 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 109| RSA3072 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 110| RSA3072 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 111| RSA3072 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 112| RSA3072 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 113| RSA4096 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 114| RSA4096 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 115| RSA4096 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 116| RSA4096 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 117| RSA4096 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 118| RSA4096 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 119| RSA8192 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 120| RSA8192 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 121| RSA8192 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 122| RSA8192 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 123| RSA8192 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 124| RSA8192 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 125| RSA | PKCS1_OAEP | MD algorithm that meets the length requirements| MGF1_ MD algorithm that meets the length requirements| 10+ | 126 127As indicated by the last row in the preceding table, you can specify the RSA key type without the key length to ensure compatibility with the key generated based on the key parameter. In this case, the encryption or decryption operation varies depending on the actual key length. 128 129 130### Getting and Setting of OAEP Parameters 131 132Since API version 10, OAEP parameters can be set and obtained when PKCS1_OAEP is used with RSA. In ths following table, the symbol "√" indicates that the parameter can be obtained or set. 133 134| OAEP Parameter| Value| Get| Set| 135| -------- | -------- | -------- | -------- | 136| md | OAEP_MD_NAME_STR | √ | - | 137| mgf | OAEP_MGF_NAME_STR | √ | - | 138| mgf1_md | OAEP_MGF1_MD_STR | √ | - | 139| pSource | OAEP_MGF1_PSRC_UINT8ARR | √ | √ | 140 141 142## SM2 143 144[SM2](crypto-asym-key-generation-conversion-spec.md#sm2) is an asymmetric encryption algorithm with a fixed length. Currently, the Crypto framework supports data encryption and decryption in the format defined in GM/T 0009-2012. 145 146The SM2 asymmetric encryption result consists of C1, C2, and C3. C1 is the elliptic curve points calculated based on the random number generated. C2 is the ciphertext data. C3 is the value calculated using the specified MD algorithm. 147 148SM2 encryption and decryption can be implemented based on a string parameter. When creating a **Cipher** instance, you need to specify the algorithm specifications in a string parameter. The string parameter consists of the asymmetric key type (algorithm_key length) and padding mode with a vertical bar (|) in between. 149 150In the following table, the options included in the square brackets ([]) are mutually exclusive. You can use only one of them in a string parameter. The SM2 algorithm and key length are separated by an underscore (_). 151 152For example, if the key length is 256 bits and the digest algorithm is MD5, the string parameter is **SM2_256|MD5**. 153| Asymmetric Key Type| MD Algorithm| API Version| 154| -------- | -------- | -------- | 155| SM2_256 | [MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3] | 10+ | 156| SM2 | [MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3] | 10+ | 157 158As indicated by the last row in the preceding table, you can specify the SM2 key type without the key length to ensure compatibility with the key generated based on the key parameter. In this case, the encryption or decryption operation varies depending on the actual key length. 159 160 161### SM2 MD Algorithm Parameter 162 163Since API version 11, SM2 MD digest algorithm parameter can be obtained. The symbol "√" indicates that the parameter can be obtained or set. 164 165| SM2 MD Algorithm Parameter| Value| Get| Set| 166| -------- | -------- | -------- | -------- | 167| md | SM2_MD_NAME_STR | √ | - | 168 169 170### SM2 Ciphertext Format 171 172Since API version 12, SM2 format conversion is supported. Currently, the SM2 ciphertext is in ASN.1 format, in which the parameters are in the **C1C3C2** order. 173 174You can convert the SM2 ciphertext into ASN.1 format based on the SM2 parameters specified or obtain SM2 parameters from the SM2 ciphertext in ASN.1 format. 175 176SM2 ciphertext consists of the following parameters: 177 178- **xCoordinate**: coordinate X of C1, that is, **C1_X**. 179 180- **yCoordinate**: coordinate Y of C1, that is, **C1_Y**. You can obtain **C1** based on **xCoordinate** and **yCoordinate**. **C1** is a point on the elliptic curve generated using a random number. 181 182- **cipherTextData**: ciphertext, that is, **C2**. 183 184- **hashData**: hash value, that is, **C3**. 185 186A string parameter can be used to specify the SM2 ciphertext format conversion mode. 187 188| SM2 Ciphertext Format Conversion Mode| Generate SM2 Ciphertext Based on Parameters| Obtain Parameters from SM2 Ciphertext| 189| -------- | -------- | -------- | 190| C1C3C2 | √ | √ | 191