> This guide applies to JS development using OpenHarmony API version 9 and SDK version 3.2.7 or later.
> This guide applies to JS development using OpenHarmony API version 9 and SDK version 3.2.7 or later.
## Generating and Converting a Key
## Key Generation and Conversion
**When to Use**
### When to Use
Typical key generation operations involve the following:
Typical key generation operations involve the following:
1. Randomly create a key instance for subsequent encryption and decryption.
1. Randomly create a key object for subsequent encryption and decryption.
2. Convert external or stored binary data into a key instance for subsequent encryption and decryption.
2. Create a key object based on the specified key parameters for subsequent encryption and decryption.
3. Obtain the binary data of a key for storage or transmission.
3. Convert external or internal binary data into a key object for subsequent encryption and decryption.
> **NOTE**<br>The key instance can be a symmetric key instance (**SymKey**) or an asymmetric key pair instance (**KeyPair**). The **KeyPair** instance consists a public key (**PubKey**) and a private key (**PriKey**). For details about the relationship between keys, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
4. Obtain the binary data of a key object for storage or transmission.
5. Obtain the parameter properties of an asymmetric key object for storage or transmission.
> **NOTE**
>
> The key object can be a symmetric key object (**SymKey**) or an asymmetric key pair object (**KeyPair**). The **KeyPair** object consists a public key (**PubKey**) and a private key (**PriKey**). For details about the relationship between keys, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
**Available APIs**
### Available APIs
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
The table below describes the APIs used in this guide.
The following table describes the APIs used in typical key generation operations. For more information about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
|Instance|API|Description|
|Instance|API|Description|
|---|---|---|
|---|---|---|
|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|Creates an **AsyKeyGenerator** instance.|
|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|Creates an **AsyKeyGenerator** instance based on the asymmetric key pair specifications specified by **algName**.|
|cryptoFramework|createAsyKeyGeneratorBySpec(asyKeySpec: AsyKeySpec): AsyKeyGeneratorBySpec;|Creates an **AsyKeyGenerator** instance based on the asymmetric key specifications specified by the key parameter.|
|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|Creates a **SymKeyGenerator** instance.|
|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|Creates a **SymKeyGenerator** instance.|
|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\<KeyPair>) : void|Generates an asymmetric key pair randomly. This API uses an asynchronous callback to return the result.|
|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\<KeyPair>) : void|Generates an asymmetric key pair randomly. This API uses an asynchronous callback to return the result.|
|AsyKeyGenerator|generateKeyPair() : Promise\<KeyPair>|Generates an asymmetric key pair randomly. This API uses a promise to return the result.|
|AsyKeyGenerator|generateKeyPair() : Promise\<KeyPair>|Generates an asymmetric key pair randomly. This API uses a promise to return the result.|
...
@@ -36,17 +39,17 @@ The table below describes the APIs used in this guide.
...
@@ -36,17 +39,17 @@ The table below describes the APIs used in this guide.
| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair>| Converts binary data into a symmetric key. This API uses a promise to return the result.|
| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\<KeyPair>| Converts binary data into a symmetric key. This API uses a promise to return the result.|
| Key | getEncoded() : DataBlob; | Obtains the binary data of a key. (The child class instances of **Key** include **SymKey**, **PubKey**, and **PriKey**.)|
| Key | getEncoded() : DataBlob; | Obtains the binary data of a key. (The child class instances of **Key** include **SymKey**, **PubKey**, and **PriKey**.)|
**How to Develop**
### Randomly Generating an RSA Key Pair and Obtaining the Binary Data
Example 1: Randomly generate an asymmetric key pair and obtain its binary data.
Randomly generate an asymmetric key pair and obtain its binary data.
1. Create an **AsyKeyGenerator** instance.
1. Create an **AsyKeyGenerator** instance.
2. Randomly generate an asymmetric key pair using **AsyKeyGenerator**.
2. Randomly generate an asymmetric key pair using **AsyKeyGenerator**.
3. Obtain binary data of the key pair generated.
3. Obtain the binary data of the key pair generated.
The following sample code demonstrates how to randomly generate an RSA key (1024 bits and two primes) using promise-based APIs.
Example: Randomly generate an RSA key (1024 bits and two primes) in promise mode.
@@ -98,12 +103,14 @@ function testGenerateAesKey() {
...
@@ -98,12 +103,14 @@ function testGenerateAesKey() {
}
}
```
```
Example 3: Generate an asymmetric key pair from the binary RSA key data.
### Converting Binary Data into an RSA Key Pair
Generate an RSA asymmetric key pair from the binary data.
1. Obtain the binary data of the RSA public or private key. The public key must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format. The private key must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
1. Obtain the binary data of the RSA public or private key. The public key must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format. The private key must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
2. Create an **AsyKeyGenerator** instance and call**convertKey()** to convert the key binary data (data of the private or public key, or both) into a **KeyPair** instance.
2. Create an **AsyKeyGenerator** instance, and use**convertKey()** to convert the key binary data (data of the private or public key, or both) into a **KeyPair** instance.
> The public key material to be converted in **convertKey()** must be in the DER format complying with X.509 specifications, and the private key material must be in the DER format complying with PKCS #8 specifications.
> The public key binary data to be converted by **convertKey()** must be in the DER format complying with X.509 specifications, and the private key binary data must be in the DER format complying with PKCS #8 specifications.
Example 4: Generate an asymmetric key pair from the binary ECC key data.
### Converting Binary Data into an ECC Key Pair
Generate an ECC asymmetric key pair from the binary data.
1. Obtain the ECC binary key data and encapsulate it into a **DataBlob** instance.
1. Obtain the ECC binary key data and encapsulate it into a **DataBlob** instance.
2.Call **convertKey()** to convert the key binary data (data of the private or public key, or both) into a **KeyPair** instance.
2.Use **convertKey()** to convert the binary data (data of the private or public key, or both) into a **KeyPair** instance.
## Generating an Asymmetric Key Object and Obtaining Key Parameters
### When to Use
Typical key generation operations involve the following:
1. Create a key object based on the specified asymmetric key parameters for subsequent encryption and decryption.
2. Obtain the parameter properties of an asymmetric key object for storage or transmission.
> **NOTE**
>
> - Key parameters can be used to generate asymmetric keys from API version 10.
> - Asymmetric systems use a public key (**PubKey**) to encrypt data and a related private key (**PriKey**) to decrypt it. The public key and private key form a key pair (**KeyPair**). For details about asymmetric key parameters, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
### Available APIs
The following table describes the APIs used in typical key generation operations. For more information about the APIs, see [AsyKeyGeneratorBySpec](../reference/apis/js-apis-cryptoFramework.md#asykeygeneratorbyspec10).
|Instance|API|Description|
|---|---|---|
|AsyKeyGeneratorBySpec|generateKeyPair(callback: AsyncCallback<KeyPair>): void;|Generates a **KeyPair** instance based on the key parameters. This API uses an asynchronous callback to return the result.|
|AsyKeyGeneratorBySpec|generateKeyPair(): Promise<KeyPair>;|Generates a **KeyPair** instance based on the key parameters. This API uses a promise to return the result.|
|AsyKeyGeneratorBySpec|generatePriKey(callback: AsyncCallback<KeyPair>): void;|Generates a **PriKey** instance based on the key parameters. This API uses an asynchronous callback to return the result.|
|AsyKeyGeneratorBySpec|generatePriKey(): Promise<KeyPair>;|Generates a **PriKey** instance based on the key parameters. This API uses a promise to return the result.|
|AsyKeyGeneratorBySpec|generatePubKey(callback: AsyncCallback<KeyPair>): void;|Generates a **PubKey** instance based on the key parameters. This API uses an asynchronous callback to return the result.|
|AsyKeyGeneratorBySpec|generatePubKey(): Promise<KeyPair>;|Generates a **PubKey** instance based on the key parameters. This API uses a promise to return the result.|
| PriKey | getAsyKeySpec(itemType: AsyKeySpecItem): bigint \| string \| number; | Obtains the key specifications of a **PriKey** instance.|
| PubKey | getAsyKeySpec(itemType: AsyKeySpecItem): bigint \| string \| number; | Obtains the key specifications of a **PubKey** instance.|
### Generating an ECC Key Pair and Obtaining Key Specifications
Generate an ECC key pair based on parameters and obtain the key specifications.
1. Create an **AsyKeyGenerator** based on key parameters.
2. Use the **AsyKeyGenerator** to generate an asymmetric key pair based on the specified key parameters.
3. Obtain the key specifications of a key object.
Example: Generate an ECC key based on key parameters in promise mode.
// Construct the EccCommonSpec struct based on the key specifications. The EccCommonSpec struct defines the common parameters of the ECC private key and public key.
// Compare the RSA public key specifications with the expected values.
functioncompareRsaPubKeyBySpec(rsaKeySpec,n,e){
if(rsaKeySpec.params.n!=n){
returnfalse;
}
if(rsaKeySpec.pk!=e){
returnfalse;
}
returntrue;
}
// Generate an RSA public key based on the RSA public key specifications, obtain the key specifications, and compare the key specifications with the expected values.
Important data needs to be encrypted in data storage or transmission for security purposes. Typical encryption and decryption operations involve the following:
Important data needs to be encrypted in data storage or transmission for security purposes. Typical encryption and decryption operations involve the following:
1. Encrypt and decrypt data using a symmetric key.
1. Encrypt and decrypt data using a symmetric key.
2. Encrypt and decrypt data using an asymmetric key pair.
2. Encrypt and decrypt data using an asymmetric key pair.
3. Obtain and set the **CipherSpecItem** parameter when the PKCS1_OAEP padding mode is used in RSA.
> **NOTE**
>
> - From API version 10, [CipherSpecItem](../reference/apis/js-apis-cryptoFramework.md#cipherspecitem10) can be obtained and set when the PKCS1_OAEP padding mode is used in RSA.
> - From API version 10, the string parameter without the key length is supported in encryption and decryption.
### Available APIs
**Available APIs**
The following table describes the APIs used in the typical encryption and decryption operations. For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
> **NOTE**
>
> Due to complexity of cryptographic algorithms, the implementation varies depending on the key specifications and parameters you use, and cannot be enumerated by sample code. Before you start, understand the APIs to ensure correct use of these APIs.
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md). <br>Due to the complexity of cryptographic algorithms, the implementation varies depending on the specifications and parameters you use, and cannot be enumerated by sample code. Before you start, understand the APIs in the API reference to ensure correct use of these APIs.
The table below describes the APIs used in this guide.
|Instance|API|Description|
|Instance|API|Description|
|---|---|---|
|---|---|---|
|cryptoFramework|createCipher(transformation : string) : Cipher|Creates a **Cipher** instance.|
|cryptoFramework|createCipher(transformation : string) : Cipher|Creates a **Cipher** instance based on the algorithm specified by **transformation**.|
|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\<void>) : void|Sets a key and initializes the **Cipher** instance. This API uses an asynchronous callback to return the result.|
|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\<void>) : void|Initializes the **Cipher** instance. This API uses an asynchronous callback to return the result.|
|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\<void>|Sets a key and initializes the **Cipher** instance. This API uses a promise to return the result.|
|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\<void>|Initializes the **Cipher** instance. This API uses a promise to return the result.|
|Cipher|update(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void|Updates the data for encryption and decryption. This API uses an asynchronous callback to return the result.|
|Cipher|update(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void|Updates the data for encryption and decryption. This API uses an asynchronous callback to return the result.|
|Cipher|update(data : DataBlob) : Promise\<DataBlob>|Updates the data for encryption and decryption. This API uses a promise to return the result.|
|Cipher|update(data : DataBlob) : Promise\<DataBlob>|Updates the data for encryption and decryption. This API uses a promise to return the result.|
|Cipher|doFinal(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void|Finalizes the encryption or decryption. This API uses an asynchronous callback to return the result.|
|Cipher|doFinal(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void|Finalizes the encryption or decryption. This API uses an asynchronous callback to return the result.|
|Cipher|doFinal(data : DataBlob) : Promise\<DataBlob>|Finalizes the encryption or decryption. This API uses a promise to return the result.|
|Cipher|doFinal(data : DataBlob) : Promise\<DataBlob>|Finalizes the encryption or decryption. This API uses a promise to return the result.|
|Cipher|getCipherSpec(itemType: CipherSpecItem): string \| Uint8Array|Obtains cipher specifications. Currently, only the RSA is supported.|
|Cipher|setCipherSpec(itemType: CipherSpecItem, itemValue: Uint8Array): void|Sets cipher specifications. Currently, only the RSA is supported.|
**How to Develop**
### Encrypting and Decrypting Data Using AES GCM (Promise)
Example 1: Encrypt and decrypt data using a symmetric key.
Encrypt and decrypt data using an AES symmetric key.
1. Create a **SymKeyGenerator** instance.
1. Create a **SymKeyGenerator** instance.
2. Use the key generator to generate a symmetric key.
2. Use the **SymKeyGenerator** to randomly generate a symmetric key.
3. Create a **Cipher** instance.
3. Create a **Cipher** instance.
4. Encrypt or decrypt data.
4. Encrypt or decrypt data.
The following example demonstrates how to use the AES-GCM to encrypt and decrypt data with promise-based APIs.
The following example demonstrates how to use the the 3DES ECB to convert existing data into a key and encrypt and decrypt data using callback-based APIs.
### Encrypting and Decrypting Data Using a 3DES ECB Symmetric Key (Callback)
Encrypt and decrypt data using a 3DES symmetric key.
1. Create a **SymKeyGenerator** instance.
2. Generate a key based on the existing binary data.
3. Create a **Cipher** instance.
4. Encrypt or decrypt data using the **Cipher** instance.
@@ -825,21 +1100,138 @@ function encryptLongMessagePromise() {
...
@@ -825,21 +1100,138 @@ function encryptLongMessagePromise() {
> **NOTE**
> **NOTE**
>
>
> - In RSA encryption and decryption, **init()** cannot be repeatedly called to initialize the **Cipher** instance. You must create a **Cipher** instance for each encryption and decryption.
> - In RSA encryption and decryption, **init()** cannot be repeatedly called to initialize a **Cipher** instance. You must create a **Cipher** instance for each encryption and decryption.
> - The RSA encryption has a limit on the length of the plaintext to be encrypted. For details, see "Basic Concepts" in [Cryptographic Framework Overview](cryptoFramework-overview.md).
> - The RSA encryption has a limit on the length of the plaintext to be encrypted. For details, see [Encryption and Decryption](cryptoFramework-overview.md#encryption-and-decryption).
> - In RSA decryption, the length of the ciphertext to be decrypted each time is the number of bits of the RSA key divided by 8.
> - In RSA decryption, the length of the ciphertext to be decrypted each time is the number of bits of the RSA key divided by 8.
## Generating and Verifying a Signature
### Using PKCS1_OAEP in RSA Encryption and Decryption
Use the PKCS1_OAEP padding mode in RSA encryption and decryption in promise mode.
1. Generate an RSA key pair based on the key parameters.<br>Call **createAsyKeyGeneratorBySpec()** to create an **AsyKeyGeneratorBySpec** object and generate an RSA asymmetric key pair. (You can also use **createAsyKeyGenerator()** to randomly generate or convert an RSA key object.)
2. Create a **Cipher** instance.<br>Call **createCipher()** to create a cipher instance, initialize the cipher instance, set the key and encryption/decryption mode, use **setCipherSpec()** to set PKCS1_OAEP **pSource**, and use **update()** to pass in data.
3. Encrypt and decrypt data.<br>Call the **doFinal()** provided by the **Cipher** class to perform encryption or decryption. The **pSource** of the **Cipher** instance to be encrypted must be the same as that decrypted.
// The get() and set() operations can be performed before the init() operation of the Cipher object and are equivalent to those after the init() operation. For example, set and get the decoder.
A digital signature can be used to verify the authenticity of a message. Typical signing and signature verification operations involve the following:
A digital signature can be used to verify the authenticity of a message. Typical signing and signature verification operations involve the following:
- Use the RSA to generate and verify a signature.
1. Use RSA to generate a signature and verify the signature.
- Use the ECC to generate and verify a signature.
2. Use ECC to generate a signature and verify the signature.
3. Use RSA to generate a signature and verify the signature. Obtain and set **SignSpecItem** when the PSS padding mode is used.
> **NOTE**
>
> - From API version 10, [SignSpecItem](../reference/apis/js-apis-cryptoFramework.md#signspecitem10) can be set and obtained when the PSS padding mode is used.
> - From API version 10, the string parameter without the key length is supported in signature verification.
**Available APIs**
### Available APIs
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md). <br>Due to the complexity of cryptographic algorithms, the implementation varies depending on the specifications and parameters you use, and cannot be enumerated by sample code. Before you start, understand the APIs in the API reference to ensure correct use of these APIs.
The following table describes the APIs used in typical signing and signature verification operations. For more information about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
> **NOTE**
>
> Due to complexity of cryptographic algorithms, the implementation varies depending on the specifications and parameters you use, and cannot be enumerated by sample code. Before you start, understand the APIs to ensure correct use of these APIs.
|Instance|API|Description|
|Instance|API|Description|
|---|---|---|
|---|---|---|
...
@@ -850,32 +1242,38 @@ For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cry
...
@@ -850,32 +1242,38 @@ For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cry
|Sign|update(data : DataBlob) : Promise\<void>|Updates the data for signing. This API uses a promise to return the result.|
|Sign|update(data : DataBlob) : Promise\<void>|Updates the data for signing. This API uses a promise to return the result.|
|Sign|sign(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void|Signs the data. This API uses an asynchronous callback to return the result.|
|Sign|sign(data : DataBlob, callback : AsyncCallback\<DataBlob>) : void|Signs the data. This API uses an asynchronous callback to return the result.|
|Sign|sign(data : DataBlob) : Promise\<DataBlob>|Signs the data. This API uses a promise to return the result.|
|Sign|sign(data : DataBlob) : Promise\<DataBlob>|Signs the data. This API uses a promise to return the result.|
|Sign|getSignSpec(itemType: SignSpecItem): string \| number|Obtains the signing specifications. Currently, only the RSA is supported.|
|Sign|setSignSpec(itemType: SignSpecItem, itemValue: number): void|Sets signing specifications. Currently, only the RSA is supported.|
|cryptoFramework|function createVerify(algName : string) : Verify|Creates a **Verify** instance.|
|cryptoFramework|function createVerify(algName : string) : Verify|Creates a **Verify** instance.|
|Verify|init(priKey : PriKey, callback : AsyncCallback\<void>) : void|Sets a key and initializes the **Verify** instance. This API uses an asynchronous callback to return the result.|
|Verify|init(pubKey : PubKey, callback : AsyncCallback\<void>) : void|Sets a key and initializes the **Verify** instance. This API uses an asynchronous callback to return the result.|
|Verify|init(priKey : PriKey) : Promise\<void>|Sets a key and initializes the **Verify** instance. This API uses a promise to return the result.|
|Verify|init(pubKey : PubKey) : Promise\<void>|Sets a key and initializes the **Verify** instance. This API uses a promise to return the result.|
|Verify|update(data : DataBlob, callback : AsyncCallback\<void>) : void|Updates the data for signature verification. This API uses an asynchronous callback to return the result.|
|Verify|update(data : DataBlob, callback : AsyncCallback\<void>) : void|Updates the data for signature verification. This API uses an asynchronous callback to return the result.|
|Verify|update(data : DataBlob) : Promise\<void>|Updates the data for signature verification. This API uses a promise to return the result.|
|Verify|update(data : DataBlob) : Promise\<void>|Updates the data for signature verification. This API uses a promise to return the result.|
|Verify|verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\<boolean>) : void|Verifies the signature. This API uses an asynchronous callback to return the result.|
|Verify|verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\<boolean>) : void|Verifies a signature. This API uses an asynchronous callback to return the result.|
|Verify|verify(data : DataBlob, signatureData : DataBlob) : Promise\<boolean>|Verifies the signature. This API uses a promise to return the result.|
|Verify|verify(data : DataBlob, signatureData : DataBlob) : Promise\<boolean>|Verifies a signature. This API uses a promise to return the result.|
|Verify|getVerifySpec(itemType: SignSpecItem): string \| number|Obtains signature verification specifications. Currently, only the RSA is supported.|
|Verify|setVerifySpec(itemType: SignSpecItem, itemValue: number): void|Sets signature verification specifications. Currently, only the RSA is supported.|
**How to Develop**
### Signing and Signature Verification Using RSA
Use RSA to sign data and verify the signature.
Example 1: Use the RSA to generate and verify a signature.
1. Generate an RSA key pair.<br>Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an RSA asymmetric key pair.
1. Generate an RSA key pair.<br>Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an RSA asymmetric key pair.
2. Create a **Sign** instance.<br>Call **createSign()** to create a **Sign** instance, initialize the **Sign** instance, and set a private key for signing.
2. Create a **Sign** instance.<br>Call **createSign()** to create a **Sign** instance, initialize the **Sign** instance, and set a private key for signing.
3. Generate a signature.<br>Call **update()** provided by the **Sign** class to add the data for signing and call **sign()** to generate a signature.
3. Generate a signature.<br>Call **update()** provided by the **Sign** class to pass in the data for signing and call **sign()** to generate a signature.
4. Create a **Verify** instance.<br>Call **createVerify()** to create a **Verify** instance, initialize the instance, and set a public key for signature verification.
4. Create a **Verify** instance.<br>Call **createVerify()** to create a **Verify** instance, initialize the instance, and set a public key for signature verification.
5. Verify the signature.<br>Call **update()** provided by the **Verify** class to add signature data and call **verify()** to verify the signature.
5. Verify the signature.<br> Call **update()** provided by the **Verify** class to pass in the signature data and call **verify()** to verify the signature.
letsigner=cryptoFramework.createSign("RSA1024|PKCS1|SHA256");// From API version 10, a Sign instance can be created by specifying a string parameter defining the key specifications.
letkeyGenPromise=rsaGenerator.generateKeyPair();
letkeyGenPromise=rsaGenerator.generateKeyPair();
keyGenPromise.then(keyPair=>{
keyGenPromise.then(keyPair=>{
globalKeyPair=keyPair;
globalKeyPair=keyPair;
...
@@ -917,7 +1315,7 @@ function verifyMessagePromise() {
...
@@ -917,7 +1315,7 @@ function verifyMessagePromise() {
letsigner=cryptoFramework.createSign("RSA1024|PKCS1|SHA256");// From API version 10, a Sign instance can be created by specifying a string parameter defining the key specifications.
@@ -944,23 +1342,26 @@ function verifyMessageCallback() {
...
@@ -944,23 +1342,26 @@ function verifyMessageCallback() {
}
}
```
```
Example 2: Use the ECDSA to generate and verify a signature.
### Signing and Signature Verification Using ECDSA
Use the ECDSA to sign data and verify the signature.
1. Generate an ECC key.<br>Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an ECC asymmetric key pair.
1. Generate an ECC key.<br>Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an ECC asymmetric key pair.
2. Create a **Sign** instance.<br>Call **createSign()** to create a **Sign** instance, initialize the **Sign** instance, and set a private key for signing.
2. Create a **Sign** instance.<br>Call **createSign()** to create a **Sign** instance, initialize the **Sign** instance, and set a private key for signing.
3. Generate a signature.<br>Call **update()** provided by the **Sign** class to add the data for signing and call **doFinal()** to generate a signature.
3. Generate a signature.<br>Call **update()** provided by the **Sign** class to pass in the data for signing and call **doFinal()** to generate a signature.
4. Create a **Verify** instance.<br>Call **createVerify()** to create a **Verify** instance, initialize the instance, and set a public key for signature verification.
4. Create a **Verify** instance.<br>Call **createVerify()** to create a **Verify** instance, initialize the instance, and set a public key for signature verification.
5. Verify the signature.<br>Call **update()** provided by the **Verify** class to add signature data and call **doFinal()** to verify the signature.
5. Verify the signature.<br>Call **update()** provided by the **Verify** class to pass in the signature data and call **doFinal()** to verify the signature.
// Convert strings in plaintext into byte streams.
functionstringToUint8Array(str){
functionstringToUint8Array(str){
vararr=[];
letarr=[];
for(vari=0,j=str.length;i<j;++i){
for(leti=0,j=str.length;i<j;++i){
arr.push(str.charCodeAt(i));
arr.push(str.charCodeAt(i));
}
}
vartmpArray=newUint8Array(arr);
returnnewUint8Array(arr);
returntmpArray;
}
}
letglobalKeyPair;
letglobalKeyPair;
...
@@ -1028,17 +1429,27 @@ function verifyMessageCallback() {
...
@@ -1028,17 +1429,27 @@ function verifyMessageCallback() {
})
})
}
}
```
```
The following example demonstrates how to call **update()** multiple times to implement signing and signature verification.
```javascript
### Signing and Signature Verification Using RSA by Segment
Use RSA to sign data and verify the signature by segment.
1. Generate an RSA key pair.<br>Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an RSA asymmetric key pair.
2. Create a **Sign** instance.<br>Call **createSign()** to create a **Sign** instance, initialize the **Sign** instance, and set a private key for signing.
3. Generate a signature.<br>Call the **update()** provided by the **Sign** class multiple times to pass in data by segment and call **sign()** to generate a signature.
4. Create a **Verify** instance.<br>Call **createVerify()** to create a **Verify** instance, initialize the instance, and set a public key for signature verification.
5. Verify the signature.<br>Call the **update()** provided by the **Verify** class multiple times to pass in data by segment and call **verify()** to verify the signature.
// Convert strings in plaintext into byte streams.
functionstringToUint8Array(str){
functionstringToUint8Array(str){
vararr=[];
letarr=[];
for(vari=0,j=str.length;i<j;++i){
for(leti=0,j=str.length;i<j;++i){
arr.push(str.charCodeAt(i));
arr.push(str.charCodeAt(i));
}
}
vartmpArray=newUint8Array(arr);
returnnewUint8Array(arr);
returntmpArray;
}
}
functionsignLongMessagePromise(){
functionsignLongMessagePromise(){
...
@@ -1056,16 +1467,16 @@ function signLongMessagePromise() {
...
@@ -1056,16 +1467,16 @@ function signLongMessagePromise() {
letcipherAlgName="RSA1024|PKCS1|SHA256";
letcipherAlgName="RSA1024|PKCS1|SHA256";
letglobalKeyPair;
letglobalKeyPair;
letasyKeyGenerator=cryptoFramework.createAsyKeyGenerator(keyGenName);// Create an AsyKeyGenerator object.
letasyKeyGenerator=cryptoFramework.createAsyKeyGenerator(keyGenName);// Create an AsyKeyGenerator object.
letsigner=cryptoFramework.createSign(cipherAlgName);//Create a cipher object for encryption.
letsigner=cryptoFramework.createSign(cipherAlgName);//Create a Sign object for signing.
letverifier=cryptoFramework.createVerify(cipherAlgName);// Create a Decoder object for decryption.
letverifier=cryptoFramework.createVerify(cipherAlgName);// Create a Verify object for signature verification.
returnnewPromise((resolve,reject)=>{
returnnewPromise((resolve,reject)=>{
setTimeout(()=>{
setTimeout(()=>{
resolve("testRsaMultiUpdate");
resolve("testRsaMultiUpdate");
},10);
},10);
}).then(()=>{
}).then(()=>{
returnasyKeyGenerator.generateKeyPair();// Generate an RSA key.
returnasyKeyGenerator.generateKeyPair();// Generate an RSA key pair.
}).then(keyPair=>{
}).then(keyPair=>{
globalKeyPair=keyPair;// Save the key to global variables.
globalKeyPair=keyPair;// Save the key pair as a global variable.
returnsigner.init(globalKeyPair.priKey);
returnsigner.init(globalKeyPair.priKey);
}).then(async()=>{
}).then(async()=>{
// If the plaintext is too large, split the plaintext based on the specified length and cyclically call update() to pass in the plaintext.
// If the plaintext is too large, split the plaintext based on the specified length and cyclically call update() to pass in the plaintext.
...
@@ -1095,26 +1506,183 @@ function signLongMessagePromise() {
...
@@ -1095,26 +1506,183 @@ function signLongMessagePromise() {
}
}
```
```
## Generating a Digest
### Using PSS in RSA Signing and Signature Verification
**When to Use**
Use the PSS padding mode in RSA signing and signature verification in callback mode.
A message digest (MD) is a fixed size numeric representation of the content of a message, computed by a has function. It is sent with the message. The receiver can generate a digest for the message and compare it with the digest received. If the two digests are the same, the message integrity is verified.
1. Generate an RSA key pair based on the key parameters.<br>Call **createAsyKeyGeneratorBySpec** to create an **AsyKeyGeneratorBySpec** object and generate an RSA asymmetric key pair.
2. Create a **Sign** instance.<br>Call **createSign()** to create a **Sign** object, initialize the **Sign** object, set the private key for signing, and set and obtain PSS parameters.
3. Generate a signature.<br>Call **update()** provided by the **Sign** class to pass in the data for signing and call **sign()** to generate a signature.
4. Create a **Verify** instance.<br>Call **createVerify()** to create a **Verify** object, initialize the object, set the public key for signature verification, and set and obtain PSS parameters. The signature verification is successful if the salt length is the same.
5. Verify the signature.<br>Call **update()** provided by the **Verify** class to pass in the signature data and call **verify()** to verify the signature.
Key agreement allows two parties to establish a shared secret over an insecure channel.
> **NOTE**
>
> From API version 10, the string parameter without the key length is supported in key agreement.
### Available APIs
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
|Instance|API|Description|
|---|---|---|
|cryptoFramework|createKeyAgreement(algName : string) : KeyAgreement|Creates a **KeyAgreement** instance.|
|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\<DataBlob>) : void|Generates a shared secret. This API uses an asynchronous callback to return the result.|
|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\<DataBlob>|Generates a shared secret. This API uses a promise to return the result.|
### How to Develop
1. Generate an ECC key.<br>Call **createAsyKeyGenerator()** to create an **AsyKeyGenerator** instance and generate an ECC asymmetric key pair.
2. Generate a shared secret by using the private and public ECC keys.
A message digest (MD) is a fixed size numeric representation of the content of a message, computed by a hash function. It is sent with the message. The receiver can generate a digest for the message and compare it with the digest received. If the two digests are the same, the message integrity is verified.
Typical MD operations involve the following:
1. Create an **Md** instance with the specified digest algorithm (such as SHA-256).
2. Pass in one or more messages for generating a digest, and generate a digest.
3. Obtain the digest algorithm and digest length (in bytes).
### Available APIs
For more information about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
| cryptoFramework | function createMd(algName : string) : Md; | Creates an **Md** instance. |
| cryptoFramework | function createMd(algName : string) : Md; | Creates an **Md** instance with the specified algorithm. |
| Md | update(input : DataBlob, callback : AsyncCallback\<void>) : void; | Updates the data for a digest. This API uses an asynchronous callback to return the result.|
| Md | update(input : DataBlob, callback : AsyncCallback\<void>) : void; | Updates the data for a digest. This API uses an asynchronous callback to return the result.|
| Md | update(input : DataBlob) : Promise\<void>; | Updates the data for a digest. This API uses a promise to return the result. |
| Md | update(input : DataBlob) : Promise\<void>; | Updates the data for a digest. This API uses a promise to return the result. |
| Md | digest(callback : AsyncCallback\<DataBlob>) : void; | Generates the digest. This API uses an asynchronous callback to return the result. |
| Md | digest(callback : AsyncCallback\<DataBlob>) : void; | Generates the digest. This API uses an asynchronous callback to return the result. |
...
@@ -1122,226 +1690,155 @@ For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cry
...
@@ -1122,226 +1690,155 @@ For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cry
| Md | getMdLength() : number; | Obtains the digest length based on the specified digest algorithm. |
| Md | getMdLength() : number; | Obtains the digest length based on the specified digest algorithm. |
1.Call**createMd()** to create an **Md** instance.
1.Use**createMd()** to create an **Md** instance.
2.Call **update()** to pass in the data for computing a digest. **update()** can be called multiple times to pass in the data by segment.
2.Use **update()** to pass in data. **update()** can be called multiple times. The algorithm library does not limit the data length of a single **update()**.
3.Call**digest()** to compute a digest.
3.Use**digest()** to compute a digest.
4. Obtain the digest algorithm and length of the digest generated.
4. Obtain the digest algorithm and length of the digest generated.
Key agreement allows two parties to establish a shared secret over an insecure channel.
**Available APIs**
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
|Instance|API|Description|
|---|---|---|
|cryptoFramework|createKeyAgreement(algName : string) : KeyAgreement|Creates a **KeyAgreement** instance.|
|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\<DataBlob>) : void|Generates a shared secret. This API uses an asynchronous callback to return the result.|
|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\<DataBlob>|Generates a shared secret. This API uses a promise to return the result.|
**How to Develop**
1. Use **createKeyAgreement()** to create a **KeyAgreement** object for subsequent key agreement operations.
2. Use **generateSecret()** provided by **KeyAgreement** to pass in the peer ECC public key object and the ECC private key object generated locally.
| cryptoFramework | function createMac(algName : string) : Mac; | Creates a **Mac** instance. |
| cryptoFramework | function createMac(algName : string) : Mac; | Creates a **Mac** instance. |
| Mac | init(key : SymKey, callback : AsyncCallback\<void>) : void; | Initializes the MAC operation. This API uses an asynchronous callback to return the result.|
| Mac | init(key : SymKey, callback : AsyncCallback\<void>) : void; | Initializes the **Mac** instance. This API uses an asynchronous callback to return the result. |
| Mac | init(key : SymKey) : Promise\<void>; | Initializes the MAC operation. This API uses a promise to return the result. |
| Mac | init(key : SymKey) : Promise\<void>; | Initializes the **Mac** instance. This API uses a promise to return the result. |
| Mac | update(input : DataBlob, callback : AsyncCallback\<void>) : void; | Updates the data for the MAC operation. This API uses an asynchronous callback to return the result. |
| Mac | update(input : DataBlob, callback : AsyncCallback\<void>) : void; | Updates the data for the MAC operation. This API uses an asynchronous callback to return the result. |
| Mac | update(input : DataBlob) : Promise\<void>; | Updates the data for the MAC operation. This API uses a promise to return the result. |
| Mac | update(input : DataBlob) : Promise\<void>; | Updates the data for the MAC operation. This API uses a promise to return the result. |
| Mac | doFinal(callback : AsyncCallback\<DataBlob>) : void; | Finalizes the MAC operation to generate a MAC. This API uses an asynchronous callback to return the result. |
| Mac | doFinal(callback : AsyncCallback\<DataBlob>) : void; | Finalizes the MAC operation to generate a MAC. This API uses an asynchronous callback to return the result. |
...
@@ -1365,88 +1862,84 @@ For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cry
...
@@ -1365,88 +1862,84 @@ For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cry
| Mac | getMacLength() : number; | Obtains the length of the MAC based on the specified algorithm. |
| Mac | getMacLength() : number; | Obtains the length of the MAC based on the specified algorithm. |
| Mac | readonly algName : string; | Obtains the digest algorithm. |
| Mac | readonly algName : string; | Obtains the digest algorithm. |
**How to Develop**
### Generating an HMAC
1.Call**createMac()** to create a **Mac** instance.
1.Use**createMac()** to create a **Mac** instance.
2.Call**init()** to initialize the **Mac** instance with the symmetric key passed in.
2.Use**init()** to initialize the **Mac** instance with the symmetric key passed in.
3.Call **update()** one or more times to add the data for computing a MAC.
3.Use **update()** to pass in the data for computing an HMAC.
Typical random number operations involve the following:
Typical random number operations involve the following:
- Generate a random number.
1. Create a **Random** instance and specify the length (in bytes) of the random number to generate a secure random number of the specified length (ranging from **1** to **INT_MAX**).
- Set a seed based on the random number generated.
2. Set a seed based on the random number generated.
**Available APIs**
### Available APIs
For details about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
For more information about the APIs, see [Crypto Framework](../reference/apis/js-apis-cryptoFramework.md).
| cryptoFramework | function createRandom() : Random; | Creates a **Random** instance. |
| cryptoFramework | function createRandom() : Random; | Creates a **Random** instance. |
| Random | generateRandom(len : number, callback: AsyncCallback\<DataBlob>) : void; | Generates a random number. This API uses an asynchronous callback to return the result.|
| Random | generateRandom(len : number, callback: AsyncCallback\<DataBlob>) : void; | Generates a random number. This API uses an asynchronous callback to return the result.|
| Random | generateRandom(len : number) : Promise\<DataBlob>; | Generates a random number. This API uses a promise to return the result. |
| Random | generateRandom(len : number) : Promise\<DataBlob>; | Generates a random number. This API uses a promise to return the result. |
| Random | generateRandomSync(len: number): DataBlob; | Generates a random number of the specified length synchronously. |
| Random | setSeed(seed : DataBlob) : void; | Sets a seed. |
| Random | setSeed(seed : DataBlob) : void; | Sets a seed. |
**How to Develop**
### How to Develop
1.Call**createRandom()** to create a **Random** instance.
1.Use**createRandom()** to create a **Random** instance.
2.Call**generateRandom()** to generate a random number of the given length.
2.Use**generateRandom()** to generate a random number of the given length.
The cryptographic (crypto for shot) framework shields the implementation differences of third-party cryptographic algorithm libraries and implements encryption and decryption, signing and signature verification, and operations of the message authentication code (MAC), hashes, and secure random numbers. You can use the APIs provided by this framework to implement cipher development quickly.
The Cryptographic (Crypto for shot) Framework shields the implementation differences of third-party cryptographic algorithm libraries and implements encryption and decryption, digital signature and signature verification, message authentication code (MAC) generation, hashes, and generation of secure random numbers. You can use the APIs provided by this framework to implement cipher development quickly.
> **NOTE**
> **NOTE**
>
>
> The crypto framework provides cryptographic operations on keys, but not key management. It is used when the application keeps the key securely (for example, temporary session keys are used only in the memory or the application implements secure key storage). If the system is required to provide key management (such as key storage), use the [HUKS](huks-overview.md).
> The Crypto Framework provides cryptographic operations, but not key management. It can be used when temporary session keys are used only in the memory or the applications implement secure key storage. If the system is required to provide key management (such as key storage), use the [HUKS](huks-overview.md).
## Working Principles
## Working Principles
The crypto framework provides components in the following layers:
- Framework layer: loads plug-ins at the plug-in layer to adapt to third-party algorithm libraries and shield implementation differences between these libraries.
- Framework layer: flexibly loads plug-ins at the plug-in layer to adapt to third-party algorithm libraries and shield differences between these libraries.
## Basic Concepts
## Basic Concepts
**Symmetric Key**
### Symmetric Key
A symmetric key is a key used both to encrypt and decrypt data. In symmetric encryption, the sender converts information in plaintext into ciphertext using a key and certain algorithm for security purposes. The receiver converts the ciphertext into plaintext using the same key and algorithm.
A symmetric key is a key used both to encrypt and decrypt data. In symmetric encryption, the sender converts information in plaintext into ciphertext using a key and certain algorithm for security purposes. The receiver converts the ciphertext into plaintext using the same key and algorithm.
- AES
-**AES key**
Advanced Encryption Standard (AES) is the most common symmetric encryption algorithm. AES is a block cipher, which divides plaintext into fixed-length groups of bits, called blocks. A block is encrypted each time until the entire plaintext is encrypted. The block size in AES is 128 bits. That is, each block contains 16 bytes (8 bits/byte). The AES key length can be 128 bits, 192 bits, or 256 bits.
-**3DES key**
Triple Data Encryption Standard (3DES), also called 3DESede or Triple DES, applies the DES cipher three times to each data block. It uses three 64-bit keys to encrypt a data block three times. Compared with DES, 3DES provides higher security due to longer key length, but lower processing speed. AES is faster and more secure than 3DES.
### Asymmetric Key
In the asymmetric cryptography, a private and public key pair is required. The private key is used to encrypt the plaintext, and the public key is used to decrypt the ciphertext. The public key is public and open to anyone in the system, while the private key is private. For digital signature and signature verification, the private key is used to sign the plaintext, and the public key is used to verify the signature data.
-**RSA key**
Rivest-Shamir-Adleman (RSA) is an asymmetric encryption algorithm widely used for secure data transmission. The security of RSA depends on the practical difficulty of factoring the product of two large prime numbers.
The RSA key parameters include the following integers:
**n**: modulus, which is a public parameter of the private key and public key.
Advanced Encryption Standard (AES) is the most common symmetric encryption algorithm. AES is a block cipher. A block cipher divides plaintext into fixed-length groups of bits, called blocks. A block is encrypted each time until the entire plaintext is encrypted. The block size in AES is 128 bits. That is, each block contains 16 bytes (8 bits/byte). The key length can be 128 bits, 192 bits, or 256 bits.
**sk**: private exponent, which is often written as **d** in the formula.
- 3DES
Triple Data Encryption Standard (3DES), also called 3DESede or Triple DES, applies the DES cipher three times to each data block. It uses three 64-bit keys to encrypt a data block three times. Compared with DES, 3DES provides higher security due to longer key length, but its processing speed is lower. The AES is faster and more secure than 3DES.
**pk**: public exponent, which is often written as **e** in the formula.
**Asymmetric Key**
-**ECC key**
In the asymmetric cryptography, a private and public key pair is required. The private key is used to encrypt the plaintext, and the public key is used to decrypt the ciphertext. The public key is public and open to anyone in the system, while the private key is private. For signing and signature verification, the private key is used to sign the plaintext, and the public key is used to verify the signature data.
Elliptic-curve cryptography (ECC) is a public-key encryption algorithm based on elliptic curve mathematics. It security is based on the assumption that it is infeasible to find the discrete logarithm of a random elliptic curve element with respect to a publicly known base point. The Crypto Framework provides capabilities for generating a variety of ECC keys.
- RSA key
The ECC algorithm can be regarded as an operation of numbers defined in a special set. Currently, the Crypto Framework supports elliptic curves in **Fp** fields, where **p** is prime. The **Fp** fields are also called the prime fields.
The security of RSA relies on the factoring problem, that is, the difficulty of factoring the product of two large prime numbers. The keys for the RSA algorithm are generated as follows:
The ECC key parameters in the **Fp** fields include the following:
1. Generate two large prime numbers **p** and **q**.
**p**: prime number used to determine **Fp**.
2. Compute **n** = **p** x **q**.
**a**, **b**: determine the elliptic curve equation.
**n** is used as the modulus for both the public and private keys, and is released as part of the public key.
**g**: base point of the elliptic curve, which can be represented as **gx** or **gy**.
3. Choose an integer **e** such that 1 < **e** < (**p** - 1) x (**q** - 1), that is, **e** and (**p** - 1) x (**q** - 1) are coprime.
**n**: order of the base point **g**.
4. Compute **d**. **e** x **d** - 1 is a multiple of (**p** - 1) and (**q** - 1).
**h**: cofactor.
The public key consists of the modulus **n** and the public exponent **e**. The private key consists of **n** and the private exponent **d**.
**sk**: private key, which is a random integer less than **n**.
In addition to the default RSA key generation from two primes, the crypto framework provides key generation from multiple primes. You can set the **primes** parameter (PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5) to specify the number of primes during key generation. The keys generated from multiple primes help reduce the computation workload in decryption and signing (Chinese remainder theorem). However, such keys are weak. The algorithm library defines specifications based on the rules for using OpenSSL prime numbers. For details, see [**Constraints**](#constraints).
**pk**: public key, which is a point on the elliptic curve. **pk** = **sk** x **g**.
-ECC key
-**DSA key**
Elliptic-Curve Cryptography (ECC) is a public-key encryption based on the algebraic structure of elliptic curve over finite fields. The crypto framework provides a variety of ECC key generation capabilities.
Digital Signature Algorithm (DSA) is a public-key algorithm based on the modular exponentiation and discrete logarithm problem. It is used for digital signatures and signature verification, but not for encryption and decryption. The Crypto Framework provides the capability of generating DSA keys of different lengths.
**Encryption and Decryption**
The DSA key parameters include the following:
- Symmetric AES encryption and decryption
**p**: a prime modulus, whose length is an integer multiple of 64.
**q**: prime factor of p – 1. The length varies depending on the length of **p**.
**g**: g = (h ^ ((p - 1) / q)) mod p, where **h** is any integer that meets 1 < h < p -1.
**sk**: private key, which is a randomly generated integer and complies with 0 < sk < q.
**pk**: public key. pk = (g ^ sk) mod p
### Encryption and Decryption
-**Symmetric AES encryption and decryption**
The algorithm library provides the following cipher modes of operation for AES: ECB, CBC, OFB, CFB, CTR, GCM, and CCM. AES is a block cipher, with a fixed block size of 128 bits. In actual applications, the last block of plaintext may be less than 128 bits and needs to be padded. The padding options are as follows:
The algorithm library provides the following cipher modes of operation for AES: ECB, CBC, OFB, CFB, CTR, GCM, and CCM. AES is a block cipher, with a fixed block size of 128 bits. In actual applications, the last block of plaintext may be less than 128 bits and needs to be padded. The padding options are as follows:
-**NoPadding**: no padding.
-**NoPadding**: no padding.
-**PKCS5**: pads a block cipher with a block size of 8 bytes
-**PKCS5**: pads a block cipher with a block size of 8 bytes.
-**PKCS7**: The PKCS #7 padding scheme is the same as that of PKCS #5 padding except that PKCS #5 padding is defined for 8-byte block sizes, while PKCS #5 padding works for any block size from 1 to 255 bytes.
-**PKCS7**: pads any block size from 1 to 255 bytes. The PKCS #7 padding scheme is the same as that of PKCS #5.
> **NOTE**<br>In ECB and CBC, the plaintext must be padded if its length is not an integer multiple of 128 bits. Since the plaintext is padded to the block size, the PKCS #5 and PKCS #7 used in the algorithm library use the block size as the padding length. That is, data is padded to 16 bytes in AES encryption.
> **NOTE**
>
> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 128 bits.<br>
> Since the plaintext is padded to the block size, the PKCS #5 and PKCS #7 used in the algorithm library use the block size as the padding length. That is, data is padded to 16 bytes in AES encryption.
-**Symmetric 3DES Encryption and Decryption**
-**Symmetric 3DES encryption and decryption**
3DES encryption and decryption apply the DES cipher three times to each data block to obtain the ciphertext or plaintext.
3DES encryption and decryption apply the DES cipher three times to each data block to obtain the ciphertext or plaintext.
The algorithm library provides the following cipher modes of operation for 3DES encryption and decryption: ECB, CBC, OFB, and CFB. DES is a block cipher, with a fixed block size of 64 bits. In actual applications, the last block of plaintext may be less than 64 bits and needs to be padded. The padding options are as follows:
The algorithm library provides the following cipher modes of operation for 3DES encryption and decryption: ECB, CBC, OFB, and CFB. DES is a block cipher, with a fixed block size of 64 bits. In actual applications, the last block of plaintext may be less than 64 bits and needs to be padded. The padding options are as follows:
-**NoPadding**: no padding.
-**NoPadding**: no padding.
-**PKCS5**: pads a block cipher with a block size of 8 bytes
-**PKCS5**: pads a block cipher with a block size of 8 bytes.
-**PKCS7**: The PKCS #7 padding scheme is the same as that of PKCS #5 padding except that PKCS #5 padding is defined for 8-byte block sizes, while PKCS #5 padding works for any block size from 1 to 255 bytes.
-**PKCS7**: pads any block size from 1 to 255 bytes. The PKCS #7 padding scheme is the same as that of PKCS #5.
> **NOTE**<br>In ECB and CBC, the plaintext must be padded if its length is not an integer multiple of 64 bits. <br>Since the plaintext is padded to the block size, the PKCS #5 and PKCS #7 used in the algorithm library use the block size as the padding length. That is, data is padded to 8 bytes in 3DES encryption.
> **NOTE**
>
> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.
> Since the plaintext is padded to the block size, the PKCS #5 and PKCS #7 used in the algorithm library use the block size as the padding length. That is, data is padded to 8 bytes in 3DES encryption.
-**Asymmetric RSA Encryption and Decryption**
-**Asymmetric RSA encryption and decryption**
After the RSA public key (n, e) and private key (n, d) are held, the RSA encryption process is as follows:
RSA is a block cipher, with fixed-length blocks. In actual applications, diverse padding modes are used. Currently, the Crypto Framework provides the following padding modes:
-**NoPadding**: no padding. The length of the input or output data must be the same as that of the RSA key modulus.
Ciphertext = Plaintext ^ **e** mod **n**
-**PKCS1**: RSAES-PKCS1-V1_5 mode in RFC3447 (corresponding to RSA_PKCS1_PADDING in OpenSSL). The RSA converts the source data D into an encryption block (EB). In encryption, the length of the input data must be less than or equal to the RSA key modulus minus 11. The length of the output data is the same as that of the RSA key modulus.
The decryption process is as follows:
-**PKCS1_OAEP**: RSAES-OAEP mode in RFC 3447 (corresponding to RSA_PKCS1_OAEP_PADDING in OpenSSL). It is a new padding mode developed by PKCS#1. In this mode, two digests (**md** and **mgf1_md**) need to be set. During encryption, the length of the input data must meet the following requirements:
The algorithm library provides the following modes of operation for RSA encryption and decryption: **PKCS1**, **PKCS1_ OAEP**, and **NoPadding**. RSA is a block cipher, with fixed-length blocks. In actual applications, diverse padding modes are used. The padding options are as follows:
The length of the output data is the same as that of the RSA key modulus. In this mode, you can also set the **pSource** byte stream to define the encoding input **P** filled by OAEP and obtain the parameters related to PKCS1_OAEP.
-**NoPadding**: No padding is required. The length of the input or output data must be the same as that of the RSA key modulus.
The **PKCS1_OAEP** parameters include the following:
-**PKCS1**: PKCS #1 v1.5 is the default padding mode for RSA encryption and decryption. The length of the input data must be less than or equal to the RSA key modulus minus 11, and the length of the output data must be the same as that of the RSA key modulus.
**md**: message digest algorithm.<br>
-**PKCS1_OAEP**: The RSA_PKCS1_OAEP_PADDING is a new padding mode provided by PKCS #1. In this mode, two digests (**md** and **mgf1_md**) must be set. The length of the input data must be less than RSA key modulus length minus the **md** length, **mgf1_md** length, and two. The length of the output data must be the same as that of the RSA key modulus.
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<br>
**mgf1_md**: mgf1 digest algorithm.<br>
**pSource**: byte stream, which is the source for encoding input P in OAEP padding.
> **NOTE**
> **NOTE**
>
>
> Length of the RSA key modulus = (Number of RSA bits + 7)/8
> RSA key modulus = (RSA bits + 7)/8
**Signing and Signature Verification**
- RSA signing and signature verification
### Signing and Signature Verification
After the RSA public key (n, e) and private key (n, d) are held, the RSA signature is generated as follows:
-**RSA signing and signature verification**
Signature = Message ^ **d** mod **n**
The Crypto Framework provides the following padding modes for RSA signing and signature verification:
-**PKCS1**: RSASSA-PKCS1-V1_5 mode in RFC3447 (corresponding to RSA_PKCS1_PADDING in OpenSSL). When this mode is used for signing and signature verification, the digest (**md**) must be set, the digest algorithm output length (bytes) must be less than the RSA key modulus.
-**PSS**: RSASSA-PSS mode in RFC 3447 (corresponding to RSA_PKCS1_PSS_PADDING in OpenSSL). In this mode, two digests (**md** and **mgf1_md**) must be set, and the total length (bytes) of **md** and **mgf1_md** must be less than the RSA key modulus. In this mode, the salt length (**saltLen**, in bytes) can also be set, and PSS-related parameters can be obtained.<br>
The PSS parameters include the following:<br>
**md**: message digest algorithm.<br>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<br>
**mgf1_md**: digest algorithm used in the MGF1 algorithm.<br>
**saltLen**: salt length, in bytes.<br>
**trailer_field**: integer used for encoding. The value must be **1**.
The signature verification process is as follows:
> **NOTE**
>
> RSA key modulus = (RSA bits + 7)/8
Message = Signature ^ **d** mod **n**
-**ECDSA**
The sender sends the message and the signature signed by the private key. The receiver decrypts the signature using the public key to verify the signature. Generally, the message sent is longer than the RSA key modulus. Therefore, the crypto framework provides two padding modes to extract the hash value of the message digest before signing the message. The crypto framework provides the following padding modes for signing and signature verification:
The Elliptic Curve Digital Signature Algorithm (ECDSA) is a digital signature algorithm that uses the ECC. Compared with the ordinary Discrete Logarithm Problem (DLP) and Integer Factorization Problem (IFP), the ECC provides a higher unit bit strength than other public-key cryptographic systems. The Crypto Framework provides the ECDSA that combines multiple elliptic curves and digest algorithms.
-**PKCS1**: PKCS #1 v1.5 is the default padding mode for RSA encryption and decryption. When this mode is used, the digest (**md**) must be set.
-**DSA**
-**PSS**: The PSS mode is a padding algorithm based on the RSA algorithm. When it is used, the digest (**md**) and mask function (**mgf1_md**) are required.
- ECDSA
The DSA security is based on the difficulty of the DLP in integer finite field. The DSA features high compatibility and applicability.
The Elliptic Curve Digital Signature Algorithm (ECDSA) is a Digital Signature Algorithm (DSA) that uses the ECC. Compared with the ordinary Discrete Logarithm Problem (DLP) and Integer Factorization Problem (IFP), the ECC provides a higher unit bit strength than other public-key cryptographic systems. The crypto framework provides the ECDSA that combines multiple elliptic curve and digest algorithms.
### Key Agreement
**Key Agreement**
**ECDH**
-**ECDH**
Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared secret over an insecure channel. The Crypto Framework provides a variety of ECDH capabilities based on the open-source algorithm library.
Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared secret over an insecure channel. The crypto framework provides a variety of ECDH capabilities based on the open-source algorithm library.
### Message Digest
**Digest**
The message digest (MD) algorithm allows a fixed-length digest to be generated from data of arbitrary size by using the hash algorithm. It is used for sensitive information encryption because it is infeasible to invert or reverse the computation. The MD algorithm is also referred to as a hash algorithm or a one-way hash algorithm.
The message digest algorithm allows a fixed-length digest to be generated from data of arbitrary size by using the hash algorithm. It is used for sensitive information encryption because it is infeasible to invert or reverse the computation. The MD algorithm is also referred to as a hash algorithm or a one-way hash algorithm.
When the same digest algorithm is used, the generated digest (hash value) has the following features:
When the same digest algorithm is used, the generated digest (hash value) has the following features:
- The same message always results in the same hash value.
- The same message always results in the same hash value.
- The digest generated is of the fixed length no matter the length of messages. (The digest length is determined by the algorithm used).
- The digest generated is of the fixed length no matter the length of messages. (The digest length is determined by the algorithm used).
- It is almost impossible to find two different messages with the same hash value. (The probability still exists, depending on the length of the digest.)
- It is almost impossible to find two different messages with the same hash value. (The probability still exists, depending on the length of the digest.)
There are three types of message digest algorithms: MD, SHA, and MAC. For details, see **HMAC**.
There are three types of message digest algorithms: MD, SHA, and MAC. For details, see section "HMAC".
MD algorithms include MD2, MD4, and MD5.
MD algorithms include MD2, MD4, and MD5.
Major SHA algorithms include SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.
Major SHA algorithms include SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.
**HMAC**
### HMAC
Hash-based Message Authentication Code (HMAC) is a key-based message authentication code algorithm. HMAC provides authentication using a shared secret instead of using a digital signature. The MAC generated can be used to verify the integrity and authenticity of the message. The length of the MAC generated by HMAC is fixed. Compared with MAC, HMAC introduces the shared secret, which ensures data correctness.
Hash-based Message Authentication Code (HMAC) is a key-based message authentication code algorithm. It provides authentication using a shared secret instead of using a digital signature. The MAC generated can be used to verify the integrity and authenticity of the message. The length of the MAC generated by HMAC is fixed. Compared with MAC, HMAC introduces the shared secret, which ensures data correctness.
**Random Number**
### Random Number
Random numbers are mainly used to generate temporary session keys or keys in asymmetric encryption. They are generated by a hardware random number generator or software-based pseudo-random number generator. In encryption and decryption, a secure random number generator must feature randomness, unrepeatability, and unpredictability. The random numbers generated by the Cryptography Secure Random Number Generator (CSPRNG) meet the requirements of cryptography security pseudo-randomness.
Random numbers are mainly used to generate temporary session keys or keys in asymmetric encryption. They are generated by a hardware random number generator or software-based pseudo-random number generator. In encryption and decryption, a secure random number generator must feature randomness, unrepeatability, and unpredictability. The random numbers generated by the Cryptography Secure Random Number Generator (CSPRNG) meet the requirements of cryptography security pseudo-randomness.
- Internal state<br>A value in the random number generator memory. The same internal state produces the same sequence of the random number.
- Internal state<br>A value in the random number generator memory. The same internal state produces the same sequence of the random number.
- Seed<br>A number used to initialize the internal state of a pseudorandom number generator. The random number generator generates a series of random sequences based on the seeds.
- Seed<br>A number used to initialize the internal state of a pseudorandom number generator. The random number generator generates a series of random sequences based on the seeds.
## Constraints
## Constraints
- The crypto framework does not support concurrent operations of multiple threads.
- The Crypto Framework does not support concurrent operations of multiple threads.
- Currently, the algorithm library supports only OpenSSL.
- Currently, the algorithm library supports only OpenSSL.
- For a key generated based on key parameters, the bigint type must be a positive number in big-endian format.
- The Crypto Framework algorithm library provides common algorithms. Some algorithms and specifications, such as MD5, are not applicable to security scenarios. You need to select the proper algorithms as required.
### Key Generation Specifications
## Key Generation Specifications
**Symmetric Key Generation Specifications**
A key can be generated based on either of the following specifications:
- String parameter: provides the specifications of the key to be generated in the form of a string.
- Key parameters: constructs a key object using the specific cryptography information.
> As a combination of the symmetric key algorithm and the key length, the string parameter specifies the key specifications when a symmetric key generator is created.
> **NOTE**<br>**String Parameter** is a combination of **Symmetric Key Algorithm** and **Key Length**. It specifies the key specifications when a symmetric key generator is created.
### 3DES Key Generation Specifications
**Asymmetric Key Generation Specifications**
The 3DES key can be generated based on a string parameter.
|Asymmetric Key Type|Number of Primes|String Parameter|
> **NOTE**
>
> As a combination of the symmetric key algorithm and the key length, the string parameter specifies the key specifications when a symmetric key generator is created.
### RSA Key Generation Specifications
> **NOTE**
>
> The RSA keys can be generated based on key parameters from API version 10.
- The RSA key can be generated based on a string parameter.
|RSA Key Type|Number of Primes|String Parameter|
|---|---|---|
|---|---|---|
|RSA512|2|RSA512\|PRIMES_2|
|RSA512|2|RSA512\|PRIMES_2|
|RSA768|2|RSA768\|PRIMES_2|
|RSA768|2|RSA768\|PRIMES_2|
...
@@ -187,48 +256,154 @@ Random numbers are mainly used to generate temporary session keys or keys in asy
...
@@ -187,48 +256,154 @@ Random numbers are mainly used to generate temporary session keys or keys in asy
|RSA8192|4|RSA8192\|PRIMES_4|
|RSA8192|4|RSA8192\|PRIMES_4|
|RSA8192|5|RSA8192\|PRIMES_5|
|RSA8192|5|RSA8192\|PRIMES_5|
> **NOTE**<br>When an RSA asymmetric key is generated, the default prime number is 2, and **PRIMES_2** is optional.
> **NOTE**
>
> As a combination of the RSA key type and the number of primes, the string parameter specifies the key specifications when an asymmetric key generator is created.
>
> The default number of primes for generating the RSA asymmetric key is 2, and **PRIMES_2** can be omitted.
- The RSA key can also be generated based on key parameters. The following table lists the types of key parameters and cryptography specifications of each key parameter.
> The key parameters are used to specify the key specifications when an asymmetric key generator is created.
>
The preceding table describes the public and private key parameters supported by the Crypto Framework algorithm library for generating RSA keys.<br>**√** indicates that properties needs to be specified to construct the key parameter.<br>x indicates that the Crypto Framework currently does not support key generation based on this parameter.
|Asymmetric Key Algorithm|Key Length|
> **CAUTION**
|---|---|
>
|ECC|ECC224|
> - RSA does not support random key generation by specifying the public parameter (**n**).
|ECC|ECC256|
>
|ECC|ECC384|
> - RSA does not support generation of the private key by specifying private key parameters (**n**, **sk**).
|ECC|ECC521|
### ECC Key Generation Specifications
> **NOTE**
>
> The ECC key can be generated based on key parameters from API version 10.
- The ECC key can be generated based on a string parameter.
> As a combination of the asymmetric key algorithm and the key Length, the string parameter specifies the key specifications when an asymmetric key generator is created.
>
> Currently, only ECC Fp curves are supported.
- The ECC key can also be generated based on key parameters. The following table lists the types of key parameters and cryptography specifications of each key parameter.
> The key parameters specify the key specifications when an asymmetric key generator is created.
>
> The preceding table describes the public and private key parameters supported by the Crypto Framework algorithm library for generating ECC keys. √ indicates that properties need to be specified to construct the key parameter.
**Symmetric Encryption and Decryption**
> **CAUTION**
>
> - Currently, the ECC supports only the **Fp** fields. Therefore, **fieldType** has a fixed value of **Fp**. **fieldType** and **p** constitute the property **field**, which currently supports only [ECFieldFp](../reference/apis/js-apis-cryptoFramework.md#ecfieldfp10).
> - **g** and **pk** are points on the ECC curve and belong to the [Point](../reference/apis/js-apis-cryptoFramework.md#point10) type. You need to specify the X and Y coordinates.
- The following symmetric encryption algorithms are supported:
### DSA Key Generation Specifications
|Algorithm|Block Cipher Mode| String Parameter |
> **NOTE**
>
> From API version 10, the DSA algorithm is supported for key generation, signing, and signature verification.
- The DSA key can be generated based on a string parameter.
> As a combination of the asymmetric key algorithm and the key length, the string parameter specifies the key specifications when an asymmetric key generator is created.
- The DSA key can also be generated based on key parameters. The following table lists the types of key parameters and cryptography specifications of each key parameter.
> The key parameters specify the key specifications when an asymmetric key generator is created.
>
> The preceding table describes the public and private key parameters supported by the Crypto Framework algorithm library for generating DSA keys.
>
> **√** indicates that properties needs to be specified to construct the key parameter.<br>x indicates that the Crypto Framework currently does not support key generation based on this parameter.
> **CAUTION**
>
> - DSA does not support generation of the private key by specifying the private key parameters (**p**, **q**, **g**, **sk**).
> - When common parameters (**p**, **q**, **g**) are specified to generate a DSA key pair, the DSA key length must be at least 1024 bits.
## Encryption and Decryption Specifications
### Symmetric Encryption and Decryption
> **NOTE**
>
> The APIs support specifications without the key length for symmetric encryption and decryption from API version 10.
The following symmetric encryption algorithms are supported.
|Symmetric Encryption and Decryption Algorithm|Block Cipher Mode|String Parameter |
> - The options included in the square brackets ([]) are mutually exclusive.
> - The options included in the square brackets ([]) are mutually exclusive.
> - **String Parameter** is a combination of **Algorithm** (including the key length), **Block Cipher Mode**, and padding mode. It specifies the symmetric encryption/decryption algorithm specifications when a symmetric encryption/decryption instance is created.
> - As a combination of the algorithm (including the key length), block cipher mode, and padding mode, the string parameter specifies the symmetric encryption/decryption algorithm specifications when a symmetric encryption/decryption instance is created.
**Asymmetric RSA Encryption and Decryption**
### Asymmetric RSA Encryption and Decryption
> **NOTE**
>
> The APIs support specifications without the key length for asymmetric RSA encryption and decryption from API version 10.
The crypto framework provides three padding modes for RSA encryption/decryption: **NoPadding**, **PKCS1**, and **PKCS1_OAEP**.
The Crypto Framework provides three padding modes for RSA encryption/decryption: **NoPadding**, **PKCS1**, and **PKCS1_OAEP**.
-Parameters for **NoPadding**
-If **NoPadding** is used, the following parameters can be specified.
@@ -239,8 +414,14 @@ The crypto framework provides three padding modes for RSA encryption/decryption:
...
@@ -239,8 +414,14 @@ The crypto framework provides three padding modes for RSA encryption/decryption:
|RSA3072|NoPadding|RSA3072\|NoPadding|
|RSA3072|NoPadding|RSA3072\|NoPadding|
|RSA4096|NoPadding|RSA4096\|NoPadding|
|RSA4096|NoPadding|RSA4096\|NoPadding|
|RSA8192|NoPadding|RSA8192\|NoPadding|
|RSA8192|NoPadding|RSA8192\|NoPadding|
|RSA|NoPadding|RSA\|NoPadding|
- Parameters for **PKCS1**
> **NOTE**
>
> - As a combination of the asymmetric key type and the padding mode, the string parameter specifies the asymmetric encryption/decryption algorithm specifications when an asymmetric encryption/decryption instance is created.
> - The RSA key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The encryption/decryption operation varies depending on the actual key length.
- If **PKCS1** is used, the following parameters can be specified.
@@ -251,174 +432,277 @@ The crypto framework provides three padding modes for RSA encryption/decryption:
...
@@ -251,174 +432,277 @@ The crypto framework provides three padding modes for RSA encryption/decryption:
|RSA3072|PKCS1|RSA3072\|PKCS1|
|RSA3072|PKCS1|RSA3072\|PKCS1|
|RSA4096|PKCS1|RSA4096\|PKCS1|
|RSA4096|PKCS1|RSA4096\|PKCS1|
|RSA8192|PKCS1|RSA8192\|PKCS1|
|RSA8192|PKCS1|RSA8192\|PKCS1|
|RSA|PKCS1|RSA\|PKCS1|
> **NOTE**
>
> - As a combination of the asymmetric key type and the padding mode, the string parameter specifies the asymmetric encryption/decryption algorithm specifications when an asymmetric encryption/decryption instance is created.
> - The RSA key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The encryption/decryption operation varies depending on the actual key length.
- If **PKCS1_OAEP** is used, the following parameters can be specified.
|RSA|PKCS1_OAEP|Digest algorithm that meets the requirements for length|MGF1_ digest algorithm that meets the requirements for length|
- Parameters for **PKCS1_OAEP**
> **NOTE**
> **NOTE**
>
>
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - Combine the asymmetric key type, padding mode, digest, and mask digest, with a vertical bar (|) in between. For example, **RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256**.
> - As a combination of the asymmetric key type, padding mode, digest, and mask digest with a vertical bar (|) in between, the string parameter specifies the asymmetric encryption/decryption algorithm specifications when an asymmetric encryption/decryption instance is created. For example, **RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256**.
> - The RSA key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The encryption/decryption operation varies depending on the actual key length.
> - The input data must meet the following requirement:<br>Input data length < RSA key modulus - **md** length - **mgf1_md** length - 2<br>For example, if the RSA key is 512 bits, SHA-512 is not supported. For details about the definition of the RSA key modulus and digest length, see "Asymmetric RSA encryption and decryption" in [Encryption and Decryption](#encryption-and-decryption).
- If **PKCS1_OAEP** is used, you can obtain the [OAEP cipher parameter](../reference/apis/js-apis-cryptoFramework.md#cipherspecitem10) and set the encoding input P for OAEP padding.
> The preceding table presents the **Get()** and **Set()** capabilities for OAEP parameters supported by the Crypto Framework. **√** indicates that the parameter can be obtained or set.
|RSA|PKCS1|Digest algorithm that meets the requirements for length|RSA\|PKCS1\|Digest algorithm that meets the requirements for length|
- Parameters for **PSS**
> **NOTE**
> **NOTE**
>
>
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - Combine the asymmetric key type, padding mode, digest, and mask digest, with a vertical bar (|) in between. For example, **RSA2048|PSS|SHA256|MGF1_SHA256**.
> - The RSA key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The signing or signature verification operation varies depending on the actual key length.
> - During RSA signature verification, the output length of the digest algorithm must be less than the RSA key modulus. For example, if the RSA key is 512 bits, SHA-512 is not supported. For details, see "RSA signing and signature verification" in [Signing and Signature Verification](#signing-and-signature-verification).
|RSA|PSS|Digest algorithm that meets the requirements for length|MGF1_ digest algorithm that meets the requirements for length|
**ECDH**
> **NOTE**
>
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - As a combination of the asymmetric key type, padding mode, digest, and mask digest with a vertical bar (|) in between, the string parameter specifies the asymmetric signing or signature verification algorithm specifications when an asymmetric signing or signature verification instance is created. For example, **RSA2048|PSS|SHA256|MGF1_SHA256**.
> - The RSA key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The signing or signature verification operation varies depending on the actual key length.
> - If the PSS padding mode is used in RSA signing or signature verification, the total length (in bytes) of **md** and **mgf1_md** must be less than the RSA key modulus. For example, if the RSA key is 512 bits, **md** and **mgf1_md** cannot be SHA256 at the same time. For details about the definition of the RSA key modulus and digest length, see "RSA signing and signature verification" in [Signing and Signature Verification](#signing-and-signature-verification).
- If the PSS mode is used, you can obtain the PSS [parameter](../reference/apis/js-apis-cryptoFramework.md#signspecitem10) for signing or signature verification, and set the salt length (**saltLen**, in bytes) for the PSS.
| PSS Parameter|Enum Value| Get()| Set()|
|---|---|---|---|
|md|PSS_MD_NAME_STR |√|
|mgf|PSS_MGF_NAME_STR|√|
|mgf1_md|PSS_MGF1_MD_STR |√|
|saltLen|PSS_SALT_LEN_NUM|√|√|
|trailer_field|PSS_TRAILER_FIELD_NUM|√|
> **NOTE**
>
> The preceding table presents the **Get()** and **Set()** capabilities for PSS parameters supported by the Crypto Framework. **√** indicates that the parameter can be obtained or set.
### ECDSA Signing and Signature Verification
> **NOTE**
> The APIs support specifications without the key length for ECDSA signing and signature verification from API version 10.
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - As a combination of the asymmetric key type and digest with a vertical bar (|) in between, the string parameter specifies the asymmetric signing or signature verification algorithm specifications when an asymmetric signing or signature verification instance is created. For example, **ECC224|SHA256**.
> - The ECC key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The ECDSA signing or signature verification operation varies depending on the actual key length.
### DSA Signing and Signature Verification
> **NOTE**
>
> DSA signing and signature verification specifications are supported from API version 10.
> - The options included in the square brackets ([]) are mutually exclusive. The options outside the square brackets are fixed values.
> - As a combination of the asymmetric key type and digest with a vertical bar (|) in between, the string parameter specifies the asymmetric signing or signature verification algorithm specifications when an asymmetric signing or signature verification instance is created. For example, **DSA1024|SHA256**.
> - The DSA key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The signing or signature verification operation varies depending on the actual key length.
## Key Agreement Specifications
- The following ECDH parameters are supported:
### ECDH
|Asymmetric Key Algorithm|Supported Type|
> **NOTE**
>
> The APIs support specifications without the key length for ECDH from API version 10.
- The following ECDH parameters are supported.
|Asymmetric Key Algorithm|String Parameter|
|---|---|
|---|---|
|ECC|ECC224|
|ECC|ECC224|
|ECC|ECC256|
|ECC|ECC256|
|ECC|ECC384|
|ECC|ECC384|
|ECC|ECC521|
|ECC|ECC521|
|ECC|ECC|
### MD Algorithm Specifications
> **NOTE**
- The crypto framework supports the following MD algorithm parameters:
>
> - The string parameter specifies the key agreement algorithm specifications when a key agreement instance is created.
> - The ECC key type in the last row of the preceding table does not contain the key length to ensure compatibility with the key generated based on the key parameters. The ECDH key agreement operation varies depending on the actual key length.
|Digest Algorithm|Supported Type|
|---|---|
|HASH|SHA1|
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
|HASH|MD5|
### HMAC Algorithm Specifications
## MD Algorithm Specifications
- The crypto framework supports the following HMAC algorithm parameters:
|Digest Algorithm|Supported Type|
The Crypto Framework supports the following MD algorithm parameters.
|---|---|
|HASH|SHA1|
|Digest algorithm|Supported Type|
|HASH|SHA224|
|---|---|
|HASH|SHA256|
|HASH|SHA1|
|HASH|SHA384|
|HASH|SHA224|
|HASH|SHA512|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
|HASH|MD5|
> **NOTE**
>
> **Supported Type** specifies the MD algorithm specifications when an MD instance is created.
## HMAC Algorithm Specifications
The Crypto Framework supports the following HMAC algorithm parameters.
|Digest algorithm|Supported Type|
|---|---|
|HASH|SHA1|
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
> **NOTE**
>
> **Supported Type** specifies the HMAC algorithm specifications when an HMAC instance is created.
## Random Number
Currently, the Crypto Framework supports only the CTR_DRBG algorithm.
> **NOTE**
>
> - Currently, only secure random numbers with length of 1 to **INT_MAX** bytes are supported.
> - The random number generation algorithm uses the **RAND_priv_bytes** interface of OpenSSL to generate secure random numbers.
