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. In this mode, both the input and output data lengths must match the RSA key length, in bytes. 17 18- [PKCS1](#pkcs1): RSAES-PKCS1-V1_5 mode in RFC3447, corresponding to RSA_PKCS1_PADDING in OpenSSL. 19 20 During RSA operation, the source data **D** must be converted into an encryption block (EB). During encryption, the maximum length of the input data is the RSA key length minus 11 bytes. The length of the output data must match the RSA key length, in bytes. 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 digests (**md** and **mgf1_md**) must be set. During encryption, the input data length must meet the following requirement:<br>Input data length (bytes) < RSA key length – 2 * MD length – 2 25 26 The length of the output data must match the RSA key length, in bytes. 27 28 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). 29 30 | PKCS1_OAEP Parameter| Description| 31 | -------- | -------- | 32 | md | MD algorithm.| 33 | mgf | Mask generation function. Currently, only MGF1 is supported.| 34| mgf1_md | MD algorithm used in MGF1.| 35 | pSource | byte stream, which is the source for encoding input P in OAEP padding.| 36 37- The following table uses RSA2048|SHA256 as an example to describe the relationship between the input data length and the algorithm. 38 | Padding Mode| Maximum Input Data Length (Bytes)| Maximum Output Data Length (Bytes)| 39 | -------- | -------- | -------- | 40 | NoPadding | 256 (RSA key length)| 256 | 41 | PKCS1 | 245 (RSA key length – 11)| 256 | 42 | PKCS1_OAEP | 190 (RSA key length – 2 * MD length – 2) | 256 | 43 44> **NOTE** 45> 46> - It takes time to generate an RSA2048, RSA3072, RSA4096, or RSA8192 asymmetric key pair or when the plaintext length exceeds 2048 bits. 47> 48> - 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. 49 50### NoPadding 51 52The 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. 53 54| Asymmetric Key Type| String Parameter| API Version| 55| -------- | -------- | -------- | 56| RSA512 | RSA512\|NoPadding | 9+ | 57| RSA768 | RSA768\|NoPadding | 9+ | 58| RSA1024 | RSA1024\|NoPadding | 9+ | 59| RSA2048 | RSA2048\|NoPadding | 9+ | 60| RSA3072 | RSA3072\|NoPadding | 9+ | 61| RSA4096 | RSA4096\|NoPadding | 9+ | 62| RSA8192 | RSA8192\|NoPadding | 9+ | 63| RSA | RSA\|NoPadding | 10+ | 64 65As 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. 66 67 68### PKCS1 69 70The 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. 71 72| Asymmetric Key Type| String Parameter| API Version| 73| -------- | -------- | -------- | 74| RSA512 | RSA512\|PKCS1 | 9+ | 75| RSA768 | RSA768\|PKCS1 | 9+ | 76| RSA1024 | RSA1024\|PKCS1 | 9+ | 77| RSA2048 | RSA2048\|PKCS1 | 9+ | 78| RSA3072 | RSA3072\|PKCS1 | 9+ | 79| RSA4096 | RSA4096\|PKCS1 | 9+ | 80| RSA8192 | RSA8192\|PKCS1 | 9+ | 81| RSA | RSA\|PKCS1 | 10+ | 82 83As 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. 84 85 86### PKCS1_OAEP 87 88The 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. 89 90In the following table, the options included in the square brackets ([]) are mutually exclusive. You can use only one of them in a string parameter. 91 92For 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**. 93 94> **NOTE** 95> 96> The input data length must meet the following requirement: 97> 98> Input data length (bytes) < RSA key length – MD length – mgf1_md length – 2<br>For example, if the RSA key is of 512 bits, **SHA512** cannot be used. 99 100| Asymmetric Key Type| Padding Mode| MD Algorithm| Mask Digest Algorithm| API Version| 101| -------- | -------- | -------- | -------- | -------- | 102| RSA512 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ | 103| RSA512 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ | 104| RSA512 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256] | 9+ | 105| RSA768 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 106| RSA768 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 107| RSA768 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 108| RSA768 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384] | 9+ | 109| RSA1024 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 110| RSA1024 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 111| RSA1024 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 112| RSA1024 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 113| RSA1024 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 114| RSA2048 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 115| RSA2048 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 116| RSA2048 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 117| RSA2048 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 118| RSA2048 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 119| RSA2048 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 120| RSA3072 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 121| RSA3072 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 122| RSA3072 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 123| RSA3072 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 124| RSA3072 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 125| RSA3072 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 126| RSA4096 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 127| RSA4096 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 128| RSA4096 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 129| RSA4096 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 130| RSA4096 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 131| RSA4096 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 132| RSA8192 | PKCS1_OAEP | MD5 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 133| RSA8192 | PKCS1_OAEP | SHA1 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 134| RSA8192 | PKCS1_OAEP | SHA224 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 135| RSA8192 | PKCS1_OAEP | SHA256 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 136| RSA8192 | PKCS1_OAEP | SHA384 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 137| RSA8192 | PKCS1_OAEP | SHA512 | [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512] | 9+ | 138| RSA | PKCS1_OAEP | MD algorithm that meets the length requirements| MGF1_ MD algorithm that meets the length requirements| 10+ | 139 140As 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. 141 142 143### Getting and Setting of OAEP Parameters 144 145Since 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. 146 147| OAEP Parameter| Value| Get| Set| 148| -------- | -------- | -------- | -------- | 149| md | OAEP_MD_NAME_STR | √ | - | 150| mgf | OAEP_MGF_NAME_STR | √ | - | 151| mgf1_md | OAEP_MGF1_MD_STR | √ | - | 152| pSource | OAEP_MGF1_PSRC_UINT8ARR | √ | √ | 153 154 155## SM2 156 157[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. 158 159The 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. 160 161SM2 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. 162 163In 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 (_). 164 165For example, if the key length is 256 bits and the digest algorithm is MD5, the string parameter is **SM2_256|MD5**. 166| Asymmetric Key Type| MD Algorithm| API Version| 167| -------- | -------- | -------- | 168| SM2_256 | [MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3] | 10+ | 169| SM2 | [MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3] | 10+ | 170 171As 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. 172 173 174### SM2 MD Algorithm Parameter 175 176Since API version 11, SM2 MD digest algorithm parameter can be obtained. The symbol "√" indicates that the parameter can be obtained or set. 177 178| SM2 MD Algorithm Parameter| Value| Get| Set| 179| -------- | -------- | -------- | -------- | 180| md | SM2_MD_NAME_STR | √ | - | 181 182 183### SM2 Ciphertext Format 184 185Since 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. 186 187You 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. 188 189SM2 ciphertext consists of the following parameters: 190 191- **xCoordinate**: coordinate X of C1, that is, **C1_X**. 192 193- **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. 194 195- **cipherTextData**: ciphertext, that is, **C2**. 196 197- **hashData**: hash value, that is, **C3**. 198 199A string parameter can be used to specify the SM2 ciphertext format conversion mode. 200 201| SM2 Ciphertext Format Conversion Mode| Generate SM2 Ciphertext Based on Parameters| Obtain Parameters from SM2 Ciphertext| 202| -------- | -------- | -------- | 203| C1C3C2 | √ | √ | 204