In data storage or transmission scenarios, encryption and decryption operations can be used to ensure data confidentiality and prevent sensitive data leakage.
Typical scenarios for using encryption and decryption operations include:
-
Encryption and decryption operations using symmetric keys.
-
Encryption and decryption operations using asymmetric keys.
-
Obtaining and setting CipherSpecItem parameters when using RSA (PKCS1_OAEP padding mode).
Symmetric Key Encryption/Decryption Algorithm Specifications
This section describes the algorithms currently supported by the system and their corresponding specifications.
For each algorithm, the supported encryption modes are introduced in the specification of that specific algorithm.
[h2]AES
The algorithm library currently provides seven commonly used encryption modes for AES encryption and decryption: ECB, CBC, OFB, CFB, CTR, GCM, and CCM. Different encryption modes apply to different encryption and decryption parameters. For details, see ParamsSpec.
Because AES is a block cipher algorithm, its block length is 16 bytes. In actual applications, the last block of plaintext may be less than 16 bytes. In this case, data can be padded using different padding modes.
Because padding to the block size is required, both PKCS5 and PKCS7 in the actual algorithm library use the block size as the padding length. That is, AES encryption pads to 16 bytes.
Note:
For the ECB and CBC encryption modes, if the plaintext length is not a multiple of 16 bytes, a padding method must be used to make up the difference.
For the CCM encryption mode, the additional authentication data (AAD) must be specified, and its length must be greater than or equal to 1 byte and less than or equal to 2048 bytes.
Currently, AES encryption and decryption can be performed using a string parameter. The specific "string parameter" is formed by concatenating the "symmetric key type (encryption/decryption algorithm + key length)", "block mode", and "padding mode" with the symbol "|", and is used to specify the algorithm specification when creating a symmetric encryption/decryption instance.
-
As shown in the table, only one item can be selected from each value range (that is, the content in []) to complete the string concatenation.
Examples:
-
When the block mode is ECB, the key length is 128 bits, and the padding mode is PKCS7, the string parameter is "AES128|ECB|PKCS7".
-
When the block mode is CFB, the key length is 256 bits, and the padding mode is NoPadding, the string parameter is "AES256|CFB|NoPadding".
Block 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+ -
-
Starting from API version 10, symmetric encryption/decryption specifications without a key length are supported. When the encryption/decryption parameter is input as a key type, omitting the length is supported, and the encryption/decryption operation depends on the actual key length of the input key.
For example, when the block mode is CFB, no key length is specified, and the padding mode is NoPadding, the string parameter is "AES|CFB|NoPadding".
[h2]DES
The encryption process of the DES algorithm consists of 16 rounds of the same encryption function, each round using a different subkey. The subkeys 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 halves, which are then encrypted through a series of permutation, substitution, and XOR operations.
The algorithm library currently provides four common encryption modes for DES encryption and decryption: ECB, CBC, OFB, and CFB. Different encryption modes apply to different encryption and decryption parameters. For details, see ParamsSpec.
Note:
For the ECB and CBC encryption modes, if the plaintext length is not an integer multiple of 64 bits, a padding method must be used to fill it.
Currently, DES encryption and decryption can be completed using a string parameter. The specific "string parameter" is formed by concatenating the "symmetric key type (encryption/decryption algorithm + key length)", "block mode", and "padding mode" with the symbol "|", and is used to specify the algorithm specification when creating a symmetric encryption/decryption instance.
-
As shown in the table, only one item can be selected from each value range (that is, the content in []) to complete the string concatenation.
Examples:
-
When the block mode is ECB, the key length is 64 bits, and the padding mode is PKCS7, the string parameter is "DES64|ECB|PKCS7".
-
When the block mode is OFB, the key length is 64 bits, and the padding mode is NoPadding, the string parameter is "DES64|OFB|NoPadding".
Block 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+ -
-
Starting from API version 10, symmetric encryption/decryption specifications without a key length are supported. When the encryption/decryption parameter inputs a key type, omitting the length is supported, and the encryption/decryption operation depends on the actual input key length.
For example, when the block mode is CFB, no key length is specified, and the padding mode is NoPadding, the string parameter is "DES|CFB|NoPadding".
[h2]3DES
The encryption and decryption process of the 3DES algorithm performs DES encryption or decryption three times on the plaintext/ciphertext data respectively, yielding the corresponding ciphertext or plaintext.
The algorithm library currently provides four commonly used encryption modes for 3DES encryption and decryption: ECB, CBC, OFB, and CFB. Different encryption modes apply to different encryption and decryption parameters. For details, see ParamsSpec.
Because DES is a block cipher algorithm with a block length of 8 bytes, in practical applications the last block of plaintext may be fewer than 8 bytes. In this case, data padding can be performed through different padding modes.
Because padding to the block size is required, both PKCS5 and PKCS7 in the actual algorithm library use the block size as the padding length, that is, 3DES encryption pads to 8 bytes.
Note:
For the ECB and CBC encryption modes, if the plaintext length is not an integer multiple of 8 bytes, a padding method must be used to make up the difference.
Currently, 3DES encryption and decryption can be completed using a string parameter. The specific "string parameter" is formed by concatenating the "symmetric key type (encryption/decryption algorithm + key length)", the "block mode", and the "padding mode" with the symbol "|", and is used to specify the algorithm specification when creating a symmetric encryption/decryption instance.
-
As shown in the table, only one item can be selected from each value range (that is, the content in []) to complete the string concatenation.
For example:
-
When the block mode is ECB, the key length is 192 bits, and the padding mode is PKCS7, the string parameter is "3DES192|ECB|PKCS7".
-
When the block mode is OFB, the key length is 192 bits, and the padding mode is NoPadding, the string parameter is "3DES192|OFB|NoPadding".
Block 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+ -
-
Starting from API version 10, symmetric encryption and decryption specifications without a key length are supported. When a key type is input as the encryption/decryption parameter, the key length can be omitted, and the encryption/decryption operation depends on the actual input key length.
For example, when the block mode is CFB, no key length is specified, and the padding mode is NoPadding, the string parameter is "3DES|CFB|NoPadding".
[h2]SM4
The algorithm library currently provides seven commonly used encryption modes for SM4 encryption and decryption: ECB, CBC, CTR, OFB, CFB, CFB128, and GCM. Different encryption modes apply to different encryption and decryption parameters. For details, see ParamsSpec.
Because SM4 is a block cipher algorithm with a block length of 16 bytes, in actual applications the last block of plaintext may be shorter than 16 bytes. In this case, data can be padded using different padding modes.
Because padding to the block size is required, both PKCS5 and PKCS7 in the actual algorithm library use the block size as the padding length; that is, SM4 encryption pads to 16 bytes.
For the ECB and CBC encryption modes, if the plaintext length is not an integer multiple of 16 bytes, a padding method must be used to make up the difference.
Currently, SM4 encryption and decryption can be performed using a string parameter. The specific "string parameter" is formed by concatenating the "symmetric key type (encryption/decryption algorithm + key length)", the "block mode", and the "padding mode" with the symbol "|", and is used to specify the algorithm specification when creating a symmetric encryption/decryption instance.
-
As shown in the table, only one item can be selected from each value range (that is, the content in []) to complete the string concatenation. The SM4 algorithm and the key length are concatenated with the symbol "_".
Examples:
-
When the block mode is ECB, the key length is 128 bits, and the padding mode is PKCS7, the string parameter is "SM4_128|ECB|PKCS7".
-
When the block mode is CFB, the key length is 128 bits, and the padding mode is NoPadding, the string parameter is "SM4_128|CFB|NoPadding".
-
When the block mode is GCM, the key length is 128 bits, and the padding mode is NoPadding, the string parameter is "SM4_128|GCM|NoPadding".
Block 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+ -
[h2]AES-WRAP
The algorithm library provides the AES-WRAP algorithm, which is an encryption algorithm based on AES and is used to securely store or transmit symmetric keys. Its main purpose is to protect keys through encryption, preventing keys from being leaked or tampered with during storage or transmission.
| Algorithm Name | String Parameter | API Version |
|---|---|---|
| AES128_WRAP | AES128_WRAP | 22+ |
| AES192_WRAP | AES192_WRAP | 22+ |
| AES256_WRAP | AES256_WRAP | 22+ |
[h2]Padding Mode
Block cipher algorithms have a fixed block length. In actual applications, the data volume of the last plaintext block may not reach the fixed length requirement. In this case, data padding can be performed through different padding modes. The padding modes are as follows:
-
NoPadding: No padding is applied. The input data must match the block length.
-
PKCS5: The padding characters consist of a byte sequence, and the value of each padded byte is the same as the length of the byte sequence to be padded. PKCS5 uses 8-byte padding, that is, the data must be padded to a multiple of eight bytes.
-
PKCS7: The padding method is the same as PKCS5. However, PKCS7 can pad any number of bytes between 1 and 255, while PKCS5 is fixed at 8 bytes.
For modes such as CFB, OFB, CTR, GCM, and CCM that convert block ciphers into stream mode implementations, no padding is required. Therefore, regardless of whether a padding mode is specified, they are implemented as NoPadding.
[h2]ChaCha20
Starting from API version 22, the algorithm library supports this algorithm.
The algorithm library currently provides ChaCha20 encryption and decryption. By default, an IV must be passed in for ChaCha20 encryption and decryption. The encryption and decryption parameter required by default ChaCha20 is IvParamsSpec.
Commonly used encryption mode: Poly1305. The encryption and decryption parameter applicable to the Poly1305 mode is Poly1305ParamsSpec.
Since ChaCha20 is a stream algorithm, no padding algorithm is required.
Currently, ChaCha20 encryption and decryption can be completed using a string parameter. The specific "string parameter" is formed by concatenating the "symmetric key type" and the "block mode" with the symbol "|", and is used to specify the algorithm specification when creating a symmetric encryption and decryption instance.
As shown in the table, only one item can be selected from each value range (that is, the content in []) to complete the string concatenation.
| Symmetric Algorithm Name | Key Length (bit) | String Parameter | API Version |
|---|---|---|---|
| ChaCha20 | 256 | ChaCha20 | 22+ |
| ChaCha20 | 256 | ChaCha20|Poly1305 | 22+ |
[h2]RC2
Starting from API version 26.0.0, the block cipher algorithm RC2 is supported, with a block length of 8 bytes and a key length ranging from 8 bits to 1024 bits, which must be a multiple of 8.
The algorithm library currently provides the following common block modes for RC2 encryption and decryption: ECB, CBC, OFB, and CFB. Different encryption modes apply to different encryption and decryption parameters. For details, see ParamsSpec.
Note:
For the ECB and CBC encryption modes, if the plaintext length is not an integer multiple of 8 bytes, a padding method must be used to fill it.
Currently, RC2 encryption and decryption can be completed using a string parameter. The specific "string parameter" is formed by concatenating the "symmetric key type", "block mode", and "padding mode" with the symbol "|". The string parameter is RC2.
The CBC, OFB, and CFB modes require an IV, which is 8 bytes in length. For details, see IvParamsSpec.
| Block 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+ |
[h2]RC4
Starting from API version 26.0.0, the stream cipher algorithm RC4 is supported, which requires no block or padding. The key length ranges from 8 bits to 4096 bits and must be a multiple of 8.
The algorithm library currently provides RC4 encryption and decryption. RC4 is a stream cipher mode and requires no block mode or padding mode.
RC4 encryption and decryption are currently supported with a string parameter, which is RC4:
| symmetric algorithm name | string parameter | API version |
|---|---|---|
| RC4 | RC4 | 26.0.0+ |
[h2]Blowfish (BF)
Starting from API version 26.0.0, the cryptographic algorithm Blowfish is supported. It is a block cipher algorithm with a block length of 8 bytes and a key length ranging from 32 to 448 bits, which must be a multiple of 8.
Note:
For the ECB and CBC encryption modes, if the plaintext length is not a multiple of 8 bytes, a padding method must be used to fill it.
The CBC, OFB, and CFB modes require an IV with a length of 8 bytes, corresponding to IvParamsSpec.
Currently, Blowfish encryption and decryption can be performed using a string parameter, where the string parameter is Blowfish:
| Block 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+ |
[h2]CAST
Starting from API version 26.0.0, the block cipher algorithm CAST is supported, with a block length of 8 bytes and a key length ranging from 40 to 128 bits, which must be a multiple of 8.
CAST is a block cipher algorithm with a block length of 8 bytes and a key length ranging from 40 to 128 bits, which must be a multiple of 8.
The algorithm library currently provides the following common block modes for CAST encryption and decryption: ECB, CBC, OFB, and CFB. Different encryption modes apply to different encryption and decryption parameters. For details, see ParamsSpec.
Note:
For the ECB and CBC encryption modes, if the plaintext length is not an integer multiple of 8 bytes, a padding method must be used to fill it.
Currently, CAST encryption and decryption can be completed using a string parameter, where the string parameter is CAST:
The CBC, OFB, and CFB modes require an IV, which is 8 bytes in length, corresponding to IvParamsSpec.
| Block 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+ |
Asymmetric Key Encryption/Decryption Algorithm Specifications
This chapter describes the algorithms supported by the system and their specifications.
The encryption modes supported by each algorithm are described in the specific specifications.
[h2]RSA
RSA is an asymmetric encryption algorithm. The length of the data to be encrypted must meet the fixed-length requirement. In actual applications, if the data volume cannot meet the fixed-length requirement, you can pad the data using different padding modes.
The algorithm library currently provides three commonly used modes for RSA encryption and decryption.
-
NoPadding: no padding is applied. The input data must be as long as the RSA key byte length, and the output data length is the same as the RSA key byte length.
-
PKCS1: the RSAES-PKCS1-V1_5 mode defined in RFC3447, corresponding to RSA_PKCS1_PADDING in OpenSSL.
During RSA computation, the source data D is converted into an Encryption block (EB). During encryption, the maximum input data length <= RSA key byte length - 11, and the output data length is the same as the RSA key byte length.
-
PKCS1_OAEP: the RSAES-OAEP mode defined in RFC3447, corresponding to RSA_PKCS1_OAEP_PADDING in OpenSSL.
This mode requires setting two digests (md and mgf1_md). During encryption, the input data length must be less than RSA key byte length - 2 * md digest byte length - 2, and the output data length is the same as the RSA key byte length.
In this mode, you can set the pSource byte stream to define the encoding input for OAEP padding and obtain the related parameters of PKCS1_OAEP.
Related parameters of PKCS1_OAEP Description md Digest algorithm. mgf Mask generation algorithm. Currently, only MGF1 is supported. mgf1_md Digest algorithm used in the MGF1 algorithm. pSource Byte stream used for encoding input. -
Take RSA2048|SHA256 as an example to illustrate the relationship between the input data length and the algorithm.
Padding Mode Maximum Input Data Length in Bytes Maximum Output Data Length in Bytes NoPadding 256 (RSA key length in bytes) 256 PKCS1 245 (RSA key length in bytes - 11) 256 PKCS1_OAEP 190 (RSA key length in bytes - 2 * md digest length in bytes - 2) 256
Note:
Using synchronous APIs to generate RSA2048, RSA3072, RSA4096, or RSA8192 asymmetric keys, or using a plaintext length exceeding 2048, increases the time consumed.
The system imposes a time limit on the main thread, and a long time consumed may cause a failure. It is recommended that you use asynchronous APIs or use multi-thread concurrency when generating large-size keys.
When the padding mode is NoPadding
Use a string parameter to perform RSA encryption and decryption. The string parameter is formed by concatenating the "asymmetric key type" and the "padding mode NoPadding" with the symbol "|", and is used to specify the algorithm specification when creating an asymmetric encryption and decryption instance.
| Asymmetric Key Type | String Parameter | API Version |
|---|---|---|
| RSA512 | RSA512|NoPadding | 9+ |
| RSA768 | RSA768|NoPadding | 9+ |
| RSA1024 | RSA1024|NoPadding | 9+ |
| RSA2048 | RSA2048|NoPadding | 9+ |
| RSA3072 | RSA3072|NoPadding | 9+ |
| RSA4096 | RSA4096|NoPadding | 9+ |
| RSA8192 | RSA8192|NoPadding | 9+ |
| RSA | RSA|NoPadding | 10+ |
As shown in the last row of the table, to be compatible with keys generated from key parameters, the RSA encryption and decryption parameters support a key type without a length, and the encryption and decryption operations depend on the actual input key length.
When the padding mode is PKCS1
Use a string parameter to perform RSA encryption and decryption. The specific "string parameter" is formed by concatenating the "asymmetric key type" and the "padding mode PKCS1" with the symbol "|", and is used to specify the algorithm specification when creating an asymmetric encryption and decryption instance.
| Asymmetric Key Type | String Parameter | API Version |
|---|---|---|
| RSA512 | RSA512|PKCS1 | 9+ |
| RSA768 | RSA768|PKCS1 | 9+ |
| RSA1024 | RSA1024|PKCS1 | 9+ |
| RSA2048 | RSA2048|PKCS1 | 9+ |
| RSA3072 | RSA3072|PKCS1 | 9+ |
| RSA4096 | RSA4096|PKCS1 | 9+ |
| RSA8192 | RSA8192|PKCS1 | 9+ |
| RSA | RSA|PKCS1 | 10+ |
As shown in the last row of the table, to be compatible with keys generated from key parameters, the RSA encryption/decryption parameter supports omitting the length when the key type is input. The encryption/decryption operation depends on the actual input key length.
Padding mode PKCS1_OAEP
RSA encryption/decryption is performed using a string parameter. The string parameter consists of the "asymmetric key type", "padding mode PKCS1_OAEP", digest, and mask digest, concatenated with the symbol "|". It is used to specify the algorithm specification when creating an asymmetric encryption/decryption instance.
As shown in the table, only one item can be selected from each value range (that is, the content in []) to complete the string concatenation.
For example, when an RSA key with the asymmetric key type RSA2048, padding mode PKCS1_OAEP, digest algorithm SHA256, and mask digest MGF1_SHA256 is required, its string parameter is "RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256".
| Asymmetric key type | Padding mode | Digest | Mask digest | API version |
|---|---|---|---|---|
| RSA512 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256] | 9+ |
| RSA512 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256] | 9+ |
| RSA512 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256] | 9+ |
| RSA768 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA768 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA768 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA768 | PKCS1_OAEP | SHA256 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384] | 9+ |
| RSA1024 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA1024 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA1024 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA1024 | PKCS1_OAEP | SHA256 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA1024 | PKCS1_OAEP | SHA384 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA2048 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA2048 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA2048 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA2048 | PKCS1_OAEP | SHA256 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA2048 | PKCS1_OAEP | SHA384 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA2048 | PKCS1_OAEP | SHA512 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA3072 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA3072 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA3072 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA3072 | PKCS1_OAEP | SHA256 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA3072 | PKCS1_OAEP | SHA384 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA3072 | PKCS1_OAEP | SHA512 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA4096 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA4096 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA4096 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA4096 | PKCS1_OAEP | SHA256 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA4096 | PKCS1_OAEP | SHA384 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA4096 | PKCS1_OAEP | SHA512 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA8192 | PKCS1_OAEP | MD5 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA8192 | PKCS1_OAEP | SHA1 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA8192 | PKCS1_OAEP | SHA224 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA8192 | PKCS1_OAEP | SHA256 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA8192 | PKCS1_OAEP | SHA384 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA8192 | PKCS1_OAEP | SHA512 | [MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] | 9+ |
| RSA | PKCS1_OAEP | Digest algorithm meeting the length requirement | MGF1_digest algorithm meeting the length requirement | 10+ |
As shown in the last row of the table, to be compatible with keys generated from key parameters, the RSA encryption/decryption parameter supports omitting the length when the key type is input. The encryption/decryption operation depends on the actual input key length.
Obtaining/setting parameters for the OAEP padding mode
Starting from API version 10, RSA supports obtaining and setting related parameters when the PKCS1_OAEP padding mode is used. "√" indicates that the parameter can be obtained or set.
| OAEP parameter | Enumerated Value | Obtain | Set |
|---|---|---|---|
| md | OAEP_MD_NAME_STR | √ | - |
| mgf | OAEP_MGF_NAME_STR | √ | - |
| mgf1_md | OAEP_MGF1_MD_STR | √ | - |
| pSource | OAEP_MGF1_PSRC_UINT8ARR | √ | √ |
[h2]SM2
SM2 is an asymmetric encryption algorithm, and the encrypted data length must meet the fixed length requirement. The algorithm library currently supports encrypting or decrypting data in the format defined by GM/T 0009-2012.
The result of SM2 asymmetric encryption consists of three parts: C1, C2, and C3. C1 is the elliptic curve point calculated from the generated random number, C2 is the ciphertext data, and C3 is the value calculated using the specified digest algorithm.
Currently, SM2 encryption and decryption can be completed using a string parameter. The specific "string parameter" is formed by concatenating the "asymmetric key type (encryption/decryption algorithm + key length)" and the "digest algorithm" with the symbol "|", and is used to specify the algorithm specification when creating an asymmetric encryption/decryption instance.
As shown in the table, only one item can be selected from each value range (i.e., the content in []) to complete the string concatenation. The SM2 algorithm and the key length are concatenated with the symbol "_".
For example, for an SM2 key with a key length of 256 bits and the MD5 digest algorithm, the string parameter is "SM2_256|MD5".
| Asymmetric Key Type | Digest Algorithm | API Version |
|---|---|---|
| SM2_256 | [MD5|SHA1|SHA224|SHA256|SHA384|SHA512|SM3] | 10+ |
| SM2 | [MD5|SHA1|SHA224|SHA256|SHA384|SHA512|SM3] | 10+ |
As shown in the last row of the table, to be compatible with keys generated from key parameters, the SM2 encryption/decryption parameter supports omitting the length when inputting the key type. The encryption/decryption operation depends on the actual input key length.
Obtaining SM2 Digest Algorithm Parameters
Starting from API version 11, obtaining the SM2 digest algorithm parameter is supported. "√" indicates that obtaining or setting this parameter is supported.
| SM2 encryption/decryption parameter | Enum value | Obtain | Set |
|---|---|---|---|
| md | SM2_MD_NAME_STR | √ | - |
Converting the SM2 Ciphertext Format
Starting from API version 12, SM2 format conversion is supported. The currently supported SM2 ciphertext format is the ASN.1 format defined by the Chinese cryptographic standard, in which the parameters are combined in the order C1C3C2.
Developers can specify SM2 ciphertext parameters and convert them into ciphertext in the ASN.1 format that complies with the Chinese cryptographic standard. Likewise, SM2 ciphertext parameters can be extracted from ciphertext in the ASN.1 format of the Chinese cryptographic standard, making it convenient to recombine them into SM2 ciphertext in other formats.
SM2 ciphertext parameters include:
-
xCoordinate: the x component, that is, C1_X.
-
yCoordinate: the y component, that is, C1_Y. xCoordinate and yCoordinate can be converted into C1.
-
cipherTextData: the ciphertext, that is, C2.
-
hashData: the hash value, that is, C3.
Currently, the mode for SM2 ciphertext format conversion can be specified using a string parameter, as shown in the following table. "√" indicates that the parameter can be obtained or set.
| SM2 Ciphertext Format Conversion Mode | Generate SM2 Ciphertext Based on Parameters | Obtain Parameters from SM2 Ciphertext |
|---|---|---|
| C1C3C2 | √ | √ |
Segmented Encryption and Decryption
During encryption and decryption, the algorithm library does not impose a size limit on the amount of data passed in a single call or cumulatively. However, when the amount of data passed in is large (for example, greater than 2 MB), you are advised to segment the data and perform segmented encryption and decryption to improve efficiency.
[h2]Symmetric Encryption and Decryption
Segmented encryption and decryption with a symmetric key is implemented by calling Cipher.update.
Developers can customize the amount of data passed in at a time (updateLength in the example) and call update multiple times to pass in data.
Currently, the maximum length supported for a single pass is INT_MAX (the maximum length of the Uint8Array type).
Developers should check whether the result of each update and doFinal is null, and when the result is not null, extract the data from it and concatenate it to form the complete ciphertext/plaintext.
Development example: Encryption and Decryption Using an AES Symmetric Key (GCM Mode)
Development example: Encryption and Decryption Using an SM4 Symmetric Key (GCM Mode)
[h2]Asymmetric Encryption and Decryption
Asymmetric encryption and decryption does not support the update operation. You only need to call Cipher.init and Cipher.doFinal to complete encryption and decryption.
Segmented encryption with an asymmetric key means that when the plaintext is larger than the data length supported by a single encryption operation (for the specific length, see Asymmetric Key Encryption and Decryption Algorithm Specifications), you need to split the data to be encrypted into data segments of appropriate length and perform the encryption operation on each data segment. That is, create a Cipher, and then call the Cipher.init and Cipher.doFinal APIs.
Strictly speaking, this is segmented encryption and decryption of data. In this case, the length of the data passed in a single operation is related to the length specified by the key specification.
- RSA: Different padding modes have different rules for the input data. Determine the length of the data passed in a single operation based on the RSA Algorithm Specifications.
Developers should check whether the result of each doFinal call is null, and when the result is not null, extract the data from it and concatenate the data to form the complete ciphertext/plaintext.
Development example: Segmented Encryption and Decryption with an RSA Asymmetric Key
[h2]FAQ
-
In segmented encryption and decryption, is the amount of data updated each time related to the encryption mode?
The amount of data updated each time is defined by the developer and is unrelated to the encryption mode.
Different encryption modes only affect the encryption and decryption parameters. Different encryption modes use different encryption and decryption parameters. For details, see ParamsSpec.