Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
“b5fda2723f7889c102f6ffaa5cd8a901b29b612d”上不存在“paddle/phi/backends/dynload/warprnnt.cc”
未验证 提交 7ac51b30 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!20947 [翻译完成】#I7HDO3 (20308+20371+20375+20109+20413+20070+20585+20649) 

Merge pull request !20947 from Annie_wang/PR20293
上级 0f75dad7 4450feed
显示空白变更内容
内联 并排
Showing with 1792 addition and 378 deletion
en/application-dev/database/data-persistence-by-preferences.md
浏览文件 @ 7ac51b30
......@@ -28,18 +28,18 @@ The preference persistent file of an application is stored in the application sa
## 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).
| API| Description|
| -------- | -------- |
| getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void | Obtain a **Preferences** instance.|
| 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.|
| 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.|
| 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.|
| delete(key: string, callback: AsyncCallback<void>): void | Deletes the KV pair with the given key from the **Preferences** instance.|
| 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.|
| off(type: 'change', callback?: Callback<{ key : string }>): void | Unsubscribes from data changes.|
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).
| API | Description |
|--------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void | Obtain a **Preferences** instance. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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
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**
>
> 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:
```js
try {
preferences.has('startup', function (err, val) {
if (err) {
console.error(`Failed to check the key 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
if (val) {
if (preferences.hasSync('startup')) {
console.info("The key 'startup' is contained.");
} else {
console.info("The key 'startup' does not contain.");
// Add a KV pair.
try {
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}`);
}
preferences.putSync('startup', 'auto');
}
})
} catch (err) {
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
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
try {
preferences.get('startup', 'default', (err, val) => {
if (err) {
console.error(`Failed to get value of 'startup'. Code:${err.code}, message:${err.message}`);
return;
}
let val = preferences.getSync('startup', 'default');
console.info(`Succeeded in getting value of 'startup'. val: ${val}.`);
})
} catch (err) {
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
5. Delete data.
Use delete() to delete a KV pair.<br>Example:
Use **deleteSync()** to delete a KV pair.<br>Example:
```js
try {
preferences.delete('startup', (err) => {
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'.");
})
preferences.deleteSync('startup');
} catch (err) {
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
console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`);
}
```
en/application-dev/reference/apis/js-apis-cryptoFramework.md
浏览文件 @ 7ac51b30
......@@ -20,7 +20,7 @@ import cryptoFramework from "@ohos.security.cryptoFramework"
| Name | Value | Description |
| ------------------------------------- | -------- | ---------------------------- |
| INVALID_PARAMS | 401 | Invalid parameters. |
| INVALID_PARAMS | 401 | Invalid parameter. |
| NOT_SUPPORT | 801 | Unsupported operation. |
| ERR_OUT_OF_MEMORY | 17620001 | Memory error. |
| ERR_RUNTIME_ERROR | 17620002 | Runtime error. |
......@@ -58,7 +58,7 @@ Defines the child class of [ParamsSpec](#paramsspec). It is used as the paramete
| Name| Type | Readable| Writable| Description |
| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ |
| 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**
>
......@@ -66,7 +66,7 @@ Defines the child class of [ParamsSpec](#paramsspec). It is used as the paramete
## 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.
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -82,7 +82,7 @@ Defines the child class of [ParamsSpec](#paramsspec) for the GCM mode. It is use
## 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.
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -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_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_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.|
| 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.|
......@@ -494,7 +494,7 @@ Clears the keys in the memory. This API returns the result synchronously.
```js
let key; // 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>
......@@ -540,7 +540,6 @@ Defines an asymmetric key pair, which includes a public key and a private key. <
> **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 service must reference the **KeyPair** object instead of the internal **pubKey** or **priKey** object.
### Attributes
......@@ -916,8 +915,8 @@ Converts data into an asymmetric key. This API uses an asynchronous callback to
```js
import cryptoFramework from "@ohos.security.cryptoFramework"
let pubKeyArray = new Uint8Array([48,89,48,19,6,7,42,134,72,206,61,2,1,6,8,42,134,72,206,61,3,1,7,3,66,0,4,83,96,142,9,86,214,126,106,247,233,92,125,4,128,138,105,246,162,215,71,81,58,202,121,26,105,211,55,130,45,236,143,55,16,248,75,167,160,167,106,2,152,243,44,68,66,0,167,99,92,235,215,159,239,28,106,124,171,34,145,124,174,57,92]);
let priKeyArray = new Uint8Array([48,49,2,1,1,4,32,115,56,137,35,207,0,60,191,90,61,136,105,210,16,27,4,171,57,10,61,123,40,189,28,34,207,236,22,45,223,10,189,160,10,6,8,42,134,72,206,61,3,1,7]);
let pubKeyArray = new Uint8Array([48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7, 3, 66, 0, 4, 83, 96, 142, 9, 86, 214, 126, 106, 247, 233, 92, 125, 4, 128, 138, 105, 246, 162, 215, 71, 81, 58, 202, 121, 26, 105, 211, 55, 130, 45, 236, 143, 55, 16, 248, 75, 167, 160, 167, 106, 2, 152, 243, 44, 68, 66, 0, 167, 99, 92, 235, 215, 159, 239, 28, 106, 124, 171, 34, 145, 124, 174, 57, 92]);
let priKeyArray = new Uint8Array([48, 49, 2, 1, 1, 4, 32, 115, 56, 137, 35, 207, 0, 60, 191, 90, 61, 136, 105, 210, 16, 27, 4, 171, 57, 10, 61, 123, 40, 189, 28, 34, 207, 236, 22, 45, 223, 10, 189, 160, 10, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7]);
let pubKeyBlob = {data: pubKeyArray}; // Data of the public key.
let priKeyBlob = {data: priKeyArray}; // Data of the private key.
let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
......@@ -964,8 +963,8 @@ Converts data into an asymmetric key. This API uses a promise to return the resu
```js
import cryptoFramework from "@ohos.security.cryptoFramework"
let pubKeyArray = new Uint8Array([48,89,48,19,6,7,42,134,72,206,61,2,1,6,8,42,134,72,206,61,3,1,7,3,66,0,4,83,96,142,9,86,214,126,106,247,233,92,125,4,128,138,105,246,162,215,71,81,58,202,121,26,105,211,55,130,45,236,143,55,16,248,75,167,160,167,106,2,152,243,44,68,66,0,167,99,92,235,215,159,239,28,106,124,171,34,145,124,174,57,92]);
let priKeyArray = new Uint8Array([48,49,2,1,1,4,32,115,56,137,35,207,0,60,191,90,61,136,105,210,16,27,4,171,57,10,61,123,40,189,28,34,207,236,22,45,223,10,189,160,10,6,8,42,134,72,206,61,3,1,7]);
let pubKeyArray = new Uint8Array([48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7, 3, 66, 0, 4, 83, 96, 142, 9, 86, 214, 126, 106, 247, 233, 92, 125, 4, 128, 138, 105, 246, 162, 215, 71, 81, 58, 202, 121, 26, 105, 211, 55, 130, 45, 236, 143, 55, 16, 248, 75, 167, 160, 167, 106, 2, 152, 243, 44, 68, 66, 0, 167, 99, 92, 235, 215, 159, 239, 28, 106, 124, 171, 34, 145, 124, 174, 57, 92]);
let priKeyArray = new Uint8Array([48, 49, 2, 1, 1, 4, 32, 115, 56, 137, 35, 207, 0, 60, 191, 90, 61, 136, 105, 210, 16, 27, 4, 171, 57, 10, 61, 123, 40, 189, 28, 34, 207, 236, 22, 45, 223, 10, 189, 160, 10, 6, 8, 42, 134, 72, 206, 61, 3, 1, 7]);
let pubKeyBlob = {data: pubKeyArray}; // Data of the public key.
let priKeyBlob = {data: priKeyArray}; // Data of the private key.
let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256");
......@@ -1297,8 +1296,8 @@ Creates a [Cipher](#cipher) instance based on the specified algorithm. <br>For d
> **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.
> 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.
> 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. 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**
......@@ -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.
- 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
......@@ -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.
> 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.
> 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).
> 3. RSA asymmetric encryption and decryption do not support **update()**.
> 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 or SM2 asymmetric encryption and decryption do not support **update()**.
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -1501,17 +1500,15 @@ cipher.update(plainText, (err, output) => { // Example of the encryption p
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.
This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
Updates the data to encrypt or decrypt by segment. This API uses a promise to return the encrypted or decrypted data. <br>This API can be called only after the [Cipher](#cipher) instance is initialized by using [init()](init-2).
> **NOTE**
>
> 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.
> 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).
> 3. RSA asymmetric encryption and decryption do not support **update()**.
> 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 or SM2 asymmetric encryption and decryption do not support **update()**.
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -1568,19 +1565,19 @@ cipher.update(plainText)
doFinal(data: DataBlob, callback: AsyncCallback\<DataBlob>): void
(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 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**
>
> 1. In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. <br>For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
> 2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
> 3. The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
> 4. For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#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).
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -1624,19 +1621,19 @@ cipher.doFinal(data, (err, output) => {
doFinal(data: DataBlob): Promise\<DataBlob>
(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 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**
>
> 1. In symmetric encryption or decryption, calling **doFinal()** means the end of an encryption or decryption process, and the [Cipher](#cipher) instance state will be cleared. To start a new encryption or decryption operation, you must call [init()](#init-2) to pass in a complete parameter list for initialization. <br>For example, if the same symmetric key is used for a **Cipher** instance to perform encryption and then decryption. After the encryption is complete, the **params** in **init** for decryption must be set instead of being **null**.
> 2. If a decryption fails, check whether the data to be encrypted and decrypted matches the parameters in **[init](#init-2)**. For the GCM mode, check whether the **authTag** obtained after encryption is obtained from the **GcmParamsSpec** for decryption.
> 3. The result of **doFinal()** may be **null**. To avoid exceptions, determine whether the result is **null** before using the **.data** field to access the **doFinal()** result.
> 4. For details about the sample code for calling **doFinal()** multiple times during RSA asymmetric encryption and decryption, see [Encrypting and Decrypting Data](../../security/cryptoFramework-guidelines.md#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).
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -1815,7 +1812,7 @@ let mdName = cipher.getCipherSpec(cryptoFramework.CipherSpecItem.OAEP_MD_NAME_ST
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).
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -1823,7 +1820,7 @@ Creates a **Sign** instance. For details about the supported specifications, see
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------------------------------------------------------ |
| 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**
......@@ -1846,11 +1843,11 @@ import cryptoFramework from "@ohos.security.cryptoFramework"
let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256");
let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256");
let signer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256");
let singer3 = cryptoFramework.createSign("ECC224|SHA256");
let signer3 = cryptoFramework.createSign("ECC224|SHA256");
let singer4 = cryptoFramework.createSign("DSA2048|SHA256");
let signer4 = cryptoFramework.createSign("DSA2048|SHA256");
```
## Sign
......@@ -1936,7 +1933,9 @@ Updates the data to be signed. This API uses a callback to complete the update.
> **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).
**System capability**: SystemCapability.Security.CryptoFramework
......@@ -2071,9 +2070,9 @@ function signMessageCallback() {
rsaGenerator.generateKeyPair(function (err, keyPair) {
globalKeyPair = keyPair;
let priKey = globalKeyPair.priKey;
signer.init(priKey, function (err, data) {
signer.update(input1, function (err, data) { // Add the first segment of the data.
signer.sign(input2, function (err, data) { // Add the second segment of the data, and sign input1 and input2.
signer.init(priKey, err => {
signer.update(input1, err => { // add first segment of data
signer.sign(input2, function (err, data) { // add second segment of data, sign input1 and input2
SignMessageBlob = data;
AlertDialog.show({message: "res" + SignMessageBlob.data});
});
......@@ -2208,7 +2207,7 @@ Creates a **Verify** instance. <br>For details about the supported specification
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ------------------------------------------------------------ |
| 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**
......@@ -2345,7 +2344,7 @@ Updates the data for signature verification. This API uses a promise to return t
> **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>
> 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 {
// Set algName based on the algorithm supported.
md = cryptoFramework.createMd("SHA256");
} 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;
try {
md = cryptoFramework.createMd("SHA256");
} 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);
......@@ -2815,7 +2814,7 @@ var md;
try {
md = cryptoFramework.createMd("SHA256");
} 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);
......@@ -2856,7 +2855,7 @@ var md;
try {
md = cryptoFramework.createMd("SHA256");
} 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);
......@@ -2905,7 +2904,7 @@ var md;
try {
md = cryptoFramework.createMd("SHA256");
} 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);
......@@ -2950,7 +2949,7 @@ var md;
try {
md = cryptoFramework.createMd("SHA256");
} 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);
......@@ -3005,7 +3004,7 @@ try {
// Set algName based on the algorithm supported.
mac = cryptoFramework.createMac("SHA256");
} 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;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
var KeyBlob;
var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
......@@ -3104,7 +3103,7 @@ var mac;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
console.error("Mac algName is: " + mac.algName);
......@@ -3156,7 +3155,7 @@ var mac;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
......@@ -3217,7 +3216,7 @@ var mac;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
console.error("Mac algName is: " + mac.algName);
......@@ -3268,7 +3267,7 @@ var mac;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128");
symKeyGenerator.convertKey(KeyBlob, (err, symKey) => {
......@@ -3326,7 +3325,7 @@ var mac;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
console.error("Mac algName is: " + mac.algName);
......@@ -3379,7 +3378,7 @@ var mac;
try {
mac = cryptoFramework.createMac("SHA256");
} catch (error) {
console.error("[Promise]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
console.error("Mac algName is: " + mac.algName);
......@@ -3433,7 +3432,7 @@ import cryptoFramework from "@ohos.security.cryptoFramework"
try {
var rand = cryptoFramework.createRandom();
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
```
......@@ -3481,7 +3480,7 @@ var rand;
try {
rand = cryptoFramework.createRandom();
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
rand.generateRandom(12, (err, randData) => {
if (err) {
......@@ -3529,7 +3528,7 @@ var rand;
try {
rand = cryptoFramework.createRandom();
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
var promiseGenerateRand = rand.generateRandom(12);
......@@ -3577,7 +3576,7 @@ var rand;
try {
rand = cryptoFramework.createRandom();
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
try {
......@@ -3619,18 +3618,18 @@ var rand;
try {
rand = cryptoFramework.createRandom();
} catch (error) {
console.error("[Callback]: error code: " + error.code + ", message is: " + error.message);
console.error("[Sync]: error code: " + error.code + ", message is: " + error.message);
}
rand.generateRandom(12, (err, randData) => {
if (err) {
console.error("[Callback] err: " + err.code);
} else {
console.error("[Callback]: generate random result: " + randData.data);
console.info("[Callback]: generate random result: " + randData.data);
try {
rand.setSeed(randData);
} catch (error) {
console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message);
console.error("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message);
}
}
});
......
en/application-dev/reference/apis/js-apis-data-cloudData.md
浏览文件 @ 7ac51b30
......@@ -18,7 +18,7 @@ import cloudData from '@ohos.data.cloudData';
## 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.
......@@ -26,8 +26,8 @@ Enumerates the actions for clearing the cloud information about the local data.
| Name | Description |
| --------- | ---------------------------- |
| CLEAR_CLOUD_INFO | Clear the cloud ID information.|
| 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_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 the data downloaded from the cloud, excluding the cloud data that has been modified locally. |
## Config
......@@ -49,7 +49,7 @@ Enables device-cloud synergy. This API uses an asynchronous callback to return t
| Name | Type | Mandatory| Description |
| --------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
......@@ -87,7 +87,7 @@ Enables device-cloud synergy. This API uses a promise to return the result.
| Name | Type | Mandatory| Description |
| --------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| 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.|
**Return value**
......@@ -127,8 +127,8 @@ Disables device-cloud synergy. This API uses an asynchronous callback to return
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ---------------- |
| accountId | string | Yes | ID of the target cloud.|
| --------- | ------------------------- | ---- | -------------------- |
| accountId | string | Yes | ID of the cloud account.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
......@@ -163,8 +163,8 @@ Disables device-cloud synergy. This API uses a promise to return the result.
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | ---------------- |
| accountId | string | Yes | ID of the target cloud.|
| --------- | ------ | ---- | -------------------- |
| accountId | string | Yes | ID of the cloud account.|
**Return value**
......@@ -203,8 +203,8 @@ Changes the device-cloud synergy switch for an application. This API uses an asy
| Name | Type | Mandatory| Description |
| --------- | ------------------------------- | ---- | ---------------------------- |
| accountId | string | Yes | ID of the target cloud.|
| bundleName| string | Yes | Name of the target application.|
| accountId | string | Yes | ID of the cloud account.|
| 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.|
| callback | AsyncCallback&lt;void&gt; | 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
| Name | Type | Mandatory| Description |
| --------- | ------------------------------- | ---- | ---------------------------- |
| accountId | string | Yes | ID of the target cloud.|
| bundleName| string | Yes | Name of the target application.|
| accountId | string | Yes | ID of the cloud account.|
| 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.|
**Return value**
......@@ -283,9 +283,9 @@ Notifies the data changes in the cloud. This API uses an asynchronous callback t
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- | ---------------- |
| accountId | string | Yes | ID of the target cloud.|
| bundleName | string | Yes | Name of the target application. |
| ---------- | ------------------------- | ---- | -------------------- |
| accountId | string | Yes | ID of the cloud account.|
| bundleName | string | Yes | Bundle name of the application. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
......@@ -321,9 +321,9 @@ Notifies the data changes in the cloud. This API uses a promise to return the re
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------ | ---- | ---------------- |
| accountId | string | Yes | ID of the target cloud.|
| bundleName | string | Yes | Name of the target application. |
| ---------- | ------ | ---- | -------------------- |
| accountId | string | Yes | ID of the cloud account.|
| bundleName | string | Yes | Bundle name of the application. |
**Return value**
......@@ -346,3 +346,88 @@ try {
console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`);
}
```
### clean
static clean(accountId: string, appActions: {[bundleName: string]: Action}, callback: AsyncCallback&lt;void&gt;):void
Clears the cloud data locally. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.CLOUDDATA_CONFIG
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------------- | ---- | -------------------------------- |
| 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&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
```js
let action = cloudData.Action;
let account = "test_id";
let bundleName1 = "test_bundleName1";
let bundleName2 = "test_bundleName2";
let appActions = { [bundleName1]: action.CLEAR_CLOUD_INFO, [bundleName2]: action.CLEAR_CLOUD_DATA_AND_INFO };
try {
cloudData.Config.clean(account, appActions, function (err) {
if (err === undefined) {
console.info('Succeeding in cleaning cloud data');
} else {
console.error(`Failed to clean cloud data. Code: ${err.code}, message: ${err.message}`);
}
});
} catch (error) {
console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`);
}
```
### clean
static clean(accountId: string, appActions: {[bundleName: string]: Action}): Promise&lt;void&gt;
Clears the cloud data locally. This API uses a promise to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.CLOUDDATA_CONFIG
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ----------------------------------------- | ---- | -------------------------------- |
| 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.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example**
```js
let action = cloudData.Action;
let account = "test_id";
let bundleName1 = "test_bundleName1";
let bundleName2 = "test_bundleName2";
let appActions = { [bundleName1]: action.CLEAR_CLOUD_INFO, [bundleName2]: action.CLEAR_CLOUD_DATA_AND_INFO };
try {
cloudData.Config.clean(account, appActions).then(() => {
console.info('Succeeding in cleaning cloud data');
}).catch((err) => {
console.error(`Failed to clean cloud data. Code: ${err.code}, message: ${err.message}`);
});
} catch (error) {
console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`);
}
```
en/application-dev/reference/apis/js-apis-data-preferences.md
浏览文件 @ 7ac51b30
# @ohos.data.preferences (User Preferences)
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.
......@@ -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). |
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | 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&lt;[Preferences](#preferences)&gt; | 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**
......@@ -310,7 +310,7 @@ class EntryAbility extends UIAbility {
removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void
Removes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result.
Removes a **Preferences** instance from the cache. This API uses an asynchronous callback to return the result.
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
......@@ -373,7 +373,7 @@ class EntryAbility extends UIAbility {
removePreferencesFromCache(context: Context, name: string): Promise&lt;void&gt;
Removes a **Preferences** instance from the memory. This API uses a promise to return the result.
Removes a **Preferences** instance from the cache. This API uses a promise to return the result.
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
......@@ -434,9 +434,58 @@ class EntryAbility extends UIAbility {
}
```
## data_preferences.removePreferencesFromCacheSync<sup>10+</sup>
removePreferencesFromCacheSync(context: Context, name: string): void
Synchronously removes a **Preferences** instance from the cache.
The deleted **Preferences** instance cannot be used to perform data operations. Otherwise, data inconsistency will be caused.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------- |
| 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.|
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
data_preferences.removePreferencesFromCacheSync(context, 'mystore');
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.removePreferencesFromCacheSync(this.context, 'mystore');
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## 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).
......@@ -445,7 +494,7 @@ Before calling any method of **Preferences**, you must obtain a **Preferences**
get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -478,7 +527,7 @@ try {
get(key: string, defValue: ValueType): Promise&lt;ValueType&gt;
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -510,11 +559,43 @@ try {
}
```
### getSync<sup>10+</sup>
getSync(key: string, defValue: ValueType): ValueType
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| 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.|
**Return value**
| Type | Description |
| ----------------------------------- | ----------------------------- |
| [ValueType](#valuetype) | Returns the value obtained.|
**Example**
```js
try {
let value = preferences.getSync('startup', 'default');
console.info("Obtained the value of 'startup'. Data: " + value);
} catch(err) {
console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message);
}
```
### getAll
getAll(callback: AsyncCallback&lt;Object&gt;): void;
Obtains an **Object** instance that contains all KV pairs. This API uses an asynchronous callback to return the result.
Obtains all KV pairs from the cached **Preferences** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -522,7 +603,7 @@ Obtains an **Object** instance that contains all KV pairs. This API uses an asyn
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;Object&gt; | 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&lt;Object&gt; | 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**
......@@ -547,7 +628,7 @@ try {
getAll(): Promise&lt;Object&gt;
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -555,7 +636,7 @@ Obtains an **Object** instance that contains all KV pairs. This API uses a promi
| Type | Description |
| --------------------- | ------------------------------------------- |
| Promise&lt;Object&gt; | Promise used to return the **Object** instance obtained.|
| Promise&lt;Object&gt; | Promise used to return the KV pairs obtained.|
**Example**
......@@ -574,11 +655,38 @@ try {
}
```
### getAllSync<sup>10+</sup>
getAllSync(): Object
Synchronously obtains all KV pairs from the cached **Preferences** instance.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Return value**
| Type | Description |
| --------------------- | ------------------------------------------- |
| Object | Returns all KV pairs obtained.|
**Example**
```js
try {
let value = preferences.getAllSync();
let allKeys = Object.keys(value);
console.info('getAll keys = ' + allKeys);
console.info("getAll object = " + JSON.stringify(value));
} catch (err) {
console.info("Failed to obtain all KV pairs. code =" + err.code + ", message =" + err.message);
}
```
### put
put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -611,7 +719,7 @@ try {
put(key: string, value: ValueType): Promise&lt;void&gt;
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -644,11 +752,37 @@ try {
```
### putSync<sup>10+</sup>
putSync(key: string, value: ValueType): void
Synchronously writes data to the cached **Preferences** instance. You can use [flush](#flush) to persist the **Preferences** instance.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------------------- | ---- | ------------------------------------------------------------ |
| 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);
}
```
### has
has(key: string, callback: AsyncCallback&lt;boolean&gt;): void
Checks whether this **Preferences** instance contains a KV pair with the given key. This API uses an asynchronous callback to return the result.
Checks whether the cached **Preferences** instance contains the KV pair of the given key. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -684,7 +818,7 @@ try {
has(key: string): Promise&lt;boolean&gt;
Checks whether this **Preferences** instance contains a KV pair with the given key. This API uses a promise to return the result.
Checks whether the cached **Preferences** instance contains the KV pair of the given key. This API uses a promise to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -720,11 +854,47 @@ try {
```
### hasSync<sup>10+</sup>
hasSync(key: string): boolean
Synchronously checks whether the cached **Preferences** instance contains the KV pair of the given key.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------- |
| key | string | Yes | Key of the data to check. It cannot be empty.|
**Return value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| boolean | If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.|
**Example**
```js
try {
let isExist = preferences.hasSync('startup');
if (isExist) {
console.info("The key 'startup' is contained.");
} else {
console.info("The key 'startup' is not contained.");
}
} catch(err) {
console.info("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
}
```
### delete
delete(key: string, callback: AsyncCallback&lt;void&gt;): void
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -756,7 +926,7 @@ try {
delete(key: string): Promise&lt;void&gt;
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -788,11 +958,36 @@ try {
```
### deleteSync<sup>10+</sup>
deleteSync(key: string): void
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------- |
| key | string | Yes | Key of the KV pair to delete. It cannot be empty.|
**Example**
```js
try {
preferences.deleteSync('startup');
} catch(err) {
console.info("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message);
}
```
### flush
flush(callback: AsyncCallback&lt;void&gt;): void
Saves the data of this **Preferences** instance to a file asynchronously. This API uses an asynchronous callback to return the result.
Flushes the data in the cached **Preferences** instance to the persistent file. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -823,7 +1018,7 @@ try {
flush(): Promise&lt;void&gt;
Saves the data of this **Preferences** instance to a file asynchronously. This API uses a promise to return the result.
Flushes the data in the cached **Preferences** instance to the persistent file. This API uses a promise to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -853,7 +1048,7 @@ try {
clear(callback: AsyncCallback&lt;void&gt;): void
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -884,7 +1079,7 @@ try {
clear(): Promise&lt;void&gt;
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.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -910,6 +1105,25 @@ try {
```
### clearSync<sup>10+</sup>
clearSync(): void
Synchronously clears all data in the cached **Preferences** instance. You can use [flush](#flush) to persist the **Preferences** instance.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Example**
```js
try {
preferences.clearSync();
} catch(err) {
console.info("Failed to clear. code =" + err.code + ", message =" + err.message);
}
```
### on('change')
on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void
......
en/application-dev/reference/apis/js-apis-data-storage.md
浏览文件 @ 7ac51b30
......@@ -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 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
......@@ -188,7 +186,7 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------------- |
| path | string | Yes | Path of the target file.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
......@@ -230,7 +228,7 @@ Deletes the singleton **Storage** instance of a file from the memory, and delete
| Type | Description |
| ------------------- | ------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value. |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
......@@ -295,7 +293,7 @@ Removes the singleton **Storage** instance of a file from the cache. The removed
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------------- |
| path | string | Yes | Path of the target file.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
......@@ -337,7 +335,7 @@ Removes the singleton **Storage** instance of a file from the cache. The removed
| Type | Description |
| ------------------- | ------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value. |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
......@@ -490,7 +488,7 @@ Obtains the **Storage** instance corresponding to the specified file, writes dat
| -------- | ------------------------- | ---- | ----------------------------------------- |
| key | string | Yes | Key of the data. It cannot be empty. |
| value | [ValueType](#valuetype) | Yes | New value to store. It can be a number, string, or Boolean value.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
......@@ -524,7 +522,7 @@ Obtains the **Storage** instance corresponding to the specified file, writes dat
| Type | Description |
| ------------------- | --------------------------- |
| Promise&lt;void&gt; | Promise that returns no value. |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
......@@ -672,7 +670,7 @@ Deletes data with the specified key from this storage object. This API uses an a
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------- |
| key | string | Yes | Key of the data. It cannot be empty.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Example**
......@@ -705,7 +703,7 @@ Deletes data with the specified key from this storage object. This API uses a pr
| Type | Description |
| ------------------- | --------------------------- |
| Promise&lt;void&gt; | Promise that returns no value. |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
......@@ -746,7 +744,7 @@ Saves the modification of this object to the **Storage** instance and synchroniz
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result.|
**Example**
......@@ -773,7 +771,7 @@ Saves the modification of this object to the **Storage** instance and synchroniz
| Type | Description |
| ------------------- | --------------------------- |
| Promise&lt;void&gt; | Promise that returns no value. |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
......@@ -814,7 +812,7 @@ Clears this **Storage** object. This API uses an asynchronous callback to return
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result.|
**Example**
......@@ -840,7 +838,7 @@ Clears this **Storage** object. This API uses a promise to return the result.
**Return value**
| Type | Description |
| ------------------- | --------------------------- |
| Promise&lt;void&gt; | Promise that returns no value. |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
......
en/application-dev/reference/apis/js-apis-privacyManager.md
浏览文件 @ 7ac51b30
......@@ -267,7 +267,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| 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. |
| 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. |
......@@ -315,7 +315,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| 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. |
| 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. |
......@@ -370,7 +370,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| 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. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100004 | The interface is not used with |
......@@ -418,7 +418,7 @@ For details about the error codes, see [Ability Access Control Error Codes](../e
| 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. |
| 12100003 | The specified permission does not exist or is not an user_grant permission. |
| 12100004 | The interface is not used with |
......@@ -551,8 +551,8 @@ Represents the request for querying permission usage records.
| Name | Type | Mandatory | Description |
| -------- | -------------- | ---- | ---------------------------------------- |
| 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.|
| deviceId | string | No | ID of the device hosting the target application.<br> The default value is the local device ID. |
| 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. |
| bundleName | string | No | Bundle name of the target application.<br>By default, all applications are queried.|
| permissionNames | Array&lt;Permissions&gt; | 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.|
......
en/application-dev/reference/apis/js-apis-rpc.md
浏览文件 @ 7ac51b30
......@@ -247,7 +247,7 @@ Obtains the data size of this **MessageSequence** object.
| Type | Description |
| ------ | ----------------------------------------------- |
| number | Size of the **MessageSequence** object obtained, in bytes.|
| number | Size of the **MessageSequence** instance obtained, in bytes.|
**Example**
......@@ -293,6 +293,14 @@ Sets the size of the data contained in this **MessageSequence** object.
| ------ | ------ | ---- | ------ |
| size | number | Yes | Data size to set, in bytes.|
**Error codes**
For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md).
| ID| Error Message|
| -------- | -------- |
| 1900009 | write data to message sequence failed |
**Example**
```ts
......@@ -326,6 +334,7 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
| ID| Error Message|
| -------- | -------- |
| 1900009 | write data to message sequence failed |
| 1900011 | parcel memory alloc failed |
**Example**
......@@ -452,6 +461,12 @@ Moves the read pointer to the specified position.
| ------ | ------ | ---- | ------- |
| pos | number | Yes | Position from which data is to read.|
**Error codes**
| ID| Error Message|
| -------- | -------- |
| 1900010 | read data from message sequence failed |
**Example**
```ts
......@@ -484,6 +499,12 @@ Moves the write pointer to the specified position.
| ------ | ------ | ---- | ----- |
| pos | number | Yes | Position from which data is to write.|
**Error codes**
| ID| Error Message|
| -------- | -------- |
| 1900009 | write data to message sequence failed |
**Example**
```ts
......@@ -2718,7 +2739,6 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
}
```
### closeFileDescriptor<sup>9+</sup>
static closeFileDescriptor(fd: number): void
......@@ -2805,7 +2825,6 @@ Checks whether this **MessageSequence** object contains file descriptors.
**Example**
```ts
import fs from '@ohos.file.fs';
let sequence = new rpc.MessageSequence();
......@@ -2926,8 +2945,8 @@ Writes an anonymous shared object to this **MessageSequence** object.
For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md).
| ID| Error Message|
| -------- | ------- |
| 1900003 | write to ashmem failed |
| -------- | -------- |
| 1900009 | write data to message sequence failed |
**Example**
......@@ -2948,7 +2967,6 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
}
```
### readAshmem
readAshmem(): Ashmem
......@@ -2969,7 +2987,7 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
| ID| Error Message|
| -------- | -------- |
| 1900004 | read from ashmem failed |
| 1900010 | read data from message sequence failed |
**Example**
......@@ -3263,7 +3281,6 @@ Writes an interface token to this **MessageParcel** object. The remote object ca
console.log("RpcServer: writeInterfaceToken is " + result);
```
### readInterfaceToken
readInterfaceToken(): string
......@@ -5825,7 +5842,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| ------- | -------------------------------- |
| boolean | Returns **true** if the message is sent successfully; returns **false** otherwise.|
### sendRequest<sup>8+(deprecated)</sup>
>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
| Name | Type | Mandatory| Description |
| ------- | ---------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| -------------------------------- | --------------------------------------------- |
| Promise&lt;SendRequestResult&gt; | Promise used to return the **sendRequestResult** object.|
### sendMessageRequest<sup>9+</sup>
sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption): Promise&lt;RequestResult&gt;
......@@ -5875,7 +5890,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| 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
| ---------------------------- | ----------------------------------------- |
| Promise&lt;RequestResult&gt; | Promise used to return the **requestResult** object.|
### sendMessageRequest<sup>9+</sup>
sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback&lt;RequestResult&gt;): void
......@@ -5899,7 +5913,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| ID| Error Message|
| -------- | -------- |
| 1900008 | proxy or remote object is invalid |
| 1900005 | only proxy object permitted |
### addDeathrecipient<sup>(deprecated)</sup>
......@@ -5971,7 +5985,6 @@ Adds a callback for receiving death notifications of the remote object. This met
| ------- | ---------------------------------------- |
| boolean | Returns **true** if the callback is added successfully; returns **false** otherwise.|
### unregisterDeathRecipient<sup>9+</sup>
unregisterDeathRecipient(recipient: DeathRecipient, flags: number): void
......@@ -5993,7 +6006,7 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
| ID| Error Message|
| -------- | -------- |
| 1900008 | proxy or remote object is invalid |
| 1900005 | only proxy object permitted |
### removeDeathRecipient<sup>(deprecated)</sup>
......@@ -6040,7 +6053,6 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode
| -------- | -------- |
| 1900008 | proxy or remote object is invalid |
### getInterfaceDescriptor<sup>(deprecated)</sup>
>This API is no longer maintained since API version 9. You are advised to use [getDescriptor](#getdescriptor9).
......@@ -6057,7 +6069,6 @@ Obtains the interface descriptor (which is a string) of this object.
| ------ | ---------------- |
| string | Interface descriptor obtained.|
### isObjectDead
isObjectDead(): boolean
......@@ -6072,7 +6083,6 @@ Checks whether this object is dead.
| ------- | ---------------------------------- |
| boolean | Returns **true** if the object is dead; returns **false** otherwise.|
## RemoteProxy
Provides APIs to implement **IRemoteObject**.
......@@ -6101,7 +6111,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
**System capability**: SystemCapability.Communication.IPC.Core
| Name | Value | Description |
| ------------- | ---- | ----------------------------------------------------------- |
| TF_SYNC | 0 | Synchronous call. |
| TF_ASYNC | 1 | Asynchronous call. |
| TF_ACCEPT_FDS | 0x10 | Indication to **sendMessageRequest<sup>9+</sup>** for returning the file descriptor.|
| TF_WAIT_TIME | 8 | Default waiting time, in seconds. |
| ------------- | --------- | ----------------------------------------------------------- |
| TF_SYNC | 0 (0x00) | Synchronous call. |
| TF_ASYNC | 1 (0x01) | Asynchronous call. |
| TF_ACCEPT_FDS | 16 (0x10) | Indication to **sendMessageRequest<sup>9+</sup>** for returning the file descriptor.|
| TF_WAIT_TIME | 4 (0x4) | Default waiting time, in seconds. |
### constructor<sup>9+</sup>
......@@ -7101,7 +7110,6 @@ A constructor used to create a **MessageOption** object.
| ------ | ------- | ---- | -------------------------------------- |
| async | boolean | No | Call flag, which can be synchronous or asynchronous. The default value is **synchronous**.|
**Example**
```ts
......@@ -7391,7 +7399,6 @@ Obtains the caller's token ID, which is used to verify the caller identity.
}
```
### getCallingDeviceID
static getCallingDeviceID(): string
......@@ -7484,7 +7491,6 @@ Flushes all suspended commands from the specified **RemoteProxy** to the corresp
| ------ | ------------------------------- | ---- | ------------------- |
| object | [IRemoteObject](#iremoteobject) | Yes | **RemoteProxy** specified. |
**Example**
```ts
......@@ -7577,7 +7583,6 @@ Changes the UID and PID of the remote user to the UID and PID of the local user.
}
```
### restoreCallingIdentity<sup>9+</sup>
static restoreCallingIdentity(identity: string): void
......@@ -7667,7 +7672,6 @@ A constructor used to create a **RemoteObject** object.
| ---------- | ------ | ---- | ------------ |
| descriptor | string | Yes | Interface descriptor.|
### sendRequest<sup>(deprecated)</sup>
>This API is no longer maintained since API version 9. You are advised to use [sendMessageRequest](#sendmessagerequest9).
......@@ -7682,7 +7686,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| ------------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. |
| 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
| Name | Type | Mandatory| Description |
| ------------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- |
| 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. |
| reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. |
| options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. |
......@@ -8239,7 +8243,6 @@ Obtains the interface descriptor.
| ------------- | --------------------------------------------- |
| IRemoteBroker | **IRemoteBroker** object bound to the specified interface token.|
**Example**
```ts
......@@ -8612,7 +8615,6 @@ Creates an **Ashmem** object by copying the file descriptor of an existing **Ash
| ------ | ---------------------- |
| Ashmem | **Ashmem** object created.|
**Example**
```ts
......
en/application-dev/reference/apis/js-apis-useriam-userauth.md
浏览文件 @ 7ac51b30
......@@ -13,6 +13,671 @@ The **userIAM.userAuth** module provides user authentication capabilities in ide
import userIAM_userAuth from '@ohos.userIAM.userAuth';
```
## WindowModeType<sup>10+</sup>
Enumerates the window types of the authentication widget.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Value | Description |
| ---------- | ---- | ---------- |
| DIALOG_BOX | 1 | Dialog box.|
| FULLSCREEN | 2 | Full screen.|
## AuthParam<sup>10+</sup>
Defines the user authentication parameters.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description |
| -------------- | ---------------------------------- | ---- | -------------------------------------- |
| challenge | Uint8Array | Yes | Challenge value. The maximum length is 32 bytes. The value can be **null**.|
| authType | [UserAuthType](#userauthtype8)[] | Yes | Authentication type. |
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. |
## WidgetParam<sup>10+</sup>
Defines the parameters of the authentication widget.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description |
| -------------------- | ----------------------------------- | ---- | -------------------- |
| title | string | Yes | Title of the authentication component. |
| navigationButtonText | string | No | Description text of the navigation button.|
| windowModeType | [WindowModeType](#windowmodetype10) | No | Type of the window. |
## UserAuthResult<sup>10+</sup>
Defines the user authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Type | Mandatory| Description |
| -------- | ------------------------------ | ---- | ------------------------------------------------------------ |
| 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).|
| token | Uint8Array | No | Authentication token information. |
| authType | [UserAuthType](#userauthtype8) | No | Authentication type. |
## IAuthCallback<sup>10+</sup>
Provides callbacks to return the authentication result.
### onResult<sup>10+</sup>
onResult(result: UserAuthResult): void
Called to return the authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ---------------------------------- | ---- | ---------- |
| result | [UserAuthResult](userauthresult10) | Yes | Authentication result.|
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
try {
userAuthInstance.on('result', {
callback: onResult(result) {
console.log("authV10 result " + result.result);
console.log("authV10 token " + result.token);
console.log("authV10 authType " + result.authType);
}
});
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed" + error);
//do error
}
```
## UserAuthInstance<sup>10+</sup>
Provides APIs for user authentication. The user authentication widget is supported.
Before using the APIs, you need to obtain a **UserAuthInstance** instance by using [getUserAuthInstance](#useriam_userauthgetuserauthinstance10).
### on<sup>10+</sup>
on(type: 'result', callback: IAuthCallback): void
Subscribes to the user authentication result.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | ------------------------------------------ |
| type | 'result' | Yes | Event type to subscribe to. **result** indicates the authentication result.|
| callback | [IAuthCallback](iauthcallback10) | Yes | Callback invoked to return the user authentication result. |
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
try {
userAuthInstance.on('result', {
callback: onResult(result) {
console.log("authV10 result " + result.result);
console.log("authV10 token " + result.token);
console.log("authV10 authType " + result.authType);
}
});
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed" + error);
//do error
}
```
### off<sup>10+</sup>
off(type: 'result', callback?: IAuthCallback): void
Unsubscribes from the user authentication result.
> **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.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | ------------------------------------------ |
| type | 'result' | Yes | Event type to unsubscribe from. **result** indicates the authentication result.|
| callback | [IAuthCallback](iauthcallback10) | No | Callback for the user authentication result. |
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
// Subscribe to the authentication result.
try {
userAuthInstance.on('result', {
callback: onResult(result) {
console.log("authV10 result " + result.result);
console.log("authV10 token " + result.token);
console.log("authV10 authType " + result.authType);
}
});
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed" + error);
//do error
}
// Unsubscribe from the authentication result.
try {
userAuthInstance.off('result');
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed" + error);
//do error
}
```
### start<sup>10+</sup>
start(): void
Starts an authentication.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------------------------------ |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500001 | Authentication failed. |
| 12500002 | General operation error. |
| 12500003 | The operation is canceled. |
| 12500004 | The operation is time-out. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
| 12500007 | The authentication task is busy. |
| 12500009 | The authenticator is locked. |
| 12500010 | The type of credential has not been enrolled. |
| 12500011 | The authentication is canceled from widget's navigation button. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
try {
userAuthInstance.start();
console.info("userAuthInstanceV10 start auth success");
} catch (error) {
console.info("userAuthInstanceV10 start auth failed, error = " + error);
//do error
}
```
### cancel<sup>10+</sup>
cancel(): void
Cancels this authentication.
> **NOTE**<br>**UserAuthInstance** must be the instance being authenticated.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Error codes**
| ID| Error Message |
| -------- | ------------------------------- |
| 201 | Permission verification failed. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
let userAuthInstance;
try {
userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
// Start user authentication.
try {
userAuthInstance.start();
console.info("userAuthInstanceV10 start auth success");
} catch (error) {
console.info("userAuthInstanceV10 start auth failed, error = " + error);
//do error
}
// Cancel the authentication.
try {
userAuthInstance.cancel();
console.info("cancel auth success");
} catch (error) {
console.info("cancel auth failed, error = " + error);
//do error
}
```
## userIAM_userAuth.getUserAuthInstance<sup>10+</sup>
getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance
Obtains a [UserAuthInstance](#userauthinstance10) instance for user authentication. The user authentication widget is supported.
> **NOTE**<br>
> A **UserAuthInstance** instance can be used for an authentication only once.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------- | ---- | -------------------------------------- |
| authParam | [AuthParam](authparam10) | Yes | Challenge value. The maximum length is 32 bytes. The value can be **null**.|
| widgetParam | [WidgetParam](#widgetparam10) | Yes | Authentication type. Only **FACE** is supported. |
**Return value**
| Type | Description |
| --------------------------------------- | ------------ |
| [UserAuthInstance](#userauthinstance10) | **UserAuthInstance** instance obtained.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | ------------------------------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
| 12500005 | The authentication type is not supported. |
| 12500006 | The authentication trust level is not supported. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
AuthParam authParam = {
challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
authType: userIAM_userAuth.UserAuthType.PIN;
authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1;
}
WidgetParam widgetParam = {
title: "Enter Password";
windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX;
}
try {
let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam);
console.info("get userAuth instance success");
} catch (error) {
console.info("get userAuth instance failed, error = " + error);
}
```
## NoticeType<sup>10+</sup>
Defines the type of the user authentication notification.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Value | Description |
| ------------- | ---- | -------------------- |
| WIDGET_NOTICE | 1 | Notification from the user authentication widget.|
## userIAM_userAuth.sendNotice<sup>10+</sup>
sendNotice(noticeType: NoticeType, eventData: string): void
Sends a notification from the user authentication widget.
**Required permissions**: ohos.permission.SUPPORT_USER_AUTH
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------- | ---- | ---------- |
| noticeType | [NoticeType](#noticetype) | Yes | Notification type.|
| eventData | string | Yes | Event data.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | --------------------------------------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let noticeType = userIAM_userAuth.NoticeType.WIDGET_NOTICE;
sendNotice(noticeType, {"eventData" : "EVENT_AUTH_TYPE_READY"});
```
## UserAuthWidgetMgr<sup>10+</sup>
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.
### on<sup>10+</sup>
on(type: 'command', callback: IAuthWidgetCallback): void
Subscribes to commands from the user authentication framework.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| 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).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
let userAuthWidgetMgr;
try {
userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
console.info("get userAuthWidgetMgr instance success");
} catch (error) {
console.info("get userAuthWidgetMgr instance failed, error = " + error);
}
try {
userAuthWidgetMgr.on('command', {
callback: sendCommand(cmdData) {
console.log("The cmdData is " + cmdData);
}
})
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed, error = " + error);
}
```
### off<sup>10+</sup>
off(type: 'command', callback?: IAuthWidgetCallback): void
Unsubscribes from commands sent from the user authentication framework.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| 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).
| ID| Error Message |
| -------- | ------------------------ |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
let userAuthWidgetMgr;
try {
userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
console.info("get userAuthWidgetMgr instance success");
} catch (error) {
console.info("get userAuthWidgetMgr instance failed, error = " + error);
}
// Subscribe to the commands sent from the user authentication framework.
try {
userAuthWidgetMgr.on('command', {
callback: sendCommand(cmdData) {
console.log("The cmdData is " + cmdData);
}
})
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed, error = " + error);
}
// Unsubscribe from the commands sent from the user authentication framework.
try {
userAuthWidgetMgr.off('command');
console.info("cancel subscribe authentication event success");
} catch (error) {
console.info("cancel subscribe authentication event failed, error = " + error);
}
```
## userIAM_userAuth.getUserAuthWidgetMgr<sup>10+</sup>
getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr
Obtains a **UserAuthWidgetMgr** instance for user authentication.
> **NOTE**<br>
> A **UserAuthInstance** instance can be used for an authentication only once.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | -------------------- |
| version | number | Yes | Version of the user authentication widget.|
**Return value**
| Type | Description |
| ----------------------------------------- | ------------ |
| [UserAuthWidgetMgr](#userauthwidgetmgr10) | **UserAuthWidgetMgr** instance obtained.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message |
| -------- | --------------------------------------- |
| 201 | Permission verification failed. |
| 202 | The caller is not a system application. |
| 401 | Incorrect parameters. |
| 12500002 | General operation error. |
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
try {
let userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
console.info("get userAuthWidgetMgr instance success");
} catch (error) {
console.info("get userAuthWidgetMgr instance failed, error = " + error);
}
```
## IAuthWidgetCallback<sup>10+</sup>
Provides the callback for returning the commands sent from the user authentication framework to the user authentication widget.
### sendCommand<sup>10+</sup>
sendCommand(cmdData: string): void
Called to return the command sent from the user authentication framework to the user authentication widget.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------ | ---- | ---------------------------------- |
| cmdData | string | Yes | Command sent from the user identity authentication framework to the user authentication widget.|
**Example**
```js
import userIAM_userAuth from '@ohos.userIAM.userAuth';
let version = 1;
try {
let userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version);
userAuthWidgetMgr.on('command', {
callback: sendCommand(cmdData) {
console.log("The cmdData is " + cmdData);
}
})
console.info("subscribe authentication event success");
} catch (error) {
console.info("subscribe authentication event failed, error = " + error);
}
```
## AuthResultInfo<sup>9+</sup>
Defines the authentication result.
......@@ -50,12 +715,14 @@ Enumerates the authentication event information types.
## AuthEventKey<sup>9+</sup>
Defines the keyword of the authentication event type. It is used as a parameter of [on](#on9).
Defines the keyword of the authentication event type. It is used as a parameter of [on](#ondeprecated).
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Value | Description |
| ---------- | ----------------------- |
| "result" | If the first parameter of [on](#on9) is **result**, the [callback](#callback9) returns the authentication result.|
| "tip" | If the first parameter of [on](#on9) is **tip**, the [callback](#callback9) returns the authentication tip information.|
| "result" | If the first parameter of [on](#ondeprecated) is **result**, the [callback](#callback9) returns the authentication result.|
| "tip" | If the first parameter of [on](#ondeprecated) is **tip**, the [callback](#callback9) returns the authentication tip information.|
## AuthEvent<sup>9+</sup>
......@@ -123,18 +790,24 @@ try {
}
```
## AuthInstance<sup>9+</sup>
## AuthInstance<sup>(deprecated)</sup>
Implements user authentication.
### on<sup>9+</sup>
> **NOTE**<br>
> This API is supported since API version 9 and deprecated since API version 10. Use [UserAuthInstance](#userauthinstance10) instead.
### on<sup>(deprecated)</sup>
on : (name : AuthEventKey, callback : AuthEvent) => void
Subscribes to the user authentication events of the specified type.
> **NOTE**<br>
> Use the [AuthInstance](#authinstance9) instance obtained to invoke this API to subscribe to events.
> 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 to subscribe to events.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
......@@ -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.|
| 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**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| -------- | ------- |
| 401 | Incorrect parameters. |
......@@ -194,14 +867,17 @@ try {
}
```
### off<sup>9+</sup>
### off<sup>(deprecated)</sup>
off : (name : AuthEventKey) => void
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>
> 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.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
......@@ -209,10 +885,10 @@ Unsubscribes from the user authentication events of the specific type.
| --------- | -------------------------- | ---- | ------------------------- |
| 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**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| -------- | ------- |
| 401 | Incorrect parameters. |
......@@ -257,23 +933,26 @@ try {
}
```
### start<sup>9+</sup>
### start<sup>(deprecated)</sup>
start : () => void
Starts authentication.
> **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.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
......@@ -306,23 +985,26 @@ try {
}
```
### cancel<sup>9+</sup>
### cancel<sup>(deprecated)</sup>
cancel : () => void
Cancels this authentication.
> **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.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
**System capability**: SystemCapability.UserIAM.UserAuth.Core
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
......@@ -347,12 +1029,15 @@ try {
}
```
## userIAM_userAuth.getAuthInstance<sup>9+</sup>
## userIAM_userAuth.getAuthInstance<sup>(deprecated)</sup>
getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance
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>
> An **AuthInstance** instance can be used for an authentication only once.
......@@ -369,13 +1054,13 @@ Obtains an **AuthInstance** instance for user authentication.
**Return value**
| Type | Description |
| ----------------------------------------- | ------------ |
| [AuthInstance](#authinstance9) | **Authenticator** instance obtained.|
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| --------------------------------------- | ------------ |
| [AuthInstance](#authinstancedeprecated) | **AuthInstance** instance obtained.|
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| -------- | ------- |
| 401 | Incorrect parameters. |
......@@ -417,10 +1102,10 @@ Checks whether the specified authentication capability is supported.
| authType | [UserAuthType](#userauthtype8) | Yes | Authentication type. Only **FACE** is supported.|
| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | Yes | Authentication trust level. |
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
**Error codes**
For details about the error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
| ID| Error Message|
| -------- | ------- |
| 201 | Permission verification failed. |
......@@ -461,19 +1146,20 @@ Enumerates the authentication result codes.
| BUSY | 12500007 | Indicates the busy state. |
| LOCKED | 12500009 | The authentication executor is locked. |
| 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()
A constructor used to create an authenticator instance.
A constructor used to create a **UserAuth** instance.
> **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.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
......@@ -481,7 +1167,7 @@ A constructor used to create an authenticator instance.
| Type | Description |
| ---------------------- | -------------------- |
| [UserAuth](#userauth8) | **Authenticator** instance obtained.|
| [UserAuth](#userauthdeprecated) | **UserAuth** instance created.|
**Example**
......@@ -567,7 +1253,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev
Performs user authentication. This API uses a callback to return the result.
> **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [start](#start9).
> This API is supported since API version 8 and deprecated since API version 9. Use [start](#startdeprecated) instead.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
......@@ -618,7 +1304,7 @@ cancelAuth(contextID : Uint8Array) : number
Cancels an authentication based on the context ID.
> **NOTE**<br>
> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [cancel](#cancel9).
> This API is supported since API version 8 and deprecated since API version 9. Use [cancel](#canceldeprecated) instead.
**Required permissions**: ohos.permission.ACCESS_BIOMETRIC
......@@ -820,7 +1506,8 @@ Enumerates the identity authentication types.
**System capability**: SystemCapability.UserIAM.UserAuth.Core
| Name | Value | Description |
| ----------- | ------ | ---------- |
| ----------- | ---- | ---------- |
| PIN<sup>10+</sup> | 1 | PIN authentication.|
| FACE | 2 | Facial authentication.|
| FINGERPRINT | 4 | Fingerprint authentication.|
......@@ -864,7 +1551,7 @@ Obtains an **Authenticator** instance for user authentication.
Defines the **Authenticator** object.
> **NOTE**<br>
> This object is deprecated since API version 8. You are advised to use [UserAuth](#userauth8).
> This API is deprecated since API version 8. Use [UserAuth](#userauthdeprecated) instead.
### execute<sup>(deprecated)</sup>
......
en/application-dev/security/cryptoFramework-overview.md
浏览文件 @ 7ac51b30
......@@ -12,7 +12,6 @@ The Crypto Framework provides components in the following layers:
- Interface layer: provides unified JavaScript interfaces externally.
- Plug-in layer: implements third-party algorithm 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
### Symmetric Key
......@@ -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.
- **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
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
**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
- **Symmetric AES encryption and decryption**
......@@ -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.
> 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**
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.
- **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
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:
**md**: message digest algorithm.<br>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<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
>
> 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
- **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.
- **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>
**mgf**: mask generation algorithm. Currently, only MGF1 is supported.<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
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
**ECDH**
......@@ -166,20 +215,13 @@ Elliptic Curve Diffie-Hellman (ECDH) allows two parties to establish a shared se
### 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:
- 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).
- 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
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.
|AES|192|AES192|
|AES|256|AES256|
> **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.
> **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.
### 3DES Key Generation Specifications
......@@ -226,9 +268,9 @@ The 3DES key can be generated based on a string parameter.
|---|---|---|
|3DES|192|3DES192|
> **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.
> **NOTE**
>
> As a combination of the symmetric key algorithm and the key length, the string parameter specifies the key specifications when a symmetric key generator is created.
### RSA Key Generation Specifications
......@@ -266,22 +308,21 @@ The 3DES key can be generated based on a string parameter.
| |Common Parameter|Public Key Parameter|Private Key Parameter|Public/Private Key Pair Parameter|
|---|---------|---|---|---|
|n |× |√ |× |√ |
|n |x |√ |x |√ |
|pk| |√ | |√ |
|sk| | |× |√ |
|sk| | |x |√ |
> **NOTE**
>
> 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**
>
> - RSA does not support random key generation by specifying the public parameter (**n**).
>
> - RSA does not support generation of the private key by specifying private key parameters (**n**, **sk**).
> - 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**).
### ECC Key Generation Specifications
> **NOTE**
......@@ -299,11 +340,13 @@ The 3DES key can be generated based on a string parameter.
> **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.
- 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.
| |Common Parameter|Public Key Parameter|Private Key Parameter|Public/Private Key Pair Parameter|
|---|---|---|---|---|
|fieldType| √| √| √| √|
......@@ -312,19 +355,19 @@ The 3DES key can be generated based on a string parameter.
|b | √| √| √| √|
|g | √| √| √| √|
|n | √| √| √| √|
|h | √| √| √| √|
|h | √| √| √| √|
|pk | | √| | √|
|sk | | | √| √|
> **NOTE**
>
> The key parameters specify the key specifications when an asymmetric key generator is created.
>
> The preceding table describes the public and private key parameters supported by the Crypto Framework algorithm library for generating ECC keys. √ indicates that properties need to be specified to construct the key parameter.
> **NOTE**
>
> 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>
> √ indicates that properties needs to be specified to construct the key parameter.
> **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.
### DSA Key Generation Specifications
......@@ -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.
- 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.
| |Common Parameter|Public Key Parameter|Private Key Parameter|Public/Private Key Pair Parameter|
|---|---------|---|---|---|
|p |√ |√ |× |√ |
|q |√ |√ |× |√ |
|g |√ |√ |× |√ |
|p |√ |√ |x |√ |
|q |√ |√ |x |√ |
|g |√ |√ |x |√ |
|pk | |√ | |√ |
|sk | | |× |√ |
|sk | | |x |√ |
> **NOTE**
>
> 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**
>
> - 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.
### 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.
|Asymmetric Key Algorithm|Key Length (Bit)|String Parameter|
|---|---|---|
|SM2|256|SM2_256|
> **NOTE**
>
> 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.
|Symmetric Key Algorithm|Key Length (Bit)|String Parameter|
|---|---|---|
|SM4|128|SM4_128|
> **NOTE**
>
> 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
### Symmetric Encryption and Decryption
......@@ -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 following symmetric encryption algorithms are supported.
|Symmetric Encryption and Decryption Algorithm|Block Cipher Mode|String Parameter |
|---|---|---|
|3DES|ECB|3DES192\|ECB\|[NoPadding\|PKCS5\|PKCS7]|
|3DES|CBC|3DES192\|CBC\|[NoPadding\|PKCS5\|PKCS7]|
|3DES|OFB|3DES192\|OFB\|[NoPadding\|PKCS5\|PKCS7]|
|3DES|CFB|3DES192\|CFB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|ECB|AES[128\|192\|256]\|ECB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CBC|AES[128\|192\|256]\|CBC\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CTR|AES[128\|192\|256]\|CTR\|[NoPadding\|PKCS5\|PKCS7]|
|AES|OFB|AES[128\|192\|256]\|OFB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CFB|AES[128\|192\|256]\|CFB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|GCM|AES[128\|192\|256]\|GCM\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CCM|AES[128\|192\|256]\|CCM\|[NoPadding\|PKCS5\|PKCS7]|
- The following symmetric encryption algorithms are supported.
|Symmetric Encryption and Decryption Algorithm|Block Cipher Mode|String Parameter |
|---|---|---|
|3DES|ECB|3DES192\|ECB\|[NoPadding\|PKCS5\|PKCS7]|
|3DES|CBC|3DES192\|CBC\|[NoPadding\|PKCS5\|PKCS7]|
|3DES|OFB|3DES192\|OFB\|[NoPadding\|PKCS5\|PKCS7]|
|3DES|CFB|3DES192\|CFB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|ECB|AES[128\|192\|256]\|ECB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CBC|AES[128\|192\|256]\|CBC\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CTR|AES[128\|192\|256]\|CTR\|[NoPadding\|PKCS5\|PKCS7]|
|AES|OFB|AES[128\|192\|256]\|OFB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CFB|AES[128\|192\|256]\|CFB\|[NoPadding\|PKCS5\|PKCS7]|
|AES|GCM|AES[128\|192\|256]\|GCM\|[NoPadding\|PKCS5\|PKCS7]|
|AES|CCM|AES[128\|192\|256]\|CCM\|[NoPadding\|PKCS5\|PKCS7]|
|SM4|ECB|SM4_128\|ECB\|[NoPadding\|PKCS5\|PKCS7]|
|SM4|CBC|SM4_128\|CBC\|[NoPadding\|PKCS5\|PKCS7]|
|SM4|CTR|SM4_128\|CTR\|[NoPadding\|PKCS5\|PKCS7]|
|SM4|OFB|SM4_128\|OFB\|[NoPadding\|PKCS5\|PKCS7]|
|SM4|CFB|SM4_128\|CFB\|[NoPadding\|PKCS5\|PKCS7]|
|SM4|CFB128|SM4_128\|CFB128\|[NoPadding\|PKCS5\|PKCS7]|
> **NOTE**
>
> - 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.
> **NOTE**
>
> - 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.
> - An underscore (_) must be added between SM4<sup>10+</sup> and the key length in **String Parameter**.
### Asymmetric RSA Encryption and 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.
### **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.
- The following parameters are supported.
| Asymmetric Key Type| Digest| String Parameter|
|---|---|---|
|SM2_256|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3]|SM2_256\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3]|
|SM2|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3]|SM2_256\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512\|SM3]|
> **NOTE**
>
> As a combination of the asymmetric key type and the padding mode, the string parameter specifies the asymmetric encryption/decryption algorithm specifications when an asymmetric encryption/decryption instance is created.
## Signing and Signature Verification Specifications
### RSA Signing and Signature Verification
......@@ -604,6 +708,7 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
### ECDSA Signing and Signature Verification
> **NOTE**
>
> The APIs support specifications without the key length for ECDSA signing and signature verification from API version 10.
- The following ECDSA parameters are supported.
......@@ -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**.
> - 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
### ECDH
......@@ -668,41 +793,51 @@ The Crypto Framework provides two padding modes for RSA signing and signature ve
## 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|
|---|---|
|HASH|SHA1|
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
|HASH|MD5|
> **NOTE**
>
> SM3 is supported since API version 10.
> **NOTE**
>
> **Supported Type** specifies the MD algorithm specifications when an MD instance is created.
|Digest Algorithm|Supported Type|
|---|---|
|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
The Crypto Framework supports the following HMAC algorithm parameters.
- The Crypto Framework supports the following HMAC algorithm parameters.
|Digest algorithm|Supported Type|
|---|---|
|HASH|SHA1|
|HASH|SHA224|
|HASH|SHA256|
|HASH|SHA384|
|HASH|SHA512|
> **NOTE**
>
> SM3 is supported from API version 10.
> **NOTE**
>
> **Supported Type** specifies the HMAC algorithm specifications when an HMAC instance is created.
|Digest Algorithm|Supported Type|
|---|---|
|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
Currently, the Crypto Framework supports only the CTR_DRBG algorithm.
- Currently, the Crypto Framework supports only the CTR_DRBG algorithm.
> **NOTE**
>
> - Currently, only secure random numbers with length of 1 to **INT_MAX** bytes are supported.
> - The random number generation algorithm uses the **RAND_priv_bytes** interface of OpenSSL to generate secure random numbers.
\ No newline at end of file
> **NOTE**
>
> - Currently, only secure random numbers with length of 1 to **INT_MAX** bytes are supported.
> - The random number generation algorithm uses the **RAND_priv_bytes** interface of OpenSSL to generate secure random numbers.
en/release-notes/changelogs/OpenHarmony_4.0.9.1/changelogs-accessToken.md 0 → 100644
浏览文件 @ 7ac51b30
# App Access Control Subsystem ChangeLog
## 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|
| ohos.permission.READ_MEDIA | File|
| ohos.permission.WRITE_MEDIA | File|
**Adaptation Guide**
N/A
en/release-notes/changelogs/OpenHarmony_4.0.9.1/changelogs-security.md 0 → 100644
浏览文件 @ 7ac51b30
# Security Subsystem Changelog
## 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
interface Key {
/**
* Encode the key object to binary data.
*
* @returns { DataBlob } the binary data of the key object.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
getEncoded(): DataBlob;
}
interface AsyKeyGenerator {
/**
* Used to generate asymmetric key pair.
*
* @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
generateKeyPair(callback: AsyncCallback<KeyPair>): void;
/**
* Used to generate asymmetric key pair.
*
* @returns { Promise<KeyPair> } the promise used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
generateKeyPair(): Promise<KeyPair>;
/**
* Used to convert asymmetric key data to key pair object.
*
* @param { DataBlob } pubKey - the public key data blob.
* @param { DataBlob } priKey - the private key data blob.
* @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback<KeyPair>): void;
/**
* Used to convert asymmetric key data to key pair object.
*
* @param { DataBlob } pubKey - the public key data blob.
* @param { DataBlob } priKey - the private key data blob.
* @returns { Promise<KeyPair> } the promise used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
convertKey(pubKey: DataBlob, priKey: DataBlob): Promise<KeyPair>;
}
/**
* Provides the asymmetric key generator instance func.
*
* @param { string } algName - indicates the algorithm name.
* @returns { AsyKeyGenerator } the generator obj create by algName.
* @throws { BusinessError } 401 - invalid parameters.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createAsyKeyGenerator(algName: string): AsyKeyGenerator;
/**
* Create a cipher object for encryption and decryption operations according to the given specifications.
* Two different Cipher objects should be created when using RSA encryption and decryption,
* even with the same specifications.
*
* @param { string } transformation - indicates the description to be transformed to cipher specifications.
* @returns { Cipher } the cipher object returned by the function.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 801 - this operation is not supported.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createCipher(transformation: string): Cipher;
/**
* Create sign class.
*
* @param { string } algName - indicates the algorithm name and params.
* @returns { Sign } the sign class.
* @throws { BusinessError } 401 - invalid parameters.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createSign(algName: string): Sign;
/**
* Create verify class.
*
* @param { string } algName - indicates the algorithm name and params.
* @returns { Verify } the verify class.
* @throws { BusinessError } 401 - invalid parameters.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createVerify(algName: string): Verify;
/**
* Create key agreement class.
*
* @param { string } algName - indicates the algorithm name and params.
* @returns { KeyAgreement } the key agreement class.
* @throws { BusinessError } 401 - invalid parameters.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createKeyAgreement(algName: string): KeyAgreement;
```
After change:
```ts
interface Key {
/**
* Encode the key object to binary data.
*
* @returns { DataBlob } the binary data of the key object.
* @throws { BusinessError } 801 - this operation is not supported.
* @throws { BusinessError } 17620001 - memory error.
* @throws { BusinessError } 17630001 - crypto operation error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
getEncoded(): DataBlob;
}
interface AsyKeyGenerator {
/**
* Used to generate asymmetric keypair.
*
* @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @throws { BusinessError } 17630001 - crypto operation error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
generateKeyPair(callback: AsyncCallback<KeyPair>): void;
/**
* Used to generate asymmetric keypair.
*
* @returns { Promise<KeyPair> } the promise used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @throws { BusinessError } 17630001 - crypto operation error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
generateKeyPair(): Promise<KeyPair>;
/**
* Used to convert asymmetric key data to keypair object.
*
* @param { DataBlob } pubKey - the public key data blob.
* @param { DataBlob } priKey - the private key data blob.
* @param { AsyncCallback<KeyPair> } callback - the callback used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @throws { BusinessError } 17630001 - crypto operation error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
convertKey(pubKey: DataBlob, priKey: DataBlob, callback: AsyncCallback<KeyPair>): void;
/**
* Used to convert asymmetric key data to keypair object.
*
* @param { DataBlob } pubKey - the public key data blob.
* @param { DataBlob } priKey - the private key data blob.
* @returns { Promise<KeyPair> } the promise used to return keypair.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 17620001 - memory error.
* @throws { BusinessError } 17630001 - crypto operation error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
convertKey(pubKey: DataBlob, priKey: DataBlob): Promise<KeyPair>;
}
/**
* Create the asymmetric key generator instance according to the given algorithm name.
*
* @param { string } algName - indicates the algorithm name.
* @returns { AsyKeyGenerator } the asymmetric key generator instance.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 801 - this operation is not supported.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createAsyKeyGenerator(algName: string): AsyKeyGenerator;
/**
* Create a cipher object for encryption and decryption operations according to the given specifications.
* Two different Cipher objects should be created when using RSA encryption and decryption,
* even with the same specifications.
*
* @param { string } transformation - indicates the description to be transformed to cipher specifications.
* @returns { Cipher } the cipher object returned by the function.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 801 - this operation is not supported.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createCipher(transformation: string): Cipher;
/**
* Create a sign object for generating signatures.
*
* @param { string } algName - indicates the algorithm name and params.
* @returns { Sign } the sign class.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 801 - this operation is not supported.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createSign(algName: string): Sign;
/**
* Create a verify object for verifying signatures.
*
* @param { string } algName - indicates the algorithm name and the parameters.
* @returns { Verify } the verify class.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 801 - this operation is not supported.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createVerify(algName: string): Verify;
/**
* Create a key agreement object.
*
* @param { string } algName - indicates the algorithm name and params.
* @returns { KeyAgreement } the key agreement object.
* @throws { BusinessError } 401 - invalid parameters.
* @throws { BusinessError } 801 - this operation is not supported.
* @throws { BusinessError } 17620001 - memory error.
* @syscap SystemCapability.Security.CryptoFramework
* @since 9
*/
function createKeyAgreement(algName: string): KeyAgreement;
```
**Adaptation Guide**
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.
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或