| data | Uint8Array | Yes | Yes | Binary data array. |
## cryptoFramework.createMac
...
...
@@ -42,13 +43,15 @@ createMac(algName : string) : Mac
Creates a **Mac** instance for message authentication code (MAC) operations.
For details about the supported specifications, see [HMAC Algorithm Specifications](../../security/cryptoFramework-overview.md#hmac-algorithm-specifications).
| algName | string | Yes | Digest algorithm to use, which can be SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.|
| algName | string | Yes | Digest algorithm. For details about the supported algorithms, see [HMAC Algorithm Specifications](../../security/cryptoFramework-overview.md#hmac-algorithm-specifications). |
**Return value**
...
...
@@ -60,7 +63,7 @@ Creates a **Mac** instance for message authentication code (MAC) operations.
| ID| Error Message |
| -------- | ------------------ |
| 17620001 | memory error |
| 17620001 | memory error. |
**Example**
...
...
@@ -100,14 +103,14 @@ Initializes the MAC computation using a symmetric key. This API uses an asynchro
Updates the MAC computation data. This API uses an asynchronous callback to return the result.
> **NOTE**<br>
> For details about the sample code for calling **update()** multiple times, see [Generating a MAC](../../security/cryptoFramework-guidelines.md#generating-a-mac).
Updates the MAC computation data. This API uses a promise to return the result.
> **NOTE**<br>
> For details about the sample code for calling **update()** multiple times, see [Generating a MAC](../../security/cryptoFramework-guidelines.md#generating-a-mac).
Creates an **Md** instance for message digest operations.
For details about the supported specifications, see [MD Algorithm Specifications](../../security/cryptoFramework-overview.md#md-algorithm-specifications).
| algName | string | Yes | Digest algorithm to use, which can be SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, or MD5.|
| algName | string | Yes | Digest algorithm. For details about the supported algorithms, see [MD Algorithm Specifications](../../security/cryptoFramework-overview.md#md-algorithm-specifications). |
**Return value**
...
...
@@ -484,7 +495,7 @@ Creates an **Md** instance for message digest operations.
Updates the message digest data. This API uses an asynchronous callback to return the result.
> **NOTE**<br>
> For details about the sample code for calling **update()** multiple times, see [Generating a Digest](../../security/cryptoFramework-guidelines.md#generating-a-digest).
Updates the message digest data. This API uses a promise to return the result.
> **NOTE**<br>
> For details about the sample code for calling **update()** multiple times, see [Generating a Digest](../../security/cryptoFramework-guidelines.md#generating-a-digest).
Defines the parameters used for encryption and decryption. <br>For the symmetric encryption and decryption modes that require parameters such as the initialization vector (IV), you need to construct a child class object and pass it to [init()](#init-2). If the IV is not required (for example, the ECB mode), pass in **null** in [init()](#init-2).
Defines the parameters used for encryption and decryption.
For the symmetric encryption and decryption modes that require parameters such as the initialization vector (IV), you must construct a child class object and pass it to [init()](#init-2). If no IV is required (for example, the ECB mode is used), pass in **null** in [init()](#init-2).
| algoName | string | Yes | Yes | Symmetric encryption and decryption parameters. Options:<br>- **IvParamsSpec**: applicable to the CBC,|CTR,|OFB, |and CFB modes.<br>- **GcmParamsSpec**: applicable to the GCM mode.<br>- **CcmParamsSpec**: applicable to the CCM mode.|
| algName | string | Yes | Yes | Symmetric encryption and decryption parameters. Options:<br>- **IvParamsSpec**: applicable to the CBC, CTR, OFB, and CFB modes.<br>- **GcmParamsSpec**: applicable to the GCM mode.<br>- **CcmParamsSpec**: applicable to the CCM mode.|
> **NOTE**
> The **params** parameter in [init()](#init-2) is of the **ParamsSpec** type (parent class), while a child class object (such as **IvParamsSpec**) needs to be passed in. When constructing the child class object, you must set **algoName** for the parent class **ParamsSpec** to let the algorithm library know the child class object to pass in in **init()**.
> **NOTE**<br>
> The **params** parameter in [init()](#init-2) is of the **ParamsSpec** type (parent class), but a child class object (such as **IvParamsSpec**) needs to be passed in. When constructing the child class object, set **algName** for the parent class **ParamsSpec** to let the algorithm library know the type of child class object to pass in in **init()**.
## IvParamsSpec
Defines the child class of [ParamsSpec](#paramsspec). It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. <br>**IvParamsSpec** applies to the encryption and decryption modes such as CBC, CTR, OFB, and CFB, which use only the IV.
Defines the child class of [ParamsSpec](#paramsspec). It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption.
**IvParamsSpec** applies to the encryption and decryption modes such as CBC, CTR, OFB, and CFB, which use only the IV.
| iv | [DataBlob](#datablob) | Yes | Yes | IV for encryption and decryption. Options:<br>- AES CBC, |CTR, |OFB, |or CFB mode: 16-byte IV<br>- 3DES CBC,|OFB, or |CFB mode: 8-byte IV|
| iv | [DataBlob](#datablob) | Yes | Yes | IV for encryption and decryption. Options:<br>- AES CBC, CTR, OFB, or CFB mode: 16-byte IV<br>- 3DES CBC, OFB, or CFB mode: 8-byte IV|
> **NOTE**
> Before passing [init()](#init-2), specify **algoName** for its parent class [ParamsSpec](#paramsspec).
> **NOTE**<br>
> Before passing [init()](#init-2), specify **algName** for its parent class [ParamsSpec](#paramsspec).
## GcmParamsSpec
...
...
@@ -948,7 +969,7 @@ Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is use
| authTag | [DataBlob](#datablob) | Yes | Yes | Authentication tag, which is of 16 bytes.<br>When the GCM mode is used for encryption, [DataBlob](#datablob) output by [doFinal()](#dofinal-2) is required. The last 16 bytes of [DataBlob](#datablob) are used as as **authTag** in [GcmParamsSpec](#gcmparamsspec) of [init()](#init-2). |
> **NOTE**
> Before passing [init()](#init-2), specify **algoName** for its parent class [ParamsSpec](#paramsspec).
> Before passing [init()](#init-2), specify **algName** for its parent class [ParamsSpec](#paramsspec).
## CcmParamsSpec
...
...
@@ -959,11 +980,11 @@ Defines the child class of [ParamsSpec](#paramsspec) for the CCM mode. It is use
| iv | [DataBlob](#datablob) | Yes | Yes | IV, which is of 7 bytes. |
| aad | [DataBlob](#datablob) | Yes | Yes | AAD, which is of 8 bytes. |
| aad | [DataBlob](#datablob) | Yes | Yes | Additional authenticated data (AAD), which is of 8 bytes. |
| authTag | [DataBlob](#datablob) | Yes | Yes | Authentication tag, which is of 12 bytes.<br>When the CCM mode is used for encryption, [DataBlob](#datablob) output by [doFinal()](#dofinal-2) is required. The last 12 bytes of [DataBlob](#datablob) are used as as **authTag** in [CcmParamsSpec](#ccmparamsspec) of [init()](#init-2).|
> **NOTE**
> Before passing [init()](#init-2), specify **algoName** for its parent class [ParamsSpec](#paramsspec).
> Before passing [init()](#init-2), specify **algName** for its parent class [ParamsSpec](#paramsspec).
## CryptoMode
...
...
@@ -1154,6 +1175,10 @@ key.clearMem();
Defines an asymmetric key pair, which includes a public key and a private key. <br>Asymmetric key pairs can be generated by the **AsyKeyGenerator**.
> **NOTE**
>
> The **pubKey** and **priKey** objects in the **KeyPair** object exist as one parameter in the **KeyPair** object. When **KeyPair** leaves the scope, its internal objects may be destructed. <br>The service must reference the **KeyPair** object instead of the internal **pubKey** or **priKey** object.
Creates a **symKeyGenerator** instance based on the specified algorithm. <br>For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation-specifications).
Creates a **symKeyGenerator** instance based on the specified algorithm. <br>For details about the supported specifications, see [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 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**
...
...
@@ -1227,8 +1252,8 @@ Generates a key randomly. This API uses an asynchronous callback to return the r
Creates an **AsyKeyGenerator** instance based on the specified algorithm.
Creates an **AsyKeyGenerator** instance based on the specified algorithm.<br>For details about the supported specifications, see [Key Generation Specifications](../../security/cryptoFramework-overview.md#key-generation- specifications).
- After **getEncoded()** is called for the asymmetric public and private keys (RSA and ECC), binary data in X.509 format and binary data in PKCS #8 format are returned, respectively. The data can be used for cross-application transfer or persistent storage.
- The public key returned by **convertKey()** must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format, and the private key must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
- In **convertKey()**, you can pass in either **pubKey** or **priKey**, or both of them. If one of them is passed in, the returned **KeyPair** instance contains only the key converted from the data you passed in.
1. After **getEncoded()** is called for the asymmetric public and private keys (RSA and ECC), binary data in X.509 format and binary data in PKCS #8 format are returned, respectively. The data can be used for cross-application transfer or persistent storage.
2. The public key returned by **convertKey()** must comply with the ASN.1 syntax, X.509 specifications, and DER encoding format, and the private key must comply with the ASN.1 syntax, PKCS #8 specifications, and DER encoding format.
3. In **convertKey()**, you can pass in either **pubKey** or **priKey**, or both of them. If one of them is passed in, the returned **KeyPair** instance contains only the key converted from the data you passed in.
## cryptoFramework.createCipher
...
...
@@ -1555,7 +1604,7 @@ Creates a [Cipher](#cipher) instance based on the specified algorithm. <br>For d
| 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 about, see **Algorithm String** in [Encryption and Decryption Specifications](../../security/cryptoFramework-overview.md#encryption-and-decryption-specifications).|
> **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.
...
...
@@ -1572,10 +1621,10 @@ Creates a [Cipher](#cipher) instance based on the specified algorithm. <br>For d
Updates the data to encrypt or decrypt by segment. This API uses an asynchronous callback to return the encrypted or decrypted data. <br>This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
> **NOTE**
> - If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. The reason is the block mode and the related specifications affect the **update()** and [doFinal()](#dofinal-2) results. <br>For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. <br>That is, encrypted/decrypted data is returned as long as the data passed in by **update()** reaches the size of a block. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. <br>When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. <br>For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
> - **update()** may be called multiple times or may not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt. <br>The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment.
> - RSA asymmetric encryption and decryption do not support **update()**.
> 1. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. The reason is the block mode and the related specifications affect the **update()** and [doFinal()](#dofinal-2) results. <br>For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. <br>That is, encrypted/decrypted data is returned as long as the data passed in by **update()** reaches the size of a block. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. <br>When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. <br>For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
> 2. **update()** may be called multiple times or may not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt. <br>The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment. <br>For details about the sample code for calling **update()** multiple times in AES, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
> 3. RSA asymmetric encryption and decryption do not support **update()**.
Updates the data to encrypt or decrypt by segment. This API uses a promise to return the encrypted or decrypted data. <br>This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
> **NOTE**
> - If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. The reason is the block mode and the related specifications affect the **update()** and [doFinal()](#dofinal-2) results. <br>For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encryption/decryption block result generated by this **update()** is output. That is, encrypted/decrypted data is returned as long as the data passed in by **update()** reaches the size of a block. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. <br>When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. <br>For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
> - **update()** may be called multiple times or may not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt. <br>The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment.
> - RSA asymmetric encryption and decryption do not support **update()**.
> 1. If you are not familiar with the block modes for symmetric encryption and decryption, add a judgment to determine whether the result of each **update()** and **doFinal()** is null. If the result is not null, obtain the data to concatenate the complete ciphertext or plaintext. The reason is the block mode and the related specifications affect the **update()** and [doFinal()](#dofinal-2) results. <br>For example, in ECB and CBC modes, data is encrypted or decrypted by block no matter whether the data passed in by **update()** is an integer multiple of the block length, and the encrypted/decrypted block data generated by this **update()** is output. <br>That is, encrypted/decrypted data is returned as long as the data passed in by **update()** reaches the size of a block. Otherwise, **null** is returned and the data will be retained until a block is formed in the next **update()**/**doFinal()**. <br>When **doFinal()** is called, the data that has not been encrypted or decrypted will be padded based on the padding mode set in [createCipher](#cryptoframeworkcreatecipher) to an integer multiple of the block length, and then encrypted or decrypted. <br>For a mode in which a block cipher can be converted into a stream cipher, the length of the ciphertext may be the same as that of the plaintext.
> 2. **update()** may be called multiple times or may not be called ([doFinal()](#dofinal-2) is called after [init](#init-2)), depending on the size of the data to encrypt or decrypt. <br>The algorithm library does not set a limit on the amount of data that can be passed in by **updated()** (once or accumulatively). For symmetric encryption and decryption of a large amount of data, you are advised to call **update()** multiple times to pass in the data by segment. For details about the sample code for calling **update()** multiple times in AES, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
> 3. RSA asymmetric encryption and decryption do not support **update()**.
(2) Encrypts or decrypts the input data for RSA asymmetric encryption/decryption. This API uses an asynchronous callback 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.
> **NOTE**
> - In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. <br>For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
> - If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
> 1. In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. <br>For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
> 2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
> 3. The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
> 4. For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
(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.
(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.
> **NOTE**
> - In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. <br>For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
> - If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
> 1. In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. <br>For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
> 2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
> 3. The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
> 4. For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encrypting-and-decrypting-data).
Creates a **Sign** instance.<br>For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
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()**.
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 **update()** is used to pass in data by segment, **data** of **sign()** can be **null**.
### Attributes
...
...
@@ -2021,7 +2078,7 @@ If **update()** is used to pass in data by segment, **data** of **sign()** can b
Initializes a **Sign**instance using a private key. This API uses an asynchronous callback to return the result. The **Sign** class does not support repeated calling of **init()**.
Initializes a **Sign**object using a private key. This API uses an asynchronous callback to return the result. The **Sign** class does not support repeated calling of **init()**.
| priKey | PriKey | Yes | Private key used for the initialization.|
| priKey | [PriKey](#prikey) | Yes | Private key used for the initialization.|
| callback | AsyncCallback\<void> | Yes | Callback invoked to return the result. |
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
### init
init(priKey : PriKey) : Promise\<void>
Initializes a **Sign**instance using a private key. This API uses a promise to return the result. The **Sign** class does not support repeated calling of **init()**.
Initializes a **Sign**object using a private key. This API uses a promise to return the result. The **Sign** class does not support repeated calling of **init()**.
Updates the data to be signed. This API uses an asynchronous callback to return the result.
> **NOTE**
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
| data | [DataBlob](#datablob)| Yes | Data to pass in.|
| callback | AsyncCallback\<void> | Yes | Callback invoked to return the result. |
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
### update
update(data : DataBlob) : Promise\<void>;
Updates the data to be signed. This API uses a promise to return the result.
> **NOTE**
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
@@ -2177,8 +2286,8 @@ function stringToUint8Array(str) {
letglobalKeyPair;
letSignMessageBlob;
letplan1="This is Sign test plan1";// The first segment of the data.
letplan2="This is Sign test plan2";// The second segment of the data.
letplan1="This is Sign test plan1";// The first segment of data.
letplan2="This is Sign test plan2";// The second segment of fata.
letinput1={data:stringToUint8Array(plan1)};
letinput2={data:stringToUint8Array(plan2)};
...
...
@@ -2191,9 +2300,9 @@ function signMessagePromise() {
letpriKey=globalKeyPair.priKey;
returnsigner.init(priKey);
}).then(()=>{
returnsigner.update(input1);// Add the first segment of the data.
returnsigner.update(input1);// add first segment of data
}).then(()=>{
returnsigner.sign(input2);// Add the second segment of the data, and sign input1 and input2.
returnsigner.sign(input2);// add second segment of data, sign input1 and input2
}).then(dataBlob=>{
SignMessageBlob=dataBlob;
console.info("sign output is "+SignMessageBlob.data);
...
...
@@ -2206,7 +2315,7 @@ function signMessagePromise() {
createVerify(algName : string) : Verify
Creates a **Verify** instance.
Creates a **Verify** instance. For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
@@ -2235,10 +2344,15 @@ let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256")
## Verify
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 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**.
### Attributes
...
...
@@ -2263,9 +2377,17 @@ Initializes the **Verify** instance using a public key. This API uses an asynchr
Updates the data for signature verification. This API uses an asynchronous callback to return the result.
> **NOTE**
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
| data | [DataBlob](#datablob)| Yes | Data to pass in.|
| callback | AsyncCallback\<void> | Yes | Callback invoked to return the result. |
**Error codes**
| ID| Error Message |
| -------- | ---------------------- |
| 17620001 | memory error. |
| 17620002 | runtime error. |
| 17630001 | crypto operation error. |
### update
update(data : DataBlob) : Promise\<void>;
Updates the data for signature verification. This API uses a promise to return the result.
> **NOTE**
> For details about the sample code for calling **update()** multiple times, see [Signing Data and Verifying Signatures](../../security/cryptoFramework-guidelines.md#signing-data-and-verifying-signatures).
Creates a **KeyAgreement** instance.<br>For details about the supported specifications, see "Key Agreement Specifications" (../../security/cryptoFramework-overview.md#key-agreement-specifications).
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, message authentication code (MAC), hashes, and secure random numbers. You can use the APIs provided by this framework to implement cipher development quickly.
> **NOTE**
>
> The crypto framework provides cryptographic operations on keys, but not key management. It is used when the application keeps the key (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).
## Working Principles
The crypto framework provides components in the following layers:
-Framework layer: flexibly loads the plugins in the plugin layer to adapt to third-party algorithm libraries and shields the implementation differences between these libraries.
-Plug-in layer: loads plug-ins at the plug-in layer to adapt to third-party algorithm libraries and shield implementation differences between these libraries.
## Basic Concepts
**Symmetric Key**
...
...
@@ -25,7 +30,7 @@ In the asymmetric cryptography, a private and public key pair is required. The p
- RSA key
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 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:<br>
1. Generate two large prime numbers **p** and **q**.
...
...
@@ -35,9 +40,8 @@ In the asymmetric cryptography, a private and public key pair is required. The p
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.
4.Compute **d**.
4. Compute **d**.<br>**e** x **d** - 1 is a multiple of (**p** - 1) and (**q** - 1).
**e** x **d** - 1 is a multiple of (**p** - 1) and (**q** - 1).
The public key consists of the modulus **n** and the public exponent **e**. The private key consists of **n** and the private exponent **d**.
...
...
@@ -53,40 +57,40 @@ In the asymmetric cryptography, a private and public key pair is required. The p
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.
-**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.
> **NOTE**
>
> In ECB and CBC, 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
> **NOTE**<br>In ECB and CBC, 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**
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:
-**NoPadding**: no padding.
-**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.
> **NOTE**
>
> 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.
-**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.
- 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:
Ciphertext = Plaintext ^ **e** mod **n**
> **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.
The decryption process is as follows:
-**Asymmetric RSA Encryption and Decryption**
Plaintext = Ciphertext ^ **d** mod **n**
After the RSA public key (n, e) and private key (n, d) are held, the RSA encryption process is as follows:<br>Ciphertext = Plaintext ^ **e** mod **n**<br>The decryption process is as follows:<br>Plaintext = Ciphertext ^ **d** mod **n**
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:
-**NoPadding**: No padding is required. The length of the input or output data must be the same as that of the RSA key modulus.
-**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.
-**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.
> **NOTE**
...
...
@@ -97,13 +101,7 @@ In the asymmetric cryptography, a private and public key pair is required. The p
- RSA 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:
Signature = Message ^ **d** mod **n**
The signature verification process is as follows:
Message = Signature ^ **d** mod **n**
After the RSA public key (n, e) and private key (n, d) are held, the RSA signature is generated as follows:<br>Signature = Message ^ **d** mod **n**<br>The signature verification process is as follows:<br> Message = Signature ^ **d** mod **n**
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:
...
...
@@ -129,8 +127,10 @@ When the same digest algorithm is used, the generated digest (hash value) has th
- 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.)
There are three types of message digest algorithms: MD, SHA, and MAC. For details, see section **HMAC**.
There are three types of message digest algorithms: MD, SHA, and MAC. For details, see **HMAC**.
MD algorithms include MD2, MD4, and MD5.
Major SHA algorithms include SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512.
**HMAC**
...
...
@@ -141,63 +141,54 @@ Hash-based Message Authentication Code (HMAC) is a key-based message authenticat
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
A value in the random number generator memory. The same internal state produces the same sequence of the random number.
- Seed
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.
- 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.
## 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.
> **String Parameter** is a combination of **Symmetric Key Algorithm** and **Key Length**. It 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.
**Asymmetric Key Generation Specifications**
-**RSA key generation**
The following parameters are supported:
|Asymmetric Key Algorithm|Key Length (Bit)|Number of Primes|String Parameter|
|---|---|---|---|
|RSA|512|2|RSA512\|PRIMES_2|
|RSA|768|2|RSA768\|PRIMES_2|
|RSA|1024|2|RSA1024\|PRIMES_2|
|RSA|1024|3|RSA1024\|PRIMES_3|
|RSA|2048|2|RSA2048\|PRIMES_2|
|RSA|2048|3|RSA2048\|PRIMES_3|
|RSA|3072|2|RSA3072\|PRIMES_2|
|RSA|3072|3|RSA3072\|PRIMES_3|
|RSA|4096|2|RSA4096\|PRIMES_2|
|RSA|4096|3|RSA4096\|PRIMES_3|
|RSA|4096|4|RSA4096\|PRIMES_4|
|RSA|8192|2|RSA8192\|PRIMES_2|
|RSA|8192|3|RSA8192\|PRIMES_3|
|RSA|8192|4|RSA8192\|PRIMES_4|
|RSA|8192|5|RSA8192\|PRIMES_5|
> **NOTE**
>
> When an RSA asymmetric key is generated, the default prime number is 2, and **PRIMES_2** is optional.
|Asymmetric Key Type|Number of Primes|String Parameter|
|---|---|---|
|RSA512|2|RSA512\|PRIMES_2|
|RSA768|2|RSA768\|PRIMES_2|
|RSA1024|2|RSA1024\|PRIMES_2|
|RSA1024|3|RSA1024\|PRIMES_3|
|RSA2048|2|RSA2048\|PRIMES_2|
|RSA2048|3|RSA2048\|PRIMES_3|
|RSA3072|2|RSA3072\|PRIMES_2|
|RSA3072|3|RSA3072\|PRIMES_3|
|RSA4096|2|RSA4096\|PRIMES_2|
|RSA4096|3|RSA4096\|PRIMES_3|
|RSA4096|4|RSA4096\|PRIMES_4|
|RSA8192|2|RSA8192\|PRIMES_2|
|RSA8192|3|RSA8192\|PRIMES_3|
|RSA8192|4|RSA8192\|PRIMES_4|
|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.
-**ECC key generation**
...
...
@@ -214,95 +205,223 @@ The following parameters are supported:
**Symmetric Encryption and Decryption**
The following symmetric encryption algorithms are supported:
> - 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.
**Asymmetric RSA Encryption and Decryption**
The crypto framework provides three padding modes for RSA encryption/decryption: **NoPadding**, **PKCS1**, and **PKCS1_OAEP**.
- If **NoPadding** is used, specify the parameter as follows:
> - 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**.
> - 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**.
