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