0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
Www140421update docs
3a6ba017创建于 24 天前历史提交

Symmetric Key Encryption and Decryption Algorithm Specifications

This topic describes the supported algorithms and specifications for symmetric key encryption and decryption.

For details about the cipher modes supported by each algorithm, see the specifications of each algorithm.

AES

The Crypto framework provides the following cipher modes for 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.

AES 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 to pad data.

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

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 128 bits. In CCM encryption mode, the additional authentication data (AAD) must be specified and its length must be greater than 1 byte and fewer than 2,048 bytes.

The AES 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 symmetric key type (algorithm and key length), block cipher mode, and padding mode with a vertical bar (|) in between.

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

    Example:

    • If the block cipher mode is ECB, key length is 128 bits, and padding mode is PKCS7, the string parameter is AES128|ECB|PKCS7.

    • If the block cipher mode is CFB, key length is 256 bits, and padding mode is NoPadding, the string parameter is AES256|CFB|NoPadding.

    Block Cipher Mode Key Length (Bit) Padding Mode API Version
    ECB [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    CBC [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    CTR [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    OFB [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    CFB [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    GCM [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    CCM [128|192|256] [NoPadding|PKCS5|PKCS7] 9+
    XTS [128|256] [NoPadding] 26.0.0+

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

    For example, if the block cipher mode is CFB and padding mode is NoPadding for a key with length not specified, the string parameter is AES|CFB|NoPadding.

DES

The encryption process of the 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.

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

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.

The DES 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 symmetric key type (algorithm and key length), block cipher mode, and padding mode with a vertical bar (|) in between.

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

    Example:

    • If the block cipher mode is ECB, key length is 64 bits, and padding mode is PKCS7, the string parameter is DES64|ECB|PKCS7.

    • If the block cipher mode is OFB, key length is 64 bits, and padding mode is NoPadding, the string parameter is DES64|OFB|NoPadding.

    Block Cipher Mode Key Length (Bit) Padding Mode API Version
    ECB 64 [NoPadding|PKCS5|PKCS7] 20+
    CBC 64 [NoPadding|PKCS5|PKCS7] 20+
    OFB 64 [NoPadding|PKCS5|PKCS7] 20+
    CFB 64 [NoPadding|PKCS5|PKCS7] 20+

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

    For example, if the block cipher mode is CFB and padding mode is NoPadding for a key with length not specified, the string parameter is DES|CFB|NoPadding.

3DES

3DES encryption and decryption apply the DES cipher three times to each data block to obtain the ciphertext or plaintext.

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

DES 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 to pad data.

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

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.

The 3DES 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 symmetric key type (algorithm and key length), block cipher mode, and padding mode with a vertical bar (|) in between.

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

    Example:

    • If the block cipher mode is ECB, key length is 192 bits, and padding mode is PKCS7, the string parameter is 3DES192|ECB|PKCS7.

    • If the block cipher mode is OFB, key length is 192 bits, and padding mode is NoPadding, the string parameter is 3DES192|OFB|NoPadding.

    Block Cipher Mode Key Length (Bit) Padding Mode API Version
    ECB 192 [NoPadding|PKCS5|PKCS7] 9+
    CBC 192 [NoPadding|PKCS5|PKCS7] 9+
    OFB 192 [NoPadding|PKCS5|PKCS7] 9+
    CFB 192 [NoPadding|PKCS5|PKCS7] 9+

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

    For example, if the block cipher mode is CFB and padding mode is NoPadding for a key with length not specified, the string parameter is 3DES|CFB|NoPadding.

SM4

The Crypto framework provides the following cipher modes for 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.

SM4 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 to pad data.

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

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 128 bits.

The SM4 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 symmetric key type (algorithm and key length), block cipher mode, and padding mode with a vertical bar (|) in between.

  • 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 (_).

    Example:

    • If the block cipher mode is ECB, key length is 128 bits, and padding mode is PKCS7, the string parameter is SM4_128|ECB|PKCS7.

    • If the block cipher mode is CFB, key length is 128 bits, and padding mode is NoPadding, the string parameter is SM4_128|CFB|NoPadding.

    • If the block cipher mode is GCM, key length is 128 bits, and padding mode is NoPadding, the string parameter is SM4_128|GCM|NoPadding.

    Block Cipher Mode Key Length (Bit) Padding Mode API Version
    ECB 128 [NoPadding|PKCS5|PKCS7] 10+
    CBC 128 [NoPadding|PKCS5|PKCS7] 10+
    CTR 128 [NoPadding|PKCS5|PKCS7] 10+
    OFB 128 [NoPadding|PKCS5|PKCS7] 10+
    CFB 128 [NoPadding|PKCS5|PKCS7] 10+
    CFB128 128 [NoPadding|PKCS5|PKCS7] 10+
    GCM 128 [NoPadding|PKCS5|PKCS7] 12+

AES-WRAP

The Crypto framework provides the AES-WRAP algorithm, which is an encryption algorithm based on AES and is used to securely store or transmit symmetric keys. This algorithm is used to protect keys by encrypting them, preventing keys from being disclosed or tampered with during storage or transmission.

Algorithm String Parameter API Version
AES128_WRAP AES128_WRAP 22+
AES256_WRAP AES256_WRAP 22+
AES384_WRAP AES384_WRAP 22+

Padding Mode

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

  • NoPadding: no padding. The length of the input data must match the block length.

  • PKCS5: pads a block cipher with a block size of 8 bytes. PKCS#5 applies padding in whole bytes. The value of each padding byte is equal to the length of the byte sequence to be padded.

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

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

ChaCha20

The Crypto framework supports this algorithm since API version 22.

The Crypto framework provides ChaCha20 encryption and decryption, which requires the IV to be passed by default. Specifically, the IvParamsSpec parameter is needed.

The most commonly used encryption mode is Poly1305, which works with the Poly1305ParamsSpec parameter.

ChaCha20 is a stream cipher, so no padding algorithm is required.

ChaCha20 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 symmetric key type and block cipher mode with a vertical bar (|) in between.

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.

Symmetric Algorithm Name Key Length (Bit) String Parameter API Version
ChaCha20 256 ChaCha20 22+
ChaCha20 256 ChaCha20|Poly1305 22+

RC2

In API version 26.0.0 and later versions, the block cryptographic algorithm RC2 is supported. The block length is 64 bits, and the key length ranges from 8 bits to 1024 bits.

The Crypto framework provides the following block cipher modes for RC2 encryption and decryption: ECB, CBC, OFB, and CFB. The encryption and decryption parameters vary depending on the cipher mode. For details, see ParamsSpec.

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.

RC2 encryption and decryption can be implemented based on a string parameter, which consists of the symmetric key type, block cipher mode, and padding mode separated by vertical bars (|). The string parameter is RC2.

In CBC, OFB, and CFB modes, an IV must be passed. The IV length is 8 bytes, corresponding to IvParamsSpec.

Block Cipher Mode String Parameter Padding Mode API Version
ECB RC2 [NoPadding|PKCS5|PKCS7] 26.0.0+
CBC RC2 [NoPadding|PKCS5|PKCS7] 26.0.0+
OFB RC2 [NoPadding|PKCS5|PKCS7] 26.0.0+
CFB RC2 [NoPadding|PKCS5|PKCS7] 26.0.0+

RC4

In API version 26.0.0 and later versions, the stream cryptographic algorithm RC4 is supported. No block cipher or padding is required. The key length ranges from 8 bits to 4096 bits.

The Crypto framework provides RC4 encryption and decryption. RC4 is a stream cipher mode and does not require block cipher or padding modes.

Currently, RC4 encryption and decryption can be performed using the string parameter RC4.

Symmetric Algorithm Name String Parameter API Version
RC4 RC4 26.0.0+

Blowfish (BF)

In API version 26.0.0 and later versions, the block cipher algorithm Blowfish is supported. The block length is 64 bits, and the key length ranges from 32 bits to 448 bits.

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.

In CBC, OFB, and CFB modes, an IV must be passed. The IV length is 8 bytes, corresponding to IvParamsSpec.

Currently, Blowfish encryption and decryption can be performed using the string parameter Blowfish.

Block Cipher Mode String Parameter Padding Mode API Version
ECB Blowfish [NoPadding|PKCS5|PKCS7] 26.0.0+
CBC Blowfish [NoPadding|PKCS5|PKCS7] 26.0.0+
OFB Blowfish [NoPadding|PKCS5|PKCS7] 26.0.0+
CFB Blowfish [NoPadding|PKCS5|PKCS7] 26.0.0+

CAST

In API version 26.0.0 and later, the block cryptographic algorithm CAST is supported. The block length is 64 bits, and the key length ranges from 40 bits to 128 bits.

CAST is a block cryptographic algorithm. The block length is 64 bits, and the key length ranges from 40 bits to 128 bits.

The Crypto framework provides the following block cipher modes for CAST encryption and decryption: ECB, CBC, OFB, and CFB. The encryption and decryption parameters vary depending on the cipher mode. For details, see ParamsSpec.

NOTE

In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.

Currently, CAST encryption and decryption can be performed using the string parameter CAST.

In CBC, OFB, and CFB modes, an IV must be passed. The IV length is 8 bytes, corresponding to IvParamsSpec.

Block Cipher Mode String Parameter Padding Mode API Version
ECB CAST [NoPadding|PKCS5|PKCS7] 26.0.0+
CBC CAST [NoPadding|PKCS5|PKCS7] 26.0.0+
OFB CAST [NoPadding|PKCS5|PKCS7] 26.0.0+
CFB CAST [NoPadding|PKCS5|PKCS7] 26.0.0+