| algName | string | Yes | Algorithm used to create the **symKeyGenerator** instance.<br>For details, see "String for Generating a Key" in [Key Generation Specifications] (../../security/cryptoFramework-overview.md#key-generation-specifications).|
| algName | string | Yes | Algorithm used to create the **symKeyGenerator** instance.<br>For details, see "String Parameter" in [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).|
**Return value**
**Return value**
...
@@ -1388,7 +1389,7 @@ Creates an **AsyKeyGenerator** instance based on the specified algorithm.
...
@@ -1388,7 +1389,7 @@ Creates an **AsyKeyGenerator** instance based on the specified algorithm.
| transformation | string | Yes | Combination of the algorithm name (including the key length), encryption mode, and padding algorithm of the **Cipher** instance to create.<br>For details about, see **Algorithm String** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications). |
| transformation | string | Yes | Combination of the algorithm name (including the key length), encryption mode, and padding algorithm of the **Cipher** instance to create.<br>For details, see **String Parameter** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).|
> **NOTE**
> **NOTE**
> 1. In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. **noPadding** indicates that no padding is performed. <br>You need to understand the differences between different block cipher modes and use the correct parameter specifications. For example, padding is required for ECB and CBC. Otherwise, ensure that the plaintext length is an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
> 1. In symmetric encryption and decryption, the implementation of PKCS #5 is the same as that of PKCS #7. PKCS #5 and PKCS #7 use the same padding length and block length. That is, data is padded with 8 bytes in 3DES and 16 bytes in AES. **noPadding** indicates that no padding is performed. <br>You need to understand the differences between different block cipher modes and use the correct parameter specifications. For example, padding is required for ECB and CBC. Otherwise, ensure that the plaintext length is an integer multiple of the block size. No padding is recommended for other modes. In this case, the ciphertext length is the same as the plaintext length.
...
@@ -1604,7 +1629,7 @@ A complete symmetric encryption/decryption process is slightly different from th
...
@@ -1604,7 +1629,7 @@ A complete symmetric encryption/decryption process is slightly different from th
Initializes a [cipher](#cipher) instance. This API uses an asynchronous callback to return the result. **init()**This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
Initializes a [cipher](#cipher) instance. This API uses an asynchronous callback to return the result. <br>This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
Initializes a [cipher](#cipher) instance. This API uses a promise to return the result. <br>**init()**This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
Initializes a [cipher](#cipher) instance. This API uses a promise to return the result. <br>This API can be used only after a [Cipher](#cipher) instance is created by using [createCipher](#cryptoframeworkcreatecipher).
(1) Encrypts or decrypts the remaining data (generated by the block ciper mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses a promise to return the encrypted or decrypted data. <br>If a small amount of data needs to be encrypted or decrypted, you can use **doFinal()** to pass in data without using **update()**. If all the data has been passed in by [update()](#update-4), you can pass in **null** in **data** of **doFinal()**. <br>The output of **doFinal()** varies with the symmetric encryption/decryption mode in use.
(1) Encrypts or decrypts the remaining data (generated by the block ciper mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses a promise to return the encrypted or decrypted data. <br>If a small amount of data needs to be encrypted or decrypted, you can use **doFinal()** to pass in data without using **update()**. If all the data has been passed in by [update()](#update-4), you can pass in **null** in **data** of **doFinal()**. <br>The output of **doFinal()** varies with the symmetric encryption/decryption mode in use.
- Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and **authTag** (the last 16 bytes for GCM and the last 12 bytes for CCM). If **null** is passed in by **data** of **doFinal()**, the result of **doFinal()** is **authTag**. **authTag** must be [GcmParamsSpec](#gcmparamsspec) or [CcmParamsSpec](#ccmparamsspec) used for decryption. The ciphertext is the **data** passed in for decryption.
- Symmetric encryption in GCM and CCM mode: The result consists of the ciphertext and **authTag** (the last 16 bytes for GCM and the last 12 bytes for CCM). If **null** is passed in by **data** of **doFinal()**, the result of **doFinal()** is **authTag**. <br>**authTag** must be [GcmParamsSpec](#gcmparamsspec) or [CcmParamsSpec](#ccmparamsspec) used for decryption. The ciphertext is the **data** passed in for decryption.
- Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.
- Symmetric encryption and decryption in other modes and symmetric decryption in GCM and CCM modes: The result is the complete plaintext/ciphertext.
(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses a promise to return the result. If a large amount of data needs to be encrypted/decrypted, call **doFinal()** multiple times and concatenate the result of each **doFinal()** to obtain the complete plaintext/ciphertext.
(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses a promise to return the result. If a large amount of data needs to be encrypted/decrypted, call **doFinal()** multiple times and concatenate the result of each **doFinal()** to obtain the complete plaintext/ciphertext.
...
@@ -2004,9 +2029,13 @@ let signer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256")
...
@@ -2004,9 +2029,13 @@ let signer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256")
## Sign
## Sign
Provides APIs for signing. Before using any API of the **Sign** class, you must create a **Sign** instance by using **createSign()**. The **Sign** class does not support repeated initialization. When a new key is used for signing, you must create a new **Sign** object and call **init()** for initialization.
Provides APIs for signing. Before using any API of the **Sign** class, you must create a **Sign** instance by using **createSign()**. The **Sign** class does not support repeated initialization. When a new key is used for signing, you must create a new **Sign** object and call **init()** for initialization.
The signing mode is determined in **createSign()**, and the key is set by **init()**.
The signing mode is determined in **createSign()**, and the key is set by **init()**.
If the data to be signed is short, you can call **sign()** to pass in the data for signing after **init()**.
If the data to be signed is short, you can call **sign()** to pass in the data for signing after **init()**.
If the data to be signed is long, you can use **update()** to pass in the data by segment, and then use **sign()** to sign the entire data.
If the data to be signed is long, you can use **update()** to pass in the data by segment, and then use **sign()** to sign the entire data.
If **update()** is used to pass in data by segment, **data** of **sign()** can be **null**.
If **update()** is used to pass in data by segment, **data** of **sign()** can be **null**.
### Attributes
### Attributes
...
@@ -2029,9 +2058,17 @@ Initializes a **Sign** instance using a private key. This API uses an asynchrono
...
@@ -2029,9 +2058,17 @@ Initializes a **Sign** instance using a private key. This API uses an asynchrono
| data | [DataBlob](#datablob) | Yes | Data to pass in.|
| callback | AsyncCallback\<DataBlob> | Yes | Callback invoked to return the result. |
| callback | AsyncCallback\<[DataBlob](#datablob) > | Yes | Callback invoked to return the result. |
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
### sign
### sign
...
@@ -2114,7 +2183,7 @@ Signs the data. This API uses a promise to return the result.
...
@@ -2114,7 +2183,7 @@ Signs the data. This API uses a promise to return the result.
| Name| Type | Mandatory| Description |
| Name| Type | Mandatory| Description |
| ------ | -------- | ---- | ---------- |
| ------ | -------- | ---- | ---------- |
| data | DataBlob | Yes | Data to pass in.|
| data | [DataBlob](#datablob) | Yes | Data to pass in.|
**Return value**
**Return value**
...
@@ -2122,6 +2191,14 @@ Signs the data. This API uses a promise to return the result.
...
@@ -2122,6 +2191,14 @@ Signs the data. This API uses a promise to return the result.
| -------------- | ----------- |
| -------------- | ----------- |
| Promise\<void> | Promise used to return the result.|
| Promise\<void> | Promise used to return the result.|
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
**Callback example**:
**Callback example**:
```javascript
```javascript
...
@@ -2138,7 +2215,7 @@ function stringToUint8Array(str) {
...
@@ -2138,7 +2215,7 @@ function stringToUint8Array(str) {
letglobalKeyPair;
letglobalKeyPair;
letSignMessageBlob;
letSignMessageBlob;
letplan1="This is Sign test plan1";// The first segment of the data.
letplan1="This is Sign test plan1";// First segment of the data.
letplan2="This is Sign test plan2";// The second segment of the data.
letplan2="This is Sign test plan2";// The second segment of the data.
letinput1={data:stringToUint8Array(plan1)};
letinput1={data:stringToUint8Array(plan1)};
letinput2={data:stringToUint8Array(plan2)};
letinput2={data:stringToUint8Array(plan2)};
...
@@ -2177,8 +2254,8 @@ function stringToUint8Array(str) {
...
@@ -2177,8 +2254,8 @@ function stringToUint8Array(str) {
letglobalKeyPair;
letglobalKeyPair;
letSignMessageBlob;
letSignMessageBlob;
letplan1="This is Sign test plan1";// The first segment of the data.
letplan1="This is Sign test plan1";// First segment of the data.
letplan2="This is Sign test plan2";// The second segment of the data.
letplan2="This is Sign test plan2";// Second segment of fata.
letinput1={data:stringToUint8Array(plan1)};
letinput1={data:stringToUint8Array(plan1)};
letinput2={data:stringToUint8Array(plan2)};
letinput2={data:stringToUint8Array(plan2)};
...
@@ -2235,10 +2312,15 @@ let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256")
...
@@ -2235,10 +2312,15 @@ let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256")
## Verify
## Verify
Provides APIs for signature verification. Before using any API of the **Verify** class, you must create a **Verify** instance by using **createVerify()**.
Provides APIs for signature verification. Before using any API of the **Verify** class, you must create a **Verify** instance by using **createVerify()**.
The **Verify** class does not support repeated initialization. When a new key is used for signature verification, you must create a new **Verify** object and call **init()** for initialization.
The **Verify** class does not support repeated initialization. When a new key is used for signature verification, you must create a new **Verify** object and call **init()** for initialization.
The signature verification mode is determined in **createVerify()**, and key is set by **init()**.
The signature verification mode is determined in **createVerify()**, and key is set by **init()**.
If the data to be verified is short, you can call **verify()** to pass in the signature data and original data after **init()**.
If the data to be verified is long, you can use **update()** to pass in the data by segment, and then use **verify()** to verify the entire data.
If the signature data to be verified is short, you can call **verify()** to pass in the signature data and original data after **init()**.
If the signature data to be verified is long, you can use **update()** to pass in the data by segment, and then use **verify()** to verify the entire data.
If **update()** is used to pass in data by segment, **data** of **verify()** can be **null**.
If **update()** is used to pass in data by segment, **data** of **verify()** can be **null**.
### Attributes
### Attributes
...
@@ -2263,9 +2345,17 @@ Initializes the **Verify** instance using a public key. This API uses an asynchr
...
@@ -2263,9 +2345,17 @@ Initializes the **Verify** instance using a public key. This API uses an asynchr
To protect sensitive data and eliminate security threads on core abilities, you can use the permissions in the [Application Permission List](permission-list.md) to protect the related API from unauthorized calling. Each time before the API is called, a permission verification is performed to check whether the caller has the required permission.
To protect sensitive data and eliminate security threats on core abilities, you can use the permissions in the [Application Permission List](permission-list.md) to protect the related API from unauthorized calling. Each time before the API is called, a permission verification is performed to check whether the caller has the required permission.
