@@ -28,18 +28,18 @@ The preference persistent file of an application is stored in the application sa
...
@@ -28,18 +28,18 @@ The preference persistent file of an application is stored in the application sa
## Available APIs
## Available APIs
The following table lists the APIs used for preferences data persistence. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [User Preferences](../reference/apis/js-apis-data-preferences.md).
The following table lists the APIs used for persisting user preference data. For more information about the APIs, see [User Preferences](../reference/apis/js-apis-data-preferences.md).
| put(key: string, value: ValueType, callback: AsyncCallback<void>): void | Writes data to the Preferences instance. You can use **flush()** to persist the **Preferences** instance data.|
| putSync(key: string, value: ValueType): void | Writes data to the Preferences instance. You can use **flush()** to persist the **Preferences** instance data. An asynchronous API is also provided. |
| has(key: string, callback: AsyncCallback<boolean>): void | Checks whether the **Preferences** instance contains a KV pair with the given key. The key cannot be empty.|
| hasSync(key: string): void | Checks whether the **Preferences** instance contains a KV pair with the given key. The key cannot be empty. An asynchronous API is also provided. |
| get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void | Obtains the value of the specified key. If the value is null or not of the default value type, **defValue** is returned.|
| getSync(key: string, defValue: ValueType): void | Obtains the value of the specified key. If the value is null or not of the default value type, **defValue** is returned. An asynchronous API is also provided. |
| delete(key: string, callback: AsyncCallback<void>): void | Deletes the KV pair with the given key from the **Preferences** instance.|
| deleteSync(key: string): void | Deletes the KV pair with the given key from the **Preferences** instance. An asynchronous API is also provided. |
| flush(callback: AsyncCallback<void>): void | Flushes the data of this **Preferences** instance to a file for data persistence.|
| flush(callback: AsyncCallback<void>): void | Flushes the data of this **Preferences** instance to a file for data persistence. |
| on(type: 'change', callback: Callback<{ key : string }>): void | Subscribes to data changes of the specified key. When the value of the specified key is changed and saved by **flush()**, a callback will be invoked to return the new data.|
| on(type: 'change', callback: Callback<{ key : string }>): void | Subscribes to data changes of the specified key. When the value of the specified key is changed and saved by **flush()**, a callback will be invoked to return the new data. |
| off(type: 'change', callback?: Callback<{ key : string }>): void | Unsubscribes from data changes.|
| off(type: 'change', callback?: Callback<{ key : string }>): void | Unsubscribes from data changes. |
| deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes a **Preferences** instance from memory. If the **Preferences** instance has a persistent file, this API also deletes the persistent file.|
| deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes a **Preferences** instance from memory. If the **Preferences** instance has a persistent file, this API also deletes the persistent file.|
...
@@ -102,40 +102,24 @@ The following table lists the APIs used for preferences data persistence. Most o
...
@@ -102,40 +102,24 @@ The following table lists the APIs used for preferences data persistence. Most o
3. Write data.
3. Write data.
Use **put()** to write data to the**Preferences** instance. After data is written, you can use **flush()** to persist the **Preferences** instance data to a file if necessary.
Use **putSync()** to write data to the cached**Preferences** instance. After data is written, you can use **flush()** to persist the **Preferences** instance data to a file if necessary.
> **NOTE**
> **NOTE**
>
>
> If the specified key already exists, the **put()** method changes the value. To prevent a value from being changed by mistake, you can use **has()** to check whether the KV pair exists.
> If the specified key already exists, the **putSync()** method changes the value. You can use **hasSync()** to check whether the KV pair exists.
Example:
Example:
```js
```js
try{
try{
preferences.has('startup',function(err,val){
if(preferences.hasSync('startup')){
if(err){
console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
if(val){
console.info("The key 'startup' is contained.");
console.info("The key 'startup' is contained.");
}else{
}else{
console.info("The key 'startup' does not contain.");
console.info("The key 'startup' does not contain.");
// Add a KV pair.
// Add a KV pair.
try{
preferences.putSync('startup','auto');
preferences.put('startup','auto',(err)=>{
if(err){
console.error(`Failed to put data. Code:${err.code}, message:${err.message}`);
return;
}
console.info('Succeeded in putting data.');
})
}catch(err){
console.error(`Failed to put data. Code: ${err.code},message:${err.message}`);
}
}
}
})
}catch(err){
}catch(err){
console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
}
}
...
@@ -143,17 +127,12 @@ The following table lists the APIs used for preferences data persistence. Most o
...
@@ -143,17 +127,12 @@ The following table lists the APIs used for preferences data persistence. Most o
4. Read data.
4. Read data.
Use **get()** to obtain the value of the specified key. If the value is null or is not of the default value type, the default data is returned. Example:
Use **getSync()** to obtain the value of the specified key. If the value is null or is not of the default value type, the default data is returned. Example:
```js
```js
try{
try{
preferences.get('startup','default',(err,val)=>{
letval=preferences.getSync('startup','default');
if(err){
console.error(`Failed to get value of 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
console.info(`Succeeded in getting value of 'startup'. val: ${val}.`);
console.info(`Succeeded in getting value of 'startup'. val: ${val}.`);
})
}catch(err){
}catch(err){
console.error(`Failed to get value of 'startup'. Code:${err.code}, message:${err.message}`);
console.error(`Failed to get value of 'startup'. Code:${err.code}, message:${err.message}`);
}
}
...
@@ -161,18 +140,12 @@ The following table lists the APIs used for preferences data persistence. Most o
...
@@ -161,18 +140,12 @@ The following table lists the APIs used for preferences data persistence. Most o
5. Delete data.
5. Delete data.
Use delete() to delete a KV pair.<br>Example:
Use **deleteSync()** to delete a KV pair.<br>Example:
```js
```js
try{
try{
preferences.delete('startup',(err)=>{
preferences.deleteSync('startup');
if(err){
console.error(`Failed to delete the key 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
console.info("Succeeded in deleting the key 'startup'.");
})
}catch(err){
}catch(err){
console.error(`Failed to delete the key 'startup'. Code:${err.code}, message:${err.message}`);
console.error(`Failed to delete the key 'startup'. Code:${err.code}, message:${err.message}`);
}
}
...
@@ -248,4 +221,3 @@ The following table lists the APIs used for preferences data persistence. Most o
...
@@ -248,4 +221,3 @@ The following table lists the APIs used for preferences data persistence. Most o
console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`);
console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`);
| 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<br>- SM4<sup>10+</sup>CBC, CTR, OFB, or CFB mode: 16-byte IV|
> **NOTE**
> **NOTE**
>
>
...
@@ -66,7 +66,7 @@ Defines the child class of [ParamsSpec](#paramsspec). It is used as the paramete
...
@@ -66,7 +66,7 @@ Defines the child class of [ParamsSpec](#paramsspec). It is used as the paramete
## GcmParamsSpec
## GcmParamsSpec
Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. <br>**GcmParamsSpec** applies to the GCM mode.
Defines the child class of [ParamsSpec](#paramsspec). It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. <br>**GcmParamsSpec** applies to the GCM mode.
@@ -82,7 +82,7 @@ Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is use
...
@@ -82,7 +82,7 @@ Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is use
## CcmParamsSpec
## CcmParamsSpec
Defines the child class of [ParamsSpec](#paramsspec) for the CCM mode. It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. <br>**CcmParamsSpec** applies to the CCM mode.
Defines the child class of [ParamsSpec](#paramsspec). It is used as the parameters of [init()](#init-2) during symmetric encryption and decryption. <br>**CcmParamsSpec** applies to the CCM mode.
@@ -131,7 +131,7 @@ Enumerates the key parameters.
...
@@ -131,7 +131,7 @@ Enumerates the key parameters.
| ECC_PK_X_BN | 209 | X coordinate of the public key **pk** (a point on the elliptic curve) in the ECC algorithm.|
| ECC_PK_X_BN | 209 | X coordinate of the public key **pk** (a point on the elliptic curve) in the ECC algorithm.|
| ECC_PK_Y_BN | 210 | Y coordinate of the public key **pk** (a point on the elliptic curve) in the ECC algorithm.|
| ECC_PK_Y_BN | 210 | Y coordinate of the public key **pk** (a point on the elliptic curve) in the ECC algorithm.|
| ECC_FIELD_TYPE_STR | 211 | Elliptic curve field type in the ECC algorithm. Currently, only the **Fp** field is supported.|
| ECC_FIELD_TYPE_STR | 211 | Elliptic curve field type in the ECC algorithm. Currently, only the **Fp** field is supported.|
| ECC_FIELD_SIZE_NUM | 212 | Size of the field in the ECC algorithm, in bits.<br>**NOTE**: For the **Fp** field, the field size is the length of the prime **p**, in bits. |
| ECC_FIELD_SIZE_NUM | 212 | Size of the field in the ECC algorithm, in bits.<br>**NOTE**<br>For the **Fp** field, the field size is the length of the prime **p**, in bits. |
| ECC_CURVE_NAME_STR | 213 | SECG curve name in the ECC algorithm.|
| ECC_CURVE_NAME_STR | 213 | SECG curve name in the ECC algorithm.|
| RSA_N_BN | 301 | Modulus **n** in the RSA algorithm.|
| RSA_N_BN | 301 | Modulus **n** in the RSA algorithm.|
| RSA_SK_BN | 302 | Private key **sk** (private key exponent **d**) in the RSA algorithm.|
| RSA_SK_BN | 302 | Private key **sk** (private key exponent **d**) in the RSA algorithm.|
...
@@ -494,7 +494,7 @@ Clears the keys in the memory. This API returns the result synchronously.
...
@@ -494,7 +494,7 @@ Clears the keys in the memory. This API returns the result synchronously.
```js
```js
letkey;// The key is a private key generated by the asymmetric key generator. The generation process is omitted here.
letkey;// The key is a private key generated by the asymmetric key generator. The generation process is omitted here.
key.clearMem();
key.clearMem();// For the asymmetric private key, clearMem() releases the internal key struct. After clearMem is executed, getEncoded() is not supported.
```
```
### getAsyKeySpec<sup>10+</sup>
### getAsyKeySpec<sup>10+</sup>
...
@@ -540,7 +540,6 @@ Defines an asymmetric key pair, which includes a public key and a private key. <
...
@@ -540,7 +540,6 @@ Defines an asymmetric key pair, which includes a public key and a private key. <
> **NOTE**
> **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 can be destructed.
> 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 can be destructed.
>
> The service must reference the **KeyPair** object instead of the internal **pubKey** or **priKey** object.
> The service must reference the **KeyPair** object instead of the internal **pubKey** or **priKey** object.
### Attributes
### Attributes
...
@@ -916,8 +915,8 @@ Converts data into an asymmetric key. This API uses an asynchronous callback to
...
@@ -916,8 +915,8 @@ Converts data into an asymmetric key. This API uses an asynchronous callback to
@@ -1297,8 +1296,8 @@ Creates a [Cipher](#cipher) instance based on the specified algorithm. <br>For d
...
@@ -1297,8 +1296,8 @@ Creates a [Cipher](#cipher) instance based on the specified algorithm. <br>For d
> **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.
> 2. If RSA is used for asymmetric encryption and decryption, two **Cipher** objects must be created to perform encryption and decryption separately. For symmetric encryption and decryption, one **cipher** object can be used to perform both encryption and decryption as long as the algorithm specifications are the same.
> 2. When RSA or SM2 are used for asymmetric encryption and decryption, create a **Cipher** instance for encryption and decryption respectively. Do not use the same **Cipher** instance for encryption and decryption. For symmetric encryption and decryption, one **cipher** object can be used to perform both encryption and decryption as long as the algorithm specifications are the same.
**Return value**
**Return value**
...
@@ -1336,7 +1335,7 @@ Provides APIs for cipher operations. The [init()](#init-2), [update()](#update-4
...
@@ -1336,7 +1335,7 @@ Provides APIs for cipher operations. The [init()](#init-2), [update()](#update-4
A complete symmetric encryption/decryption process is slightly different from the asymmetric encryption/decryption process.
A complete symmetric encryption/decryption process is slightly different from the asymmetric encryption/decryption process.
- Symmetric encryption and decryption: **init()** and **doFinal()** are mandatory. **update()** is optional and can be called multiple times to encrypt or decrypt big data. After **doFinal()** is called to complete an encryption or decryption operation, **init()** can be called to start a new encryption or decryption operation.
- Symmetric encryption and decryption: **init()** and **doFinal()** are mandatory. **update()** is optional and can be called multiple times to encrypt or decrypt big data. After **doFinal()** is called to complete an encryption or decryption operation, **init()** can be called to start a new encryption or decryption operation.
- RSA asymmetric encryption and decryption: **init()** and **doFinal()** are mandatory, and **update()** is not supported. **doFinal()** can be called multiple times to encrypt or decrypt big data. **init()** cannot be called repeatedly. If the encryption/decryption mode or padding mode is changed, a new **Cipher** object must be created.
- RSA or SM2 asymmetric encryption and decryption: **init()** and **doFinal()** are mandatory, and **update()** is not supported. **doFinal()** can be called multiple times to encrypt or decrypt big data. **init()** cannot be called repeatedly. If the encryption/decryption mode or padding mode is changed, a new **Cipher** object must be created.
### Attributes
### Attributes
...
@@ -1447,8 +1446,8 @@ Updates the data to encrypt or decrypt by segment. This API uses an asynchronous
...
@@ -1447,8 +1446,8 @@ Updates the data to encrypt or decrypt by segment. This API uses an asynchronous
> 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.
> 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.
> 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.
> 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.
> 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#encryption-and-decryption).
> For details about the sample code for calling **update()** multiple times in AES, see [Encryption and Decryption](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
> 3. RSA asymmetric encryption and decryption do not support **update()**.
> 3. RSA or SM2 asymmetric encryption and decryption do not support **update()**.
@@ -1501,17 +1500,15 @@ cipher.update(plainText, (err, output) => { // Example of the encryption p
...
@@ -1501,17 +1500,15 @@ cipher.update(plainText, (err, output) => { // Example of the encryption p
update(data: DataBlob): Promise\<DataBlob>
update(data: DataBlob): Promise\<DataBlob>
Updates the data to encrypt or decrypt by segment. This API uses a promise to return the encrypted or decrypted data.
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).
This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
> **NOTE**
> **NOTE**
>
>
> 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.
> 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.
> 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.
> 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.
> 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#encryption-and-decryption).
> For details about the sample code for calling **update()** multiple times in AES, see [Encryption and Decryption](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
> 3. RSA asymmetric encryption and decryption do not support **update()**.
> 3. RSA or SM2 asymmetric encryption and decryption do not support **update()**.
(1) Encrypts or decrypts the remaining data (generated by the block cipher mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses an asynchronous callback 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 cipher mode) and the data passed in by **doFinal()** to finalize the symmetric encryption or decryption. This API uses an asynchronous callback 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**. <br>**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 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.
(2) Encrypts or decrypts the input data for RSA or SM2 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**
> **NOTE**
>
>
> 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**.
> 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.
> 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.
> 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#encryption-and-decryption).
> 4. For details about the sample code for calling **doFinal()** multiple times during RSA or SM2 asymmetric encryption and decryption, see [Encryption and Decryption](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
(1) Encrypts or decrypts the remaining data (generated by the block cipher 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 cipher 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**. <br>**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 or SM2 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**
> **NOTE**
>
>
> 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**.
> 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.
> 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.
> 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#encryption-and-decryption).
> 4. For details about the sample code for calling **doFinal()** multiple times during RSA or SM2 asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#encryption-and-decryption).
@@ -1815,7 +1812,7 @@ let mdName = cipher.getCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MD_NAME_ST
...
@@ -1815,7 +1812,7 @@ let mdName = cipher.getCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MD_NAME_ST
createSign(algName: string): Sign
createSign(algName: string): Sign
Creates a **Sign** instance.For details about the supported specifications, see [Signing and Signature Verification Specifications](../../security/cryptoFramework-overview.md#signing-and-signature-verification-specifications).
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).
| algName | string | Yes | Signing algorithm, which can be RSA, ECC, or DSA.<br> If the RSA PKCS1 mode is used, you need to set the digest. If the RSA PSS mode is used, you need to set the digest and mask digest.|
| algName | string | Yes | Signing algorithm, which can be RSA, ECC, DSA, or SM2<sup>10+</sup>. If the RSA PKCS1 mode is used, you need to set the digest. If the RSA PSS mode is used, you need to set the digest and mask digest.|
**Return value**
**Return value**
...
@@ -1846,11 +1843,11 @@ import cryptoFramework from "@ohos.security.cryptoFramework"
...
@@ -1846,11 +1843,11 @@ import cryptoFramework from "@ohos.security.cryptoFramework"
@@ -1936,7 +1933,9 @@ Updates the data to be signed. This API uses a callback to complete the update.
...
@@ -1936,7 +1933,9 @@ Updates the data to be signed. This API uses a callback to complete the update.
> **NOTE**
> **NOTE**
>
>
> **update()** may be called multiple times or may not be called (call [sign](#sign-1) after [init](#init-2)), depending on the size of the data.<br>The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data needs to be signed, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.<br>For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
> **update()** may be called multiple times or may not be called (call [sign](#sign-1) after [init](#init-2)), depending on the size of the data.
> The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data needs to be signed, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.
> For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
| algName | string | Yes | Signing algorithm, which can be RSA, ECC, or DSA.<br> If the RSA PKCS1 mode is used, you need to set the digest. If the RSA PSS mode is used, you need to set the digest and mask digest.|
| algName | string | Yes | Signing algorithm, which can be RSA, ECC, DSA, or SM2<sup>10+</sup>. If the RSA PKCS1 mode is used, you need to set the digest. If the RSA PSS mode is used, you need to set the digest and mask digest.|
**Return value**
**Return value**
...
@@ -2345,7 +2344,7 @@ Updates the data for signature verification. This API uses a promise to return t
...
@@ -2345,7 +2344,7 @@ Updates the data for signature verification. This API uses a promise to return t
> **NOTE**
> **NOTE**
>
>
> **update()** may be called multiple times or may not be called (call [verify](#verify-2) after [init](#init-5)), depending on the size of the data.<br>
> **update()** may be called multiple times or may not be called (call [verify](#verify-2) after [init](#init-5)), depending on the size of the data.
> The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data is involved in signature verification, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.<br>
> The algorithm library does not set a limit on the amount of data to be updated (once or accumulatively). If a large amount of data is involved in signature verification, you are advised to use **update()** multiple times to pass in data. This can prevent too much memory from being requested at a time.<br>
> For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
> For details about the sample code for calling **update()** multiple times, see [Signing and Signature verification](../../security/cryptoFramework-guidelines.md#signing-and-signature-verification).
...
@@ -2714,7 +2713,7 @@ try {
...
@@ -2714,7 +2713,7 @@ try {
// Set algName based on the algorithm supported.
// Set algName based on the algorithm supported.
md=cryptoFramework.createMd("SHA256");
md=cryptoFramework.createMd("SHA256");
}catch(error){
}catch(error){
console.error("[Promise]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
```
```
...
@@ -2765,7 +2764,7 @@ var md;
...
@@ -2765,7 +2764,7 @@ var md;
try{
try{
md=cryptoFramework.createMd("SHA256");
md=cryptoFramework.createMd("SHA256");
}catch(error){
}catch(error){
console.error("[Callback]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
console.error("Md algName is: "+md.algName);
console.error("Md algName is: "+md.algName);
...
@@ -2815,7 +2814,7 @@ var md;
...
@@ -2815,7 +2814,7 @@ var md;
try{
try{
md=cryptoFramework.createMd("SHA256");
md=cryptoFramework.createMd("SHA256");
}catch(error){
}catch(error){
console.error("[Callback]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
console.error("Md algName is: "+md.algName);
console.error("Md algName is: "+md.algName);
...
@@ -2856,7 +2855,7 @@ var md;
...
@@ -2856,7 +2855,7 @@ var md;
try{
try{
md=cryptoFramework.createMd("SHA256");
md=cryptoFramework.createMd("SHA256");
}catch(error){
}catch(error){
console.error("[Callback]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
console.error("Md algName is: "+md.algName);
console.error("Md algName is: "+md.algName);
...
@@ -2905,7 +2904,7 @@ var md;
...
@@ -2905,7 +2904,7 @@ var md;
try{
try{
md=cryptoFramework.createMd("SHA256");
md=cryptoFramework.createMd("SHA256");
}catch(error){
}catch(error){
console.error("[Callback]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
console.error("Md algName is: "+md.algName);
console.error("Md algName is: "+md.algName);
...
@@ -2950,7 +2949,7 @@ var md;
...
@@ -2950,7 +2949,7 @@ var md;
try{
try{
md=cryptoFramework.createMd("SHA256");
md=cryptoFramework.createMd("SHA256");
}catch(error){
}catch(error){
console.error("[Callback]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
console.error("Md algName is: "+md.algName);
console.error("Md algName is: "+md.algName);
...
@@ -3005,7 +3004,7 @@ try {
...
@@ -3005,7 +3004,7 @@ try {
// Set algName based on the algorithm supported.
// Set algName based on the algorithm supported.
mac=cryptoFramework.createMac("SHA256");
mac=cryptoFramework.createMac("SHA256");
}catch(error){
}catch(error){
console.error("[Promise]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
}
}
```
```
...
@@ -3052,7 +3051,7 @@ var mac;
...
@@ -3052,7 +3051,7 @@ var mac;
try{
try{
mac=cryptoFramework.createMac("SHA256");
mac=cryptoFramework.createMac("SHA256");
}catch(error){
}catch(error){
console.error("[Promise]: error code: "+error.code+", message is: "+error.message);
console.error("[Sync]: error code: "+error.code+", message is: "+error.message);
@@ -18,7 +18,7 @@ import cloudData from '@ohos.data.cloudData';
...
@@ -18,7 +18,7 @@ import cloudData from '@ohos.data.cloudData';
## Action
## Action
Enumerates the actions for clearing the cloud information about the local data.
Enumerates the actions to take to clear the downloaded cloud data locally.
**System API**: This is a system API.
**System API**: This is a system API.
...
@@ -26,8 +26,8 @@ Enumerates the actions for clearing the cloud information about the local data.
...
@@ -26,8 +26,8 @@ Enumerates the actions for clearing the cloud information about the local data.
| Name | Description |
| Name | Description |
| --------- | ---------------------------- |
| --------- | ---------------------------- |
| CLEAR_CLOUD_INFO | Clear the cloud ID information.|
| CLEAR_CLOUD_INFO | Clear only the cloud identifier of the data downloaded from the cloud. The related data is still stored as local data.|
| CLEAR_CLOUD_DATA_AND_INFO |Clear all cloud data, including cloud ID information and data downloaded from the cloud (excluding the data modified or generated locally). |
| CLEAR_CLOUD_DATA_AND_INFO |Clear the data downloaded from the cloud, excluding the cloud data that has been modified locally. |
## Config
## Config
...
@@ -49,7 +49,7 @@ Enables device-cloud synergy. This API uses an asynchronous callback to return t
...
@@ -49,7 +49,7 @@ Enables device-cloud synergy. This API uses an asynchronous callback to return t
| accountId | string | Yes | ID of the target cloud. |
| accountId | string | Yes | ID of the cloud account. |
| switches | {[bundleName: string]: boolean} | Yes | Device-cloud synergy switches for applications. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
| switches | {[bundleName: string]: boolean} | Yes | Device-cloud synergy switches for applications. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. |
...
@@ -87,7 +87,7 @@ Enables device-cloud synergy. This API uses a promise to return the result.
...
@@ -87,7 +87,7 @@ Enables device-cloud synergy. This API uses a promise to return the result.
| accountId | string | Yes | ID of the target cloud. |
| accountId | string | Yes | ID of the cloud account. |
| switches | {[bundleName: string]: boolean} | Yes | Device-cloud synergy switches for applications. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
| switches | {[bundleName: string]: boolean} | Yes | Device-cloud synergy switches for applications. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
**Return value**
**Return value**
...
@@ -127,8 +127,8 @@ Disables device-cloud synergy. This API uses an asynchronous callback to return
...
@@ -127,8 +127,8 @@ Disables device-cloud synergy. This API uses an asynchronous callback to return
| accountId | string | Yes | ID of the target cloud.|
| accountId | string | Yes | ID of the cloud account.|
| bundleName| string | Yes | Name of the target application.|
| bundleName| string | Yes | Bundle name of the application.|
| status | boolean | Yes | Setting of the device-cloud synergy switch for the application. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
| status | boolean | Yes | Setting of the device-cloud synergy switch for the application. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. |
...
@@ -242,8 +242,8 @@ Changes the device-cloud synergy switch for an application. This API uses a prom
...
@@ -242,8 +242,8 @@ Changes the device-cloud synergy switch for an application. This API uses a prom
| accountId | string | Yes | ID of the target cloud.|
| accountId | string | Yes | ID of the cloud account.|
| bundleName| string | Yes | Name of the target application.|
| bundleName| string | Yes | Bundle name of the application.|
| status | boolean | Yes | Setting of the device-cloud synergy switch for the application. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
| status | boolean | Yes | Setting of the device-cloud synergy switch for the application. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.|
**Return value**
**Return value**
...
@@ -283,9 +283,9 @@ Notifies the data changes in the cloud. This API uses an asynchronous callback t
...
@@ -283,9 +283,9 @@ Notifies the data changes in the cloud. This API uses an asynchronous callback t
| accountId | string | Yes | ID of the cloud account. |
| appActions | {[bundleName: string]: [Action](#action)} | Yes | Information about the application whose data is to be cleared and the action to take.|
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. |
| accountId | string | Yes | ID of the cloud account. |
| appActions | {[bundleName: string]: [Action](#action)} | Yes | Information about the application whose data is to be cleared and the action to take.|
The **user preferences** module provides APIs for processing data in the form of key-value (KV) pairs and supports persistence of the KV pairs when required.
The **Preferences** module provides APIs for processing data in the form of key-value (KV) pairs, and supports persistence of the KV pairs when required, as well as modification and query of the data.
The key is of the string type, and the value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.
The key is of the string type, and the value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.
...
@@ -40,7 +40,7 @@ Obtains a **Preferences** instance. This API uses an asynchronous callback to re
...
@@ -40,7 +40,7 @@ Obtains a **Preferences** instance. This API uses an asynchronous callback to re
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance. |
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback<[Preferences](#preferences)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **object** is the **Preferences** instance obtained. Otherwise, **err** is an error code.|
| callback | AsyncCallback<[Preferences](#preferences)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and the **Preferences** instance obtained is returned. Otherwise, **err** is an error code.|
**Example**
**Example**
...
@@ -310,7 +310,7 @@ class EntryAbility extends UIAbility {
...
@@ -310,7 +310,7 @@ class EntryAbility extends UIAbility {
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance.|
console.info("Failed to remove preferences. code ="+err.code+", message ="+err.message);
}
}
}
```
## Preferences
## Preferences
Provides methods for obtaining and modifying data.
Provides APIs for obtaining and modifying the stored data.
Before calling any method of **Preferences**, you must obtain a **Preferences** instance by using [data_preferences.getPreferences](#data_preferencesgetpreferences).
Before calling any method of **Preferences**, you must obtain a **Preferences** instance by using [data_preferences.getPreferences](#data_preferencesgetpreferences).
...
@@ -445,7 +494,7 @@ Before calling any method of **Preferences**, you must obtain a **Preferences**
...
@@ -445,7 +494,7 @@ Before calling any method of **Preferences**, you must obtain a **Preferences**
Obtains the value of a key. This API uses an asynchronous callback to return the result. If the value is **null** or is not of the default value type, **defValue** is returned.
Obtains the value corresponding to the specified key from the cached **Preferences** instance. This API uses an asynchronous callback to return the result. If the value is null or is not of the default value type, **defValue** is returned.
Obtains the value of a key. This API uses a promise to return the result. If the value is **null** or is not of the default value type, **defValue** is returned.
Obtains the value corresponding to the specified key from the cached **Preferences** instance. This API uses a promise to return the result. If the value is null or is not of the default value type, **defValue** is returned.
Synchronously obtains the value corresponding to the specified key from the cached **Preferences** instance. If the value is null or is not of the default value type, **defValue** is returned.
| key | string | Yes | Key of the data to obtain. It cannot be empty. |
| defValue | [ValueType](#valuetype) | Yes | Default value to be returned. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback<Object> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **value**is the **Object** instance obtained. Otherwise, **err** is an error code.|
| callback | AsyncCallback<Object> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **value**provides all KV pairs obtained. Otherwise, **err** is an error code.|
**Example**
**Example**
...
@@ -547,7 +628,7 @@ try {
...
@@ -547,7 +628,7 @@ try {
getAll(): Promise<Object>
getAll(): Promise<Object>
Obtains an **Object** instance that contains all KV pairs. This API uses a promise to return the result.
Obtains all KV pairs from the cached **Preferences** instance. This API uses a promise to return the result.
Writes data to this **Preferences** instance. This API uses an asynchronous callback to return the result. You can use [flush](#flush) to make the **Preferences** instance persistent.
Writes data to the cached **Preferences** instance. This API uses an asynchronous callback to return the result. You can use [flush](#flush) to persist the **Preferences** instance.
Writes data to this **Preferences** instance. This API uses a promise to return the result. You can use [flush](#flush) to make the **Preferences** instance persistent.
Writes data to the cached **Preferences** instance. This API uses a promise to return the result. You can use [flush](#flush) to persist the **Preferences** instance.
| key | string | Yes | Key of the data. It cannot be empty. |
| value | [ValueType](#valuetype) | Yes | Value to write. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
**Example**
```js
try{
preferences.putSync('startup','auto');
}catch(err){
console.info("Failed to put value of 'startup'. code ="+err.code+", message ="+err.message);
Deletes a KV pair from this **Preferences** instance based on the specified key. This API uses an asynchronous callback to return the result.
Deletes a KV pair from the cached **Preferences** instance based on the specified key. This API uses an asynchronous callback to return the result. You can use [flush](#flush) to persist the **Preferences** instance.
Deletes a KV pair from this **Preferences** instance. This API uses a promise to return the result.
Deletes a KV pair from the cached **Preferences** instance based on the specified key. This API uses a promise to return the result. You can use [flush](#flush) to persist the **Preferences** instance.
Synchronously deletes a KV pair from the cached **Preferences** instance based on the specified key. You can use [flush](#flush) to persist the **Preferences** instance.
Clears this **Preferences** instance. This API uses an asynchronous callback to return the result.
Clears all data in the cached **Preferences** instance. This API uses an asynchronous callback to return the result. You can use [flush](#flush) to persist the **Preferences** instance.
Clears this **Preferences** instance. This API uses a promise to return the result.
Clears all data in the cached **Preferences** instance. This API uses a promise to return the result. You can use [flush](#flush) to persist the **Preferences** instance.
@@ -8,8 +8,6 @@ The **DataStorage** module provides applications with data processing capability
...
@@ -8,8 +8,6 @@ The **DataStorage** module provides applications with data processing capability
> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
>
> - The APIs of this module are no longer maintained since API version 9. You are advised to use [@ohos.data.preferences](js-apis-data-preferences.md).
> - The APIs of this module are no longer maintained since API version 9. You are advised to use [@ohos.data.preferences](js-apis-data-preferences.md).
>
> - The APIs of this module can be used only in the FA model.
## Modules to Import
## Modules to Import
...
@@ -188,7 +186,7 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete
...
@@ -188,7 +186,7 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete
@@ -267,7 +267,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
...
@@ -267,7 +267,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| ID| Error Message|
| ID| Error Message|
| -------- | -------- |
| -------- | -------- |
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
| 12100001 | The tokenID is 0, permissionName is longer than 256 bytes, or the count value is invalid. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100004 | The interface is called repeatedly with the same input. It means the application specified by the tokenID has been using the specified permission. |
| 12100004 | The interface is called repeatedly with the same input. It means the application specified by the tokenID has been using the specified permission. |
...
@@ -315,7 +315,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
...
@@ -315,7 +315,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| ID| Error Message|
| ID| Error Message|
| -------- | -------- |
| -------- | -------- |
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
| 12100001 | The tokenID is 0, permissionName is longer than 256 bytes, or the count value is invalid. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100004 | The interface is called repeatedly with the same input. It means the application specified by the tokenID has been using the specified permission. |
| 12100004 | The interface is called repeatedly with the same input. It means the application specified by the tokenID has been using the specified permission. |
...
@@ -370,7 +370,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
...
@@ -370,7 +370,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| ID| Error Message|
| ID| Error Message|
| -------- | -------- |
| -------- | -------- |
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
| 12100001 | The tokenID is 0, permissionName is longer than 256 bytes, or the count value is invalid. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100004 | The interface is not used with |
| 12100004 | The interface is not used with |
...
@@ -418,7 +418,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
...
@@ -418,7 +418,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| ID| Error Message|
| ID| Error Message|
| -------- | -------- |
| -------- | -------- |
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
| 12100001 | The tokenID is 0, permissionName is longer than 256 bytes, or the count value is invalid. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100002 | The specified tokenID does not exist or refer to an application process. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100004 | The interface is not used with |
| 12100004 | The interface is not used with |
...
@@ -551,8 +551,8 @@ Represents the request for querying permission usage records.
...
@@ -551,8 +551,8 @@ Represents the request for querying permission usage records.
| tokenId | number | No | Token ID of the application (invoker).<br>By default, all applications are queried. |
| tokenId | number | No | Token ID of the application (invoker).<br>By default, all applications are queried. |
| isRemote | boolean | No | Whether to query the permission usage records of the remote device.<br>The default value is **false**, which means the permission usage records of the local device are queried by default.|
| isRemote | boolean | No | Whether to query the permission usage records of the remote device.<br>The default value is **false**, which means the permission usage records of the local device are queried by default.|
| deviceId | string | No | ID of the device hosting the target application.<br>The default value is the local device ID. |
| deviceId | string | No | ID of the device hosting the target application.<br>The default value is the local device ID. |
| bundleName | string | No | Bundle name of the target application.<br>By default, all applications are queried.|
| bundleName | string | No | Bundle name of the target application.<br>By default, all applications are queried.|
| permissionNames | Array<Permissions> | No | Permissions to query.<br>By default, the usage records of all permissions are queried. |
| permissionNames | Array<Permissions> | No | Permissions to query.<br>By default, the usage records of all permissions are queried. |
| beginTime | number | No | Start time of the query, in ms.<br>The default value is **0**, which means the start time is not set.|
| beginTime | number | No | Start time of the query, in ms.<br>The default value is **0**, which means the start time is not set.|
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -5836,7 +5853,6 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -5836,7 +5853,6 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| ------- | -------------------------------- |
| ------- | -------------------------------- |
| boolean | Returns **true** if the message is sent successfully; returns **false** otherwise.|
| boolean | Returns **true** if the message is sent successfully; returns **false** otherwise.|
### sendRequest<sup>8+(deprecated)</sup>
### sendRequest<sup>8+(deprecated)</sup>
>This API is no longer maintained since API version 9. You are advised to use [sendMessageRequest](#sendmessagerequest9).
>This API is no longer maintained since API version 9. You are advised to use [sendMessageRequest](#sendmessagerequest9).
...
@@ -5851,7 +5867,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -5851,7 +5867,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -5862,7 +5878,6 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -5862,7 +5878,6 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -5886,7 +5901,6 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
...
@@ -5886,7 +5901,6 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -5919,7 +5933,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -5919,7 +5933,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -5946,7 +5960,7 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
...
@@ -5946,7 +5960,7 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
| ID| Error Message|
| ID| Error Message|
| -------- | -------- |
| -------- | -------- |
| 1900008 | proxy or remote object is invalid |
| 1900005 | only proxy object permitted |
### addDeathrecipient<sup>(deprecated)</sup>
### addDeathrecipient<sup>(deprecated)</sup>
...
@@ -5971,7 +5985,6 @@ Adds a callback for receiving death notifications of the remote object. This met
...
@@ -5971,7 +5985,6 @@ Adds a callback for receiving death notifications of the remote object. This met
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -6177,7 +6187,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
...
@@ -6177,7 +6187,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -6261,7 +6271,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -6261,7 +6271,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -6343,7 +6353,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
...
@@ -6343,7 +6353,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -6424,7 +6434,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -6424,7 +6434,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -7080,12 +7090,11 @@ Provides common message options (flag and wait time). Use the specified flag to
...
@@ -7080,12 +7090,11 @@ Provides common message options (flag and wait time). Use the specified flag to
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -7748,7 +7752,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -7748,7 +7752,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -7818,7 +7822,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
...
@@ -7818,7 +7822,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -7874,7 +7878,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
...
@@ -7874,7 +7878,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -7924,7 +7928,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
...
@@ -7924,7 +7928,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| code | number | Yes | Message code (1-16777215) called by the request, which is determined by the communication parties. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.|
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
...
@@ -8239,7 +8243,6 @@ Obtains the interface descriptor.
...
@@ -8239,7 +8243,6 @@ Obtains the interface descriptor.
| result | number | Yes | User authentication result. If the operation is successful, **0** is returned. If the operation fails, an error code is returned. For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).|
> **NOTE**<br>You need to use the [UserAuthInstance](#userauthinstance10) instance that has successfully subscribed to the event to call this API to cancel the subscription.
Provides APIs for managing the user authentication widget. You can use the APIs to register the user authentication widget with UserAuthWidgetMgr for management and scheduling.
| type | 'command' | Yes | Event type to subscribe to. **command** indicates the command sent from the user authentication framework to the user authentication widget.|
| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | Yes | Callback invoked to send the command from the user authentication framework to the user authentication widget.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| type | 'command' | Yes | Event type to unsubscribe from. **command** indicates the command sent from the user authentication framework to the user authentication widget.|
| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | No | Callback for the command sent from the user authentication framework to the user authentication widget.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
@@ -145,10 +818,10 @@ Subscribes to the user authentication events of the specified type.
...
@@ -145,10 +818,10 @@ Subscribes to the user authentication events of the specified type.
| name | [AuthEventKey](#autheventkey9) | Yes | Authentication event type. If the value is **result**, the callback returns the authentication result. If the value is **tip**, the callback returns the authentication tip information.|
| name | [AuthEventKey](#autheventkey9) | Yes | Authentication event type. If the value is **result**, the callback returns the authentication result. If the value is **tip**, the callback returns the authentication tip information.|
| callback | [AuthEvent](#authevent9) | Yes | Callback invoked to return the authentication result or tip information.|
| callback | [AuthEvent](#authevent9) | Yes | Callback invoked to return the authentication result or tip information.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| ID| Error Message|
| -------- | ------- |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 401 | Incorrect parameters. |
...
@@ -194,14 +867,17 @@ try {
...
@@ -194,14 +867,17 @@ try {
}
}
```
```
### off<sup>9+</sup>
### off<sup>(deprecated)</sup>
off : (name : AuthEventKey) => void
off : (name : AuthEventKey) => void
Unsubscribes from the user authentication events of the specific type.
Unsubscribes from the user authentication events of the specific type.
>**NOTE**<br>
>This API is supported since API version 9 and deprecated since API version 10.
> **NOTE**<br>
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to unsubscribe from events.
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API to unsubscribe from events.
| name | [AuthEventKey](#autheventkey9) | Yes | Type of the authentication event to unsubscribe from. If the value is **result**, the authentication result is unsubscribed from. If the value is **tip**, the authentication tip information is unsubscribed from.|
| name | [AuthEventKey](#autheventkey9) | Yes | Type of the authentication event to unsubscribe from. If the value is **result**, the authentication result is unsubscribed from. If the value is **tip**, the authentication tip information is unsubscribed from.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| ID| Error Message|
| -------- | ------- |
| -------- | ------- |
| 401 | Incorrect parameters. |
| 401 | Incorrect parameters. |
...
@@ -257,23 +933,26 @@ try {
...
@@ -257,23 +933,26 @@ try {
}
}
```
```
### start<sup>9+</sup>
### start<sup>(deprecated)</sup>
start : () => void
start : () => void
Starts authentication.
Starts authentication.
> **NOTE**<br>
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API.
> This API is supported since API version 9 and deprecated since API version 10.
> **NOTE**<br>
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API.
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| ID| Error Message|
| -------- | ------- |
| -------- | ------- |
| 201 | Permission verification failed. |
| 201 | Permission verification failed. |
...
@@ -306,23 +985,26 @@ try {
...
@@ -306,23 +985,26 @@ try {
}
}
```
```
### cancel<sup>9+</sup>
### cancel<sup>(deprecated)</sup>
cancel : () => void
cancel : () => void
Cancels this authentication.
Cancels this authentication.
> **NOTE**<br>
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API. The [AuthInstance](#authinstance9) instance must be the one being authenticated.
> This API is supported since API version 9 and deprecated since API version 10.
> **NOTE**<br>
> Use the [AuthInstance](#authinstancedeprecated) instance obtained to invoke this API. The [AuthInstance](#authinstancedeprecated) instance must be the instance being authenticated.
Obtains an **AuthInstance** instance for user authentication.
Obtains an **AuthInstance** instance for user authentication.
> **NOTE**<br>
> This API is supported since API version 9 and deprecated since API version 10. Use [getUserAuthInstance](#useriam_userauthgetuserauthinstance10) instead.
> **NOTE**<br>
> **NOTE**<br>
> An **AuthInstance** instance can be used for an authentication only once.
> An **AuthInstance** instance can be used for an authentication only once.
...
@@ -369,13 +1054,13 @@ Obtains an **AuthInstance** instance for user authentication.
...
@@ -369,13 +1054,13 @@ Obtains an **AuthInstance** instance for user authentication.
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| ID| Error Message|
| -------- | ------- |
| -------- | ------- |
| 201 | Permission verification failed. |
| 201 | Permission verification failed. |
...
@@ -461,19 +1146,20 @@ Enumerates the authentication result codes.
...
@@ -461,19 +1146,20 @@ Enumerates the authentication result codes.
| BUSY | 12500007 | Indicates the busy state. |
| BUSY | 12500007 | Indicates the busy state. |
| LOCKED | 12500009 | The authentication executor is locked. |
| LOCKED | 12500009 | The authentication executor is locked. |
| NOT_ENROLLED | 12500010 | The user has not entered the authentication information.|
| NOT_ENROLLED | 12500010 | The user has not entered the authentication information.|
| CANCELED_FROM_WIDGET | 12500011 | The authentication is canceled by the user from the user authentication widget. If this error code is returned, the authentication is customized by the application.|
## UserAuth<sup>8+</sup>
## UserAuth<sup>(deprecated)</sup>
Provides APIs to manage an **Authenticator** object.
Provides APIs for user authentication.
### constructor<sup>(deprecated)</sup>
### constructor<sup>(deprecated)</sup>
constructor()
constructor()
A constructor used to create an authenticator instance.
A constructor used to create a**UserAuth** instance.
> **NOTE**<br>
> **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [getAuthInstance](#useriam_userauthgetauthinstance9).
> This API is supported since API version 8 and deprecated since API version 9. Use [getAuthInstance](#useriam_userauthgetauthinstancedeprecated) instead.
- Framework layer: flexibly loads plug-ins at the plug-in layer to adapt to third-party algorithm libraries and shield 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
...
@@ -27,6 +26,10 @@ A symmetric key is a key used both to encrypt and decrypt data. In symmetric enc
...
@@ -27,6 +26,10 @@ A symmetric key is a key used both to encrypt and decrypt data. In symmetric enc
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.
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.
-**SM4 key**
ShangMi 4 (SM4) is a block cipher that has a key size and a block size of 128 bits each. Both the encryption and decryption of one block of data is composed of 32 rounds. A non-linear key scheduler is used to produce the round keys. The decryption uses the same round keys as for encryption, except that they are in reversed order.
### Asymmetric Key
### 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.
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.
...
@@ -81,6 +84,26 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -81,6 +84,26 @@ In the asymmetric cryptography, a private and public key pair is required. The p
**pk**: public key. pk = (g ^ sk) mod p
**pk**: public key. pk = (g ^ sk) mod p
-**SM2 key**
ShangMi 2 (SM2) is a public key cryptographic algorithm based on the ECC. The key length is 256 bits. The SM2 algorithm uses the elliptic curve in the Fp fields.
The SM2 key parameters in the **Fp** fields include the following:
**p**: a prime greater than 3, used to determine **Fp**.
**a**, **b**: determine the elliptic curve equation.
**g**: base point of the elliptic curve, which can be represented as **gx** or **gy**.
**n**: order of the base point **g**.
**h**: cofactor.
**sk**: private key, which is a random integer less than **n**.
**pk**: public key, which is a point on the elliptic curve. **pk** = **sk** x **g**.
### Encryption and Decryption
### Encryption and Decryption
-**Symmetric AES encryption and decryption**
-**Symmetric AES encryption and decryption**
...
@@ -109,9 +132,22 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -109,9 +132,22 @@ In the asymmetric cryptography, a private and public key pair is required. The p
> In ECB and CBC modes, the plaintext must be padded if its length is not an integer multiple of 64 bits.
> 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.
> 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.
-**Symmetric SM4 encryption and decryption**
The Crypto Framework provides the following SM4 encryption modes: ECB, CBC, CTR, OFB, CFB, and CFB128. SM4 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.
-**PKCS7**: pads any block size from 1 to 255 bytes. The PKCS #7 padding scheme is the same as that of PKCS #5.
> **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 SM4 encryption.
-**Asymmetric RSA encryption and decryption**
-**Asymmetric RSA encryption and decryption**
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:
RSA is an asymmetric 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.
-**NoPadding**: no padding. The length of the input or output data must be the same as that of the RSA key modulus.
-**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.
-**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.
...
@@ -123,6 +159,7 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -123,6 +159,7 @@ In the asymmetric cryptography, a private and public key pair is required. The p
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.
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.
The **PKCS1_OAEP** parameters include the following:
The **PKCS1_OAEP** parameters include the following:
**md**: message digest algorithm.<br>
**md**: message digest algorithm.<br>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<br>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<br>
**mgf1_md**: mgf1 digest algorithm.<br>
**mgf1_md**: mgf1 digest algorithm.<br>
...
@@ -132,14 +169,21 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -132,14 +169,21 @@ In the asymmetric cryptography, a private and public key pair is required. The p
>
>
> RSA key modulus = (RSA bits + 7)/8
> RSA key modulus = (RSA bits + 7)/8
-**Asymmetric SM2 encryption and decryption**
SM2 is an asymmetric encryption algorithm based on the ECC. The encryption length is fixed. Currently, the Crypto Framework supports encrypted data in C1C3C2 format and decryption of data in C1C3C2 format.
### Signing and Signature Verification
### Signing and Signature Verification
-**RSA signing and signature verification**
-**RSA signing and signature verification**
The Crypto Framework provides the following padding modes for RSA signing and signature verification:
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.
-**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>
-**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.
The PSS parameters include the following:
**md**: message digest algorithm.<br>
**md**: message digest algorithm.<br>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<br>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<br>
**mgf1_md**: digest algorithm used in the MGF1 algorithm.<br>
**mgf1_md**: digest algorithm used in the MGF1 algorithm.<br>
...
@@ -158,6 +202,11 @@ In the asymmetric cryptography, a private and public key pair is required. The p
...
@@ -158,6 +202,11 @@ In the asymmetric cryptography, a private and public key pair is required. The p
The DSA security is based on the difficulty of the DLP in integer finite field. The DSA features high compatibility and applicability.
The DSA security is based on the difficulty of the DLP in integer finite field. The DSA features high compatibility and applicability.
-**SM2**
SM2 is a digital signature algorithm based on the ECC.
### Key Agreement
### Key Agreement
**ECDH**
**ECDH**
...
@@ -166,20 +215,13 @@ Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared se
...
@@ -166,20 +215,13 @@ Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared se
### Message Digest
### Message 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 section "HMAC".
MD algorithms include MD2, MD4, and MD5.
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. 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.
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.
...
@@ -214,9 +256,9 @@ The AES key can be generated based on a string parameter.
...
@@ -214,9 +256,9 @@ The AES key can be generated based on a string parameter.
|AES|192|AES192|
|AES|192|AES192|
|AES|256|AES256|
|AES|256|AES256|
> **NOTE**
> **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.
> 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.
### 3DES Key Generation Specifications
### 3DES Key Generation Specifications
...
@@ -226,9 +268,9 @@ The 3DES key can be generated based on a string parameter.
...
@@ -226,9 +268,9 @@ The 3DES key can be generated based on a string parameter.
|---|---|---|
|---|---|---|
|3DES|192|3DES192|
|3DES|192|3DES192|
> **NOTE**
> **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.
> 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
### RSA Key Generation Specifications
...
@@ -266,22 +308,21 @@ The 3DES key can be generated based on a string parameter.
...
@@ -266,22 +308,21 @@ The 3DES key can be generated based on a string parameter.
> The key parameters are used to specify the key specifications when an asymmetric key generator is created.
> 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 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.
> 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.
> **CAUTION**
> **CAUTION**
>
>
> - RSA does not support random key generation by specifying the public parameter (**n**).
> - RSA does not support random key generation based on the public parameter (**n**).
>
> - RSA does not support generation of the private key by specifying the private key parameters (**n**, **sk**).
> - RSA does not support generation of the private key by specifying private key parameters (**n**, **sk**).
### ECC Key Generation Specifications
### ECC Key Generation Specifications
> **NOTE**
> **NOTE**
...
@@ -299,11 +340,13 @@ The 3DES key can be generated based on a string parameter.
...
@@ -299,11 +340,13 @@ The 3DES key can be generated based on a string parameter.
> **NOTE**
> **NOTE**
>
>
> 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.
> 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.<br>
>
> Currently, only ECC Fp curves are supported.
> 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 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.
@@ -312,19 +355,19 @@ The 3DES key can be generated based on a string parameter.
...
@@ -312,19 +355,19 @@ The 3DES key can be generated based on a string parameter.
|b | √| √| √| √|
|b | √| √| √| √|
|g | √| √| √| √|
|g | √| √| √| √|
|n | √| √| √| √|
|n | √| √| √| √|
|h | √| √| √| √|
|h | √| √| √| √|
|pk | | √| | √|
|pk | | √| | √|
|sk | | | √| √|
|sk | | | √| √|
> **NOTE**
> **NOTE**
>
>
> The key parameters specify the key specifications when an asymmetric key generator is created.
> The key parameters specify the key specifications when an asymmetric key generator is created.<br>
>
> The preceding table describes the public and private key parameters supported by the Crypto Framework algorithm library for generating ECC keys.<br>
> 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.
> √ indicates that properties needs to be specified to construct the key parameter.
> **CAUTION**
> **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).
> - Currently, the ECC supports only the **Fp** fields. Therefore, **fieldType** has a fixed value of **Fp**. **fieldType** and **p** constitute the property **field**. Currently, the **field** 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.
> - **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.
### DSA Key Generation Specifications
### DSA Key Generation Specifications
...
@@ -345,29 +388,64 @@ The 3DES key can be generated based on a string parameter.
...
@@ -345,29 +388,64 @@ The 3DES 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.
> 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 DSA keys 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 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.
> The preceding table describes the public and private key parameters supported by the Crypto Framework algorithm library for generating DSA 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.
> √ 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**
> **CAUTION**
>
>
> - DSA does not support generation of the private key by specifying the private key parameters (**p**, **q**, **g**, **sk**).
> - 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.
> - When common parameters (**p**, **q**, **g**) are specified to generate a DSA key pair, the DSA key length must be at least 1024 bits.
### SM2 Key Generation Specifications
> **NOTE**
>
> SM2 keys can be randomly generated from API version 10.
- The SM2 keys can be generated based on the string parameter.
> As a combination of the asymmetric key algorithm and key length with an underscore (_) in between, the string parameter specifies the key specifications when an asymmetric key generator is created.
### SM4 Key Generation Specifications
> **NOTE**
>
> SM4 keys can be randomly generated from API version 10.
- The SM4 keys can be generated based on the string parameter.
> As a combination of the symmetric key algorithm and key length with an underscore (_) in between, the string parameter specifies the key specifications when a symmetric key generator is created.
## Encryption and Decryption Specifications
## Encryption and Decryption Specifications
### Symmetric Encryption and Decryption
### Symmetric Encryption and Decryption
...
@@ -376,25 +454,32 @@ The 3DES key can be generated based on a string parameter.
...
@@ -376,25 +454,32 @@ The 3DES key can be generated based on a string parameter.
>
>
> The APIs support specifications without the key length for symmetric encryption and decryption from API version 10.
> The APIs support specifications without the key length for symmetric encryption and decryption from API version 10.
The following symmetric encryption algorithms are supported.
- The following symmetric encryption algorithms are supported.
|Symmetric Encryption and Decryption Algorithm|Block Cipher Mode|String Parameter |
|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.
> - 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.
> - 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.
> - An underscore (_) must be added between SM4<sup>10+</sup> and the key length in **String Parameter**.
### Asymmetric RSA Encryption and Decryption
### Asymmetric RSA Encryption and Decryption
...
@@ -505,6 +590,25 @@ The Crypto Framework provides three padding modes for RSA encryption/decryption:
...
@@ -505,6 +590,25 @@ The Crypto Framework provides three padding modes for RSA encryption/decryption:
>
>
> 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.
> 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.
### **Asymmetric SM2 Encryption and Decryption**
> **NOTE**
>
> The APIs support specifications without the key length for asymmetric SM2 encryption and decryption from API version 10.
The SM2 encryption and decryption support only the ciphertext in C1C3C2 format. The SM2 asymmetric encryption result consists of C1, C2, and C3. C1 is the elliptic curve points calculated based on the random number generated. C2 is the ciphertext data. C3 is the value calculated using the specified digest algorithm. The new SM standard support data in C1C3C2 format. Encryption without digest is not supported.
> 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.
## Signing and Signature Verification Specifications
## Signing and Signature Verification Specifications
### RSA Signing and Signature Verification
### RSA Signing and Signature Verification
...
@@ -604,6 +708,7 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
...
@@ -604,6 +708,7 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
### ECDSA Signing and Signature Verification
### ECDSA Signing and Signature Verification
> **NOTE**
> **NOTE**
>
> The APIs support specifications without the key length for ECDSA signing and signature verification from API version 10.
> The APIs support specifications without the key length for ECDSA signing and signature verification from API version 10.
- The following ECDSA parameters are supported.
- The following ECDSA parameters are supported.
...
@@ -642,6 +747,26 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
...
@@ -642,6 +747,26 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
> - 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**.
> - 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.
> - 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.
### SM2 Signature Verification
> **NOTE**
>
> The APIs support SM2 signing and signature verification from API version 10.
- The following SM2 parameters are supported.
|Asymmetric Key Type|Digest|String Parameter|
|---|---|---|
|SM2_256|SM3|SM2_256\|SM3|
|SM2|SM3|SM2\|SM3|
> **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 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.
> - SM2 digital signatures support only the SM3 digest.
## Key Agreement Specifications
## Key Agreement Specifications
### ECDH
### ECDH
...
@@ -668,41 +793,51 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
...
@@ -668,41 +793,51 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
## MD Algorithm Specifications
## MD Algorithm Specifications
The Crypto Framework supports the following MD algorithm parameters.
-The Crypto Framework supports the following MD algorithm parameters.
|Digest algorithm|Supported Type|
> **NOTE**
|---|---|
>
|HASH|SHA1|
> SM3 is supported since API version 10.
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
|HASH|MD5|
> **NOTE**
|Digest Algorithm|Supported Type|
>
|---|---|
> **Supported Type** specifies the MD algorithm specifications when an MD instance is created.
|HASH|SHA1|
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
|HASH|MD5|
|HASH|SM3|
> **NOTE**
>
> **Supported Type** specifies the MD algorithm specifications when an MD instance is created.
## HMAC Algorithm Specifications
## HMAC Algorithm Specifications
The Crypto Framework supports the following HMAC algorithm parameters.
-The Crypto Framework supports the following HMAC algorithm parameters.
|Digest algorithm|Supported Type|
> **NOTE**
|---|---|
>
|HASH|SHA1|
> SM3 is supported from API version 10.
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
> **NOTE**
|Digest Algorithm|Supported Type|
>
|---|---|
> **Supported Type** specifies the HMAC algorithm specifications when an HMAC instance is created.
|HASH|SHA1|
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
|HASH|SM3|
> **NOTE**
>
> **Supported Type** specifies the HMAC algorithm specifications when an HMAC instance is created.
## Random Number
## Random Number
Currently, the Crypto Framework supports only the CTR_DRBG algorithm.
-Currently, the Crypto Framework supports only the CTR_DRBG algorithm.
> **NOTE**
> **NOTE**
>
>
> - Currently, only secure random numbers with length of 1 to **INT_MAX** bytes are supported.
> - 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.
> - The random number generation algorithm uses the **RAND_priv_bytes** interface of OpenSSL to generate secure random numbers.
## cl.accessToken.1 Change of the Media and File Permission Group
The original Media and File permission group contains the following permissions:
- ohos.permission.MEDIA_LOCATION
- ohos.permission.READ_MEDIA
- ohos.permission.WRITE_MEDIA
Changed the permission group as follows:
- Added **ohos.permission.MEDIA_LOCATION** to the Image and Video permission group.
- Added **ohos.permission.READ_MEDIA** and **ohos.permission.WRITE_MEDIA** to the File permission group.
**Change Impact**
The permission dialog boxes are displayed by permission group.
- Before the change, if the three permissions are applied for an application, a dialog box for applying for the media and file permissions will be displayed only once.
- After the change, if the three permissions are applied for an application, a dialog box for applying for the image and video permissions and a dialog box for applying for the file permission will be displayed.
**Key API/Component Changes**
Permission group before the change:
| Permission | Permission Group |
| -------- | ---------------------------- |
| ohos.permission.MEDIA_LOCATION | Media and File|
| ohos.permission.READ_MEDIA | Media and File|
| ohos.permission.WRITE_MEDIA | Media and File|
Permission groups after the change:
| Permission | Permission Group |
| -------- | ---------------------------- |
| ohos.permission.MEDIA_LOCATION | Image and Video|
## cl.security.1 Addition of the @throws Tags for Exceptions Thrown in API Version 9
Added the @throws tags for the APIs of API version 9 in the JS document.
**Change Impact**
For released JS interfaces, the exception handling process may be affected, including synchronous and asynchronous exceptions. Check the exception handling process based on the latest @throws tags and make adaptation.
**Key API/Component Changes**
Before change:
```ts
interfaceKey{
/**
* Encode the key object to binary data.
*
* @returns { DataBlob } the binary data of the key object.
Check the exception handling process based on the latest @throws tags and modify the code as required.
- For synchronization methods, such as **createSign**, use try/catch to process error information.
- For asynchronous methods, such as **convertKey**, use try/catch to process synchronous parameter errors and use the **error** object to obtain asynchronous parameter errors and service execution errors.
