1# Symmetric 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 specifications for symmetric key encryption and decryption. 11 12For details about the cipher modes supported by each algorithm, see the specifications of each algorithm. 13 14## AES 15 16The Crypto framework provides the following cipher modes for [AES](crypto-sym-key-generation-conversion-spec.md#aes) encryption and decryption: ECB, CBC, OFB, CFB, CTR, GCM, and CCM. The encryption and decryption parameters vary depending on the cipher mode. For details, see [ParamsSpec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#paramsspec). 17 18AES is a block cipher, with a fixed block size of 128 bits. If the last block is less than 128 bits (16 bytes), you can specify the [padding mode](#padding-mode) to pad data. 19 20Because the data is padded to the block size, **PKCS5** and **PKCS7** used in the Crypto framework use the block size as the padding length. That is, data is padded to 16 bytes for AES encryption. 21 22> **NOTE** 23> 24> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 128 bits. 25> In CCM encryption mode, the additional authentication data (AAD) must be specified and its length must be greater than 1 byte and less than 2048 bytes. 26 27The AES 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 symmetric key type (algorithm and key length), cipher block mode, and padding mode with a vertical bar (|) in between. 28 29- In the following table, the options included in the square brackets ([]) are mutually exclusive. You can use only one of them in a string parameter. 30 31 Example: 32 - If the cipher block mode is ECB and padding mode is **PKCS7** for a 128-bit AES key, the string parameter is **AES128|ECB|PKCS7**. 33 34 - If the cipher block mode is CFB and padding mode is **NoPadding** for a 256-bit AES key, the string parameter is **AES256|CFB|NoPadding**. 35 36 | Cipher Mode| Key Length (Bit)| Padding Mode| API Version| 37 | -------- | -------- | -------- | -------- | 38 | ECB | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 39 | CBC | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 40 | CTR | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 41 | OFB | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 42 | CFB | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 43 | GCM | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 44 | CCM | [128\|192\|256] | [NoPadding\|PKCS5\|PKCS7] | 9+ | 45 46- Since API version 10, symmetric encryption and decryption support the algorithm specifications without the key length. If the symmetric key type does not contain the key length, the encryption and decryption operations vary with the actual key length. 47 48 For example, if the block mode is CFB and the padding mode is **NoPadding** for an AES key with key length not specified, the string parameter is **AES|CFB|NoPadding**. 49 50## DES 51 52The encryption process of the [DES](crypto-sym-key-generation-conversion-spec.md#des) algorithm consists of 16 rounds of the same encryption function, with each round using a different key. These keys are generated by performing a series of permutation and shift operations on the original key. In each round, the plaintext block is divided into left and right parts. Then, the plaintext block is encrypted by a set of permutation, replacement, and XOR operations. 53 54The Crypto framework provides the following cipher modes for DES encryption and decryption: ECB, CBC, OFB, and CFB. The encryption and decryption parameters vary depending on the cipher mode. For details, see [ParamsSpec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#paramsspec). 55 56> **NOTE** 57> 58> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits. 59 60The DES 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 symmetric key type (algorithm and key length), cipher block mode, and padding mode with a vertical bar (|) in between. 61 62- In the following table, the options included in the square brackets ([]) are mutually exclusive. You can use only one of them in a string parameter. 63 64 Example: 65 - If the cipher block mode is ECB and padding mode is **PKCS7** for a 64-bit DES key, the string parameter is **DES64|ECB|PKCS7**. 66 67 - If the cipher block mode is OFB and padding mode is **NoPadding** for a 64-bit DES key, the string parameter is **DES64|OFB|NoPadding**. 68 69 | Cipher Mode| Key Length (Bit)| Padding Mode| API Version| 70 | -------- | -------- | -------- | -------- | 71 | ECB | 64 | [NoPadding\|PKCS5\|PKCS7] | 20+ | 72 | CBC | 64 | [NoPadding\|PKCS5\|PKCS7] | 20+ | 73 | OFB | 64 | [NoPadding\|PKCS5\|PKCS7] | 20+ | 74 | CFB | 64 | [NoPadding\|PKCS5\|PKCS7] | 20+ | 75 76- Since API version 10, symmetric encryption and decryption support the algorithm specifications without the key length. If the symmetric key type does not contain the key length, the encryption and decryption operations vary with the actual key length. 77 For example, if the block mode is CFB and the padding mode is **NoPadding** for a DES key with key length not specified, the string parameter is **DES|CFB|NoPadding**. 78 79## 3DES 80 81[3DES](crypto-sym-key-generation-conversion-spec.md#3des) encryption and decryption apply the DES cipher three times to each data block to obtain the ciphertext or plaintext. 82 83The Crypto framework provides the following cipher modes for 3DES encryption and decryption: ECB, CBC, OFB, and CFB. The encryption and decryption parameters vary depending on the cipher mode. For details, see [ParamsSpec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#paramsspec). 84 85DES is a block cipher, with a fixed block size of 64 bits. If the last block is less than 64 bits (8 bytes), you can specify the [padding mode](#padding-mode) to pad data. 86 87Because the data is padded to the block size, **PKCS5** and **PKCS7** used in the Crypto framework use the block size as the padding length. That is, data is padded to 8 bytes for 3DES encryption. 88 89> **NOTE** 90> 91> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits. 92 93The 3DES 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 symmetric key type (algorithm and key length), cipher block mode, and padding mode with a vertical bar (|) in between. 94 95- In the following table, the options included in the square brackets ([]) are mutually exclusive. You can use only one of them in a string parameter. 96 97 Example: 98 - If the cipher block mode is ECB and padding mode is **PKCS7** for a 192-bit 3DES key, the string parameter is **3DES192|ECB|PKCS7**. 99 100 - If the cipher block mode is OFB and padding mode is **NoPadding** for a 192-bit 3DES key, the string parameter is **3DES192|OFB|NoPadding**. 101 102 | Cipher Mode| Key Length (Bit)| Padding Mode| API Version| 103 | -------- | -------- | -------- | -------- | 104 | ECB | 192 | [NoPadding\|PKCS5\|PKCS7] | 9+ | 105 | CBC | 192 | [NoPadding\|PKCS5\|PKCS7] | 9+ | 106 | OFB | 192 | [NoPadding\|PKCS5\|PKCS7] | 9+ | 107 | CFB | 192 | [NoPadding\|PKCS5\|PKCS7] | 9+ | 108 109- Since API version 10, symmetric encryption and decryption support the algorithm specifications without the key length. If the symmetric key type does not contain the key length, the encryption and decryption operations vary with the actual key length. 110 For example, if the block mode is CFB and the padding mode is **NoPadding** for a 3DES key with key length not specified, the string parameter is **3DES|CFB|NoPadding**. 111 112## SM4 113 114The Crypto framework provides the following cipher modes for [SM4](crypto-sym-key-generation-conversion-spec.md#sm4) encryption and decryption: ECB, CBC, CTR, OFB, CFB, CFB128, and GCM. The encryption and decryption parameters vary depending on the cipher mode. For details, see [ParamsSpec](../../reference/apis-crypto-architecture-kit/js-apis-cryptoFramework.md#paramsspec). 115 116SM4 is a block cipher, with a fixed block size of 128 bits. If the last block is less than 128 bits (16 bytes), you can specify the [padding mode](#padding-mode) to pad data. 117 118Because the data is padded to the block size, **PKCS5** and **PKCS7** used in the Crypto framework use the block size as the padding length. That is, data is padded to 16 bytes for SM4 encryption. 119 120> **NOTE** 121> 122> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 128 bits. 123 124The SM4 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 symmetric key type (algorithm_key length), cipher block mode, and padding mode with a vertical bar (|) in between. 125 126- In 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 SM4 algorithm and key length are separated by an underscore (_). 127 128 Example: 129 - If the cipher block mode is ECB and padding mode is **PKCS7** for a 128-bit SM4 key, the string parameter is **SM4_128|ECB|PKCS7**. 130 131 - If the cipher block mode is CFB and padding mode is **NoPadding** for a 128-bit SM4 key, the string parameter is **SM4_128|CFB|NoPadding**. 132 133 - If the cipher block mode is GCM and padding mode is **NoPadding** for a 128-bit SM4 key, the string parameter is **SM4_128|GCM|NoPadding**. 134 135 | Cipher Mode| Key Length (Bit)| Padding Mode| API Version| 136 | -------- | -------- | -------- | -------- | 137 | ECB | 128 | [NoPadding\|PKCS5\|PKCS7] | 10+ | 138 | CBC | 128 | [NoPadding\|PKCS5\|PKCS7] | 10+ | 139 | CTR | 128 | [NoPadding\|PKCS5\|PKCS7] | 10+ | 140 | OFB | 128 | [NoPadding\|PKCS5\|PKCS7] | 10+ | 141 | CFB | 128 | [NoPadding\|PKCS5\|PKCS7] | 10+ | 142 | CFB128 | 128 | [NoPadding\|PKCS5\|PKCS7] | 10+ | 143 | GCM | 128 | [NoPadding\|PKCS5\|PKCS7] | 12+ | 144 145## Padding Mode 146 147The block cipher algorithm has a fixed block length. If the length of the last block does not meet the requirement, data will be added to extend the block to the required length based on the padding mode. The following padding modes are supported: 148 149- **NoPadding**: no padding. The length of the input data must match the block length. 150 151- **PKCS5**: pads a block cipher with a block size of 8 bytes. PKCS#5 applies padding in whole bytes. The value of each added byte is the number of bytes that are added. 152 153- **PKCS7**: pads a block cipher with a block size from 1 to 255 bytes. The padding scheme is the same as that of PKCS#5. PKCS#5 is defined for 8-byte block sizes, while PKCS#7 can work with block size ranging from 1 to 255 bytes. 154 155For the modes that convert block ciphers into stream ciphers, such as CFB, OFB, CTR, GCM, and CCM, padding is not required. Therefore, **NoPadding** is used no matter whether the padding mode is specified. 156