Skip to content

D
Docs

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

通知 161
Star 293
Fork 28
D
Docs
“d1a691733b1be0a266b6b4bb9535ea1a9b729075”上不存在“...gserver/git@gitcode.net:paddlepaddle/PaddleDetection.git”
未验证 提交 15d48c92 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!3212 媒体、安全、dfx英文开发指南同步 

Merge pull request !3212 from zengyawen/OpenHarmony-3.1-Release
上级 58b156c2 960d6545
隐藏空白更改
内联 并排
Showing with 732 addition and 309 deletion
en/application-dev/dfx/hiappevent-guidelines.md
浏览文件 @ 15d48c92
...@@ -8,69 +8,21 @@ The event logging function helps applications log various information generated ...@@ -8,69 +8,21 @@ The event logging function helps applications log various information generated
JS application event logging APIs are provided by the **hiAppEvent** module. JS application event logging APIs are provided by the **hiAppEvent** module.
**APIs for event logging:** **APIs for Event Logging**
| API | Return Value | Description | | API | Return Value | Description |
| ------------------------------------------------------------ | -------------- | ------------------------------------------------------------ | | ------------------------------------------------------------ | -------------- | ------------------------------------------------------------ |
| write(string eventName, EventType type, object keyValues, AsyncCallback\<void> callback): void | void | Logs application events in asynchronous mode. This method uses an asynchronous callback to return the result. | | write(string eventName, EventType type, object keyValues, AsyncCallback\<void> callback): void | void | Logs application events in asynchronous mode. This method uses an asynchronous callback to return the result. |
| write(string eventName, EventType type, object keyValues): Promise\<void> | Promise\<void> | Logs application events in asynchronous mode. This method uses a promise to return the result. | | write(string eventName, EventType type, object keyValues): Promise\<void> | Promise\<void> | Logs application events in asynchronous mode. This method uses a promise to return the result. |
- **eventName**: event name you customized. The event name can contain a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter.
- **type**: event type enumerated by **EventType**.
| Type | Description |
| --------- | ----------------- |
| FAULT | Fault event |
| STATISTIC | Statistical event |
| SECURITY | Security event |
| BEHAVIOR | Behavior event |
- **keyValues**: event parameter key-value pair. For a variable-length parameter, enter each pair of parameter name and value in sequence. For a JSON parameter, enter the parameter name as the key and parameter value as the value.
- A parameter name must be a string, and a parameter value must be a string, number, boolean, or array (which is a basic element).
- The number of event parameters must be less than or equal to 32.
- The parameter name can contain a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (\_).
- A string value can contain a maximum of 8*1024 characters.
- An array value can contain a maximum of 100 elements. Excess elements will be truncated.
- **callback**: callback function used to process the received return value. The value **0** indicates that the event parameter verification is successful, and the event will be written to the event file asynchronously. A value greater than **0** indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored. A value smaller than **0** indicates that the event parameter verification fails, and the event will not be written to the event file asynchronously.
When an asynchronous callback is used, the return value can be processed directly in the callback. When a promise is used, the return value can also be processed in the promise in a similar way. For details about the result codes, see [Event Verification Result Codes](hiappevent-overview.md#Event Verification Result Codes). When an asynchronous callback is used, the return value can be processed directly in the callback. When a promise is used, the return value can also be processed in the promise in a similar way. For details about the result codes, see [Event Verification Result Codes](hiappevent-overview.md#Event Verification Result Codes).
**APIs for event logging configuration:** **APIs for Event Logging Configuration**
| API | Return Value | Description | | API | Return Value | Description |
| ------------------------------ | ------------ | ------------------------------------------------------------ | | ------------------------------ | ------------ | ------------------------------------------------------------ |
| configure(ConfigOption config) | boolean | Sets the configuration options for application event logging.<br/>The value **true** indicates that the operation is successful, and value **false** indicates the opposite. | | configure(ConfigOption config) | boolean | Sets the configuration options for application event logging.<br/>The value **true** indicates that the operation is successful, and value **false** indicates the opposite. |
- **config**: configuration options for application event logging.
Configuration options for application event logging (**ConfigOption**)
| Name | Type | Mandatory | Description |
| ---------- | ------- | --------- | ------------------------------------------------------------ |
| disable | boolean | No | Sets the application event logging switch. The value **true** means to disable the application event logging function, and value **false** means the opposite. |
| maxStorage | string | No | Specifies the maximum size of the event file storage directory. The default value is 10M. |
**Predefined event name constants (Event)**:
| Constant | Type | Description |
| ------------------------- | ------ | ---------------------------------------------- |
| USER_LOGIN | string | Name of the user login event. |
| USER_LOGOUT | string | Name of the user logout event. |
| DISTRIBUTED_SERVICE_START | string | Name of the distributed service startup event. |
**Predefined parameter name constants (Param):**
| Constant | Type | Description |
| ------------------------------- | ------ | -------------------------------- |
| USER_ID | string | Custom user ID. |
| DISTRIBUTED_SERVICE_NAME | string | Distributed service name. |
| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Distributed service instance ID. |
## How to Develop ## How to Develop
In this example, an application event is logged after the application startup execution page is loaded. In this example, an application event is logged after the application startup execution page is loaded.
...@@ -103,8 +55,7 @@ In this example, an application event is logged after the application startup ex ...@@ -103,8 +55,7 @@ In this example, an application event is logged after the application startup ex
}).catch((err) => { }).catch((err) => {
console.error(`failed to write event because ${err.code}`); console.error(`failed to write event because ${err.code}`);
}); });
});
// 3. Set the application event logging switch. // 3. Set the application event logging switch.
hiAppEvent.configure({ hiAppEvent.configure({
disable: true disable: true
...@@ -118,6 +69,4 @@ In this example, an application event is logged after the application startup ex ...@@ -118,6 +69,4 @@ In this example, an application event is logged after the application startup ex
} }
``` ```
2. Tap the run button on the application UI to run the project. 2. Tap the run button on the application UI to run the project.
\ No newline at end of file
en/application-dev/dfx/hiappevent-overview.md
浏览文件 @ 15d48c92
...@@ -6,9 +6,7 @@ HiAppEvent provides event logging APIs for applications to log the fault, statis ...@@ -6,9 +6,7 @@ HiAppEvent provides event logging APIs for applications to log the fault, statis
The HiAppEvent module of OpenHarmony can be used to develop application event services and provide functions related to application events, including flushing application events to a disk and querying historical application event data. The HiAppEvent module of OpenHarmony can be used to develop application event services and provide functions related to application events, including flushing application events to a disk and querying historical application event data.
- **Logging** **Logging**: Logs changes caused by user operations to provide service data for development, product, and O&M analysis.
Logs changes caused by user operations to provide service data for development, product, and O&M analysis.
## Event Verification Result Codes ## Event Verification Result Codes
......
en/application-dev/media/Readme-EN.md
浏览文件 @ 15d48c92
...@@ -6,18 +6,14 @@ ...@@ -6,18 +6,14 @@
- [Audio Playback Development](audio-playback.md) - [Audio Playback Development](audio-playback.md)
- [Audio Playback Development Using AudioRenderer](audio-renderer.md) - [Audio Rendering Development](audio-renderer.md)
- [Audio Recording Development](audio-recorder.md) - [Audio Recording Development](audio-recorder.md)
- [Audio Recorder Development Using AudioCapturer](audio-capturer) - [Audio Capture Development](audio-capturer)
- Video - Video
- [Video Playback Development](video-playback.md) - [Video Playback Development](video-playback.md)
- [Video Recording Development](video-recorder.md)
- Image - Image
- [Image Development](image.md) - [Image Development](image.md)
en/application-dev/media/audio-capturer.md
浏览文件 @ 15d48c92
# Audio Recorder Development Using AudioCapturer # Audio Capture Development
--- ---
## ***Note***: ## ***Note***:
...@@ -41,7 +41,7 @@ Here's an example of how to use AudioCapturer to capture a raw audio file. ...@@ -41,7 +41,7 @@ Here's an example of how to use AudioCapturer to capture a raw audio file.
2. (Optional) Subscribe to audio capturer state change events using the **on('stateChange')** API. 2. (Optional) Subscribe to audio capturer state change events using the **on('stateChange')** API.
If an application wants to take some action based on the state updates in capturer, the application can subscribe to the state change event. If an application wants to take some action based on the state updates in capturer, the application can subscribe to the state change event.
There are more events that applications can subscribe to, such as 'markReach' and 'periodReach'. Refer to [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) for more details. There are more events that applications can subscribe to, such as 'markReach' and 'periodReach'. Refer to [Audio](../reference/apis/js-apis-audio.md) for more details.
``` ```
audioCapturer.on('stateChange',(state) => { audioCapturer.on('stateChange',(state) => {
console.info('AudioCapturerLog: Changed State to : ' + state) console.info('AudioCapturerLog: Changed State to : ' + state)
...@@ -149,4 +149,4 @@ That is, the AudioCapturer has an internal state that the application must alway ...@@ -149,4 +149,4 @@ That is, the AudioCapturer has an internal state that the application must alway
The system may throw an error/exception or generate other undefined behaviour if the application performs an operation while capturer is in an improper state. The system may throw an error/exception or generate other undefined behaviour if the application performs an operation while capturer is in an improper state.
## **Other APIs** ## **Other APIs**
See [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) for more useful APIs like **getAudioTime**, **getCapturerInfo** and **getStreamInfo**. See [AudioCapturer in the Audio API](../reference/apis/js-apis-audio.md) for more useful APIs like **getAudioTime**, **getCapturerInfo** and **getStreamInfo**.
en/application-dev/media/audio-playback.md
浏览文件 @ 15d48c92
...@@ -16,7 +16,7 @@ You can use audio playback APIs to convert audio data into audible analog signal ...@@ -16,7 +16,7 @@ You can use audio playback APIs to convert audio data into audible analog signal
## How to Develop ## How to Develop
For details about the APIs used for audio playback, see [js-apis-media.md](../reference/apis/js-apis-media.md). For details about the APIs used for audio playback, see [AudioPlayer in the Media API](../reference/apis/js-apis-media.md).
### Full-Process Scenario ### Full-Process Scenario
......
en/application-dev/media/audio-recorder.md
浏览文件 @ 15d48c92
...@@ -16,7 +16,7 @@ During audio recording, audio signals are captured, encoded, and saved to files. ...@@ -16,7 +16,7 @@ During audio recording, audio signals are captured, encoded, and saved to files.
## How to Develop ## How to Develop
For details about the APIs used for audio recording, see [js-apis-media.md](../reference/apis/js-apis-media.md). For details about the APIs, see [AudioRecorder in the Media API](../reference/apis/js-apis-media.md).
### Full-Process Scenario ### Full-Process Scenario
...@@ -127,7 +127,7 @@ import mediaLibrary from '@ohos.multimedia.mediaLibrary' ...@@ -127,7 +127,7 @@ import mediaLibrary from '@ohos.multimedia.mediaLibrary'
let testFdNumber; let testFdNumber;
function SetCallBack(audioPlayer) { function SetCallBack(audioRecorder) {
audioRecorder.on('prepare', () => { // Set the 'prepare' event callback. audioRecorder.on('prepare', () => { // Set the 'prepare' event callback.
console.log('prepare success'); console.log('prepare success');
// The recording page is ready. You can click the Record button to start recording. // The recording page is ready. You can click the Record button to start recording.
......
en/application-dev/media/audio-renderer.md
浏览文件 @ 15d48c92
# Audio Playback Development Using AudioRenderer # Audio Rendering Development
--- ---
## ***Note***: ## ***Note***:
...@@ -17,7 +17,7 @@ When a higher priority stream wants to play, the AudioRenderer framework interru ...@@ -17,7 +17,7 @@ When a higher priority stream wants to play, the AudioRenderer framework interru
For example, if a call is arrived when you listen to music, the music playback, which is the lower priority stream, is paused.\ For example, if a call is arrived when you listen to music, the music playback, which is the lower priority stream, is paused.\
With the sample code below, we'll look at how AudioInterrupt works in detail.\ With the sample code below, we'll look at how AudioInterrupt works in detail.\
<br/> <br/>
Please see [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) for a list of supported audio stream types and formats, such as AudioSampleFormat, AudioChannel, AudioSampleFormat, and AudioEncodingType. Please see [AudioRenderer in the Audio API](../reference/apis/js-apis-audio.md#audiorenderer8) for a list of supported audio stream types and formats, such as AudioSampleFormat, AudioChannel, AudioSampleFormat, and AudioEncodingType.
## **Usage** ## **Usage**
...@@ -267,8 +267,8 @@ The system may throw an error/exception or generate other undefined behaviour if ...@@ -267,8 +267,8 @@ The system may throw an error/exception or generate other undefined behaviour if
## **Asynchronous Operations:** ## **Asynchronous Operations:**
Most of the AudioRenderer calls are asynchronous. As a result, the UI thread will not be blocked.\ Most of the AudioRenderer calls are asynchronous. As a result, the UI thread will not be blocked.\
For each API, the framework provides both callback and promises functions.\ For each API, the framework provides both callback and promises functions.\
In the example, promise functions are used for simplicity. [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) In the example, promise functions are used for simplicity. [AudioRender in the Audio API](../reference/apis/js-apis-audio.md#audiorenderer8)
provides reference for both callback and promise. provides reference for both callback and promise.
## **Other APIs:** ## **Other APIs:**
See [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-audio.md) for more useful APIs like getAudioTime, drain, and getBufferSize. See [Audio](../reference/apis/js-apis-audio.md) for more useful APIs like getAudioTime, drain, and getBufferSize.
en/application-dev/media/image.md
浏览文件 @ 15d48c92
...@@ -6,7 +6,7 @@ You can use image development APIs to decode images into pixel maps and encode t ...@@ -6,7 +6,7 @@ You can use image development APIs to decode images into pixel maps and encode t
## Available APIs ## Available APIs
For details about the APIs, see [js-apis-image.md](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-image.md). For details about the APIs, see [Image Processing](../reference/apis/js-apis-image.md).
## How to Develop ## How to Develop
......
en/application-dev/media/video-playback.md
浏览文件 @ 15d48c92
...@@ -20,9 +20,22 @@ Note: Video playback requires hardware capabilities such as display, audio, and ...@@ -20,9 +20,22 @@ Note: Video playback requires hardware capabilities such as display, audio, and
2. The third-party application transfers the surface ID to the VideoPlayer JS. 2. The third-party application transfers the surface ID to the VideoPlayer JS.
3. The media service flushes the frame data to the surface buffer. 3. The media service flushes the frame data to the surface buffer.
## Compatibility
You are advised to use the mainstream playback formats and resolutions, rather than custom or abnormal streams to avoid playback failure, frame freezing, and artifacts. The system is not affected by incompatibility issues. If such an error occurs, you can exit stream playback mode.
The table below lists the mainstream playback formats and resolutions.
| Video Container Specification| Specification Description | Resolution |
| :----------: | :-----------------------------------------------: | :--------------------------------: |
| mp4 | Video format: H.264/MPEG-2/MPEG-4/H.263; audio format: AAC/MP3| Mainstream resolutions, such as 1080p, 720p, 480p, and 270p|
| mkv | Video format: H.264/MPEG-2/MPEG-4/H.263; audio format: AAC/MP3| Mainstream resolutions, such as 1080p, 720p, 480p, and 270p|
| ts | Video format: H.264/MPEG-2/MPEG-4; audio format: AAC/MP3 | Mainstream resolutions, such as 1080p, 720p, 480p, and 270p|
| webm | Video format: VP8; audio format: VORBIS | Mainstream resolutions, such as 1080p, 720p, 480p, and 270p|
## How to Develop ## How to Develop
For details about the APIs used for video playback, see [js-apis-media.md](../reference/apis/js-apis-media.md). For details about the APIs, see [VideoPlayer in the Media API](../reference/apis/js-apis-media.md).
### Full-Process Scenario ### Full-Process Scenario
......
en/application-dev/media/video-recorder.md 已删除 100644 → 0
浏览文件 @ 58b156c2
# Video Recording Development
## When to Use
During video recording, audio and video signals are captured, encoded, and saved to files. You can specify parameters such as the encoding format, encapsulation format, and file path for video recording.
**Figure 1** Video recording state transition
![en-us_image_video_recorder_state_machine](figures/en-us_image_video_recorder_state_machine.png)
**Figure 2** Layer 0 diagram of video recording
![en-us_image_video_recorder_zero](figures/en-us_image_video_recorder_zero.png)
## How to Develop
For details about the APIs used for video recording, see [js-apis-media.md](../reference/apis/js-apis-media.md).
### Full-Process Scenario
The full video recording process includes creating an instance, setting recording parameters, recording video, pausing, resuming, and stopping recording, and releasing resources.
```js
import media from '@ohos.multimedia.media'
import mediaLibrary from '@ohos.multimedia.mediaLibrary'
let testFdNumber;
// pathName indicates the passed recording file name, for example, 01.mp4. The generated file address is /storage/media/100/local/files/Movies/01.mp4.
// To use the media library, declare the following permissions: ohos.permission.MEDIA_LOCATION, ohos.permission.WRITE_MEDIA, and ohos.permission.READ_MEDIA.
async function getFd(pathName) {
let displayName = pathName;
const mediaTest = mediaLibrary.getMediaLibrary();
let fileKeyObj = mediaLibrary.FileKey;
let mediaType = mediaLibrary.MediaType.VIDEO;
let publicPath = await mediaTest.getPublicDirectory(mediaLibrary.DirectoryType.DIR_VIDEO);
let dataUri = await mediaTest.createAsset(mediaType, displayName, publicPath);
if (dataUri != undefined) {
let args = dataUri.id.toString();
let fetchOp = {
selections : fileKeyObj.ID + "=?",
selectionArgs : [args],
}
let fetchFileResult = await mediaTest.getFileAssets(fetchOp);
let fileAsset = await fetchFileResult.getAllObject();
let fdNumber = await fileAsset[0].open('Rw');
fdNumber = "fd://" + fdNumber.toString();
testFdNumber = fdNumber;
}
}
await getFd('01.mp4');
let videoProfile = {
audioBitrate : 48000,
audioChannels : 2,
audioCodec : 'audio/mp4a-latm',
audioSampleRate : 48000,
fileFormat : 'mp4',
videoBitrate : 48000,
videoCodec : 'video/mp4v-es',
videoFrameWidth : 640,
videoFrameHeight : 480,
videoFrameRate : 30
}
let videoConfig = {
audioSourceType : 1,
videoSourceType : 0,
profile : videoProfile,
url: testFdNumber, // testFdNumber is generated by getFd.
orientationHint : 0,
location : { latitude : 30, longitude : 130 },
}
// Error callback triggered in the case of an error
function failureCallback(error) {
console.info('error happened, error name is ' + error.name);
console.info('error happened, error code is ' + error.code);
console.info('error happened, error message is ' + error.message);
}
// Error callback triggered in the case of an exception
function catchCallback(error) {
console.info('catch error happened, error name is ' + error.name);
console.info('catch error happened, error code is ' + error.code);
console.info('catch error happened, error message is ' + error.message);
}
let videoRecorder = null; // videoRecorder is an empty object and assigned with a value after createVideoRecorder is successfully called.
let surfaceID = null; // Used to save the surface ID returned by getInputSurface.
// Create a VideoRecorder object.
await media.createVideoRecorder().then((recorder) => {
console.info('case createVideoRecorder called');
if (typeof (recorder) != 'undefined') {
videoRecorder = recorder;
console.info('createVideoRecorder success');
} else {
console.info('createVideoRecorder failed');
}
}, failureCallback).catch(catchCallback);
// Obtain the surface ID, save it, and pass it to camera-related interfaces.
await videoRecorder.getInputSurface().then((surface) => {
console.info('getInputSurface success');
surfaceID = surface;
}, failureCallback).catch(catchCallback);
// Video recording depends on camera-related interfaces. The following operations can be performed only after the video output start interface is invoked.
// Start video recording.
await videoRecorder.start().then(() => {
console.info('start success');
}, failureCallback).catch(catchCallback);
// Pause video playback before the video output stop interface is invoked.
await videoRecorder.pause().then(() => {
console.info('pause success');
}, failureCallback).catch(catchCallback);
// Resume video playback after the video output start interface is invoked.
await videoRecorder.resume().then(() => {
console.info('resume success');
}, failureCallback).catch(catchCallback);
// Stop video recording after the video output stop interface is invoked.
await videoRecorder.stop().then(() => {
console.info('stop success');
}, failureCallback).catch(catchCallback);
// Reset the recording configuration.
await videoRecorder.reset().then(() => {
console.info('reset success');
}, failureCallback).catch(catchCallback);
// Release the video recording resources and camera object resources.
await videoRecorder.release().then(() => {
console.info('release success');
}, failureCallback).catch(catchCallback);
// Set the related object to null.
videoRecorder = null;
surfaceID = null;
```
en/application-dev/security/Readme-EN.md
浏览文件 @ 15d48c92
...@@ -3,5 +3,14 @@ ...@@ -3,5 +3,14 @@
- User Authentication - User Authentication
- [User Authentication Overview](userauth-overview.md) - [User Authentication Overview](userauth-overview.md)
- [User Authentication Development](userauth-guidelines.md) - [User Authentication Development](userauth-guidelines.md)
- hapsigner
- [hapsigner Guide](hapsigntool-guidelines.md) - Key Management
\ No newline at end of file - [HUKS Overview](huks-overview.md)
- [HUKS Development](huks-guidelines.md)
- hapsigntool
- [hapsigntool Guide](hapsigntool-guidelines.md)
- Access Control
- [Access Control Overview](accesstoken-overview.md)
- [Access Control Development](accesstoken-guidelines.md)
\ No newline at end of file
en/application-dev/security/accesstoken-guidelines.md 0 → 100644
浏览文件 @ 15d48c92
# Access Control Development
## Scenario
In this example, the app requires the **ohos.permission.PERMISSION1** and **ohos.permission.PERMISSION2** permissions to implement core functions.
- The ability privilege level (APL) of the app is normal.
- The level of **ohos.permission.PERMISSION1** is normal, and the authorization mode is system_grant.
- The level of **ohos.permission.PERMISSION2** is system_basic, and the authorization mode is user_grant.
> **Precautions**
>
> In this scenario, the required permissions include a user_grant permission. You can check whether the caller has the required permission through permission verification.
>
> If the permission verification result indicates that the app has not obtained that permission, dynamic user authorization is required.
>
## Available APIs
The table below lists only the API used in this guide. For more information, see the [API Reference](../reference/apis/js-apis-abilityAccessCtrl.md).
| API | Description |
| ------------------------------------------------------------ | --------------------------------------------------- |
| verifyAccessToken(tokenID: number, permissionName: string): Promise&lt;GrantStatus&gt; | Verifies whether an app has the specified permission. This API uses a promise to return the result.|
## Declaring Permissions
### config.json
Declare the permissions required by the app one by one in the **config.json** file. The app cannot obtain a permission if it is not declared in the **config.json** file.
**Description of config.json**
| Field | Description |
| --------- | ------------------------------------------------------------ |
| name | Name of the permission. |
| reason | Reason for requesting the permission. This field is mandatory for a user_grant permission.|
| usedScene | Scenario of the permission. This field is mandatory for a user_grant permission.|
| abilities | Abilities that use the permission. The value is an array. |
| when | Time when the permission is used. The value can be **inuse** (the permission can be used only in the foreground) or **always** (the permission can be used in foreground and background).|
**Example**
```json
{
"module" : {
"requesetPermissions":[
{
"name" : "ohos.permission.PERMISSION1",
"reason": "$string:reason",
"usedScene": {
"abilities": [
"FormAbility"
],
"when":"inuse"
}
},
{
"name" : "ohos.permission.PERMISSION2",
"reason": "$string:reason",
"usedScene": {
"abilities": [
"FormAbility"
],
"when":"always"
}
}
],
}
}
```
## Declaring the ACL
The permission level of **ohos.permission.PERMISSION2** is system_basic, which is higher than the app's APL. In this case, use the ACL.
In addition to declaring all the permissions in the **config.json** file, you must declare the permissions whose levels are higher than the app's APL in the app's profile. In this example, declare the permission under the **acls** field:
```json
{
"version-name": "1.0.0",
"version-code": 1,
"app-distribution-type": "os_integration",
"uuid": "5027b99e-5f9e-465d-9508-a9e0134ffe18",
"validity": {
"not-before": 1594865258,
"not-after": 1689473258
},
"type": "release",
"bundle-info": {
"developer-id": "OpenHarmony",
"distribution-certificate": "-----BEGIN CERTIFICATE-----\nMIICMzCCAbegAwIBAgIEaOC/zDAMBggqhkjOPQQDAwUAMGMxCzAJBgNVBAYTAkNO\nMRQwEgYDVQQKEwtPcGVuSGFybW9ueTEZMBcGA1UECxMQT3Blbkhhcm1vbnkgVGVh\nbTEjMCEGA1UEAxMaT3Blbkhhcm1vbnkgQXBwbGljYXRpb24gQ0EwHhcNMjEwMjAy\nMTIxOTMxWhcNNDkxMjMxMTIxOTMxWjBoMQswCQYDVQQGEwJDTjEUMBIGA1UEChML\nT3Blbkhhcm1vbnkxGTAXBgNVBAsTEE9wZW5IYXJtb255IFRlYW0xKDAmBgNVBAMT\nH09wZW5IYXJtb255IEFwcGxpY2F0aW9uIFJlbGVhc2UwWTATBgcqhkjOPQIBBggq\nhkjOPQMBBwNCAATbYOCQQpW5fdkYHN45v0X3AHax12jPBdEDosFRIZ1eXmxOYzSG\nJwMfsHhUU90E8lI0TXYZnNmgM1sovubeQqATo1IwUDAfBgNVHSMEGDAWgBTbhrci\nFtULoUu33SV7ufEFfaItRzAOBgNVHQ8BAf8EBAMCB4AwHQYDVR0OBBYEFPtxruhl\ncRBQsJdwcZqLu9oNUVgaMAwGCCqGSM49BAMDBQADaAAwZQIxAJta0PQ2p4DIu/ps\nLMdLCDgQ5UH1l0B4PGhBlMgdi2zf8nk9spazEQI/0XNwpft8QAIwHSuA2WelVi/o\nzAlF08DnbJrOOtOnQq5wHOPlDYB4OtUzOYJk9scotrEnJxJzGsh/\n-----END CERTIFICATE-----\n",
"bundle-name": "com.ohos.permissionmanager",
"apl": "system_core",
"app-feature": "hos_system_app"
},
"acls": {
"allowed-acls": [
"ohos.permission.PERMISSION2"
]
},
"permissions": {
"restricted-permissions": []
},
"issuer": "pki_internal"
}
```
## Applying for the user_grant Permission
After the permissions are declared, the system grants the system_grant permission during the installation of the app. The user_grant permission must be authorized by the user.
Therefore, before invoking the API protected by the **ohos.permission.PERMISSION2 permission**, the app needs to verify whether it has the permission.
If the verification result indicates that the app has the permission, the app can access the target API. Otherwise, the app needs to request user authorization and then proceeds based on the authorization result. For details, see [Access Control Overview](accesstoken-overview.md).
> **Precautions**
>
> The permissions authorized by user are not permanent, because the user may revoke the authorization at any time. Therefore, even if the user has granted the requested permission to an app, the app's permission must be verified before the app calls an API protected by the permission.
## Example
The procedure is as follows:
1. Obtain the caller's identity tokenId.
2. Determine the permission to be verified. In this example, the permission is **permissionNameUser**.
3. Call **verifyAccessToken** to verify the permissions of the caller.
4. Proceed based on the permission verification result.
```js
import {describe, beforeEach, afterEach, it, expect} from 'deccjsunit/index'
import abilityAccessCtrl from '@ohos.abilityAccessCtrl'
import bundle from '@ohos.bundle'
async requestPermission() {
var permissionNameUser = "ohos.permission.PERMISSION2";
var bundleFlag = 0;
var tokenID = undefined;
var userID = 100;
var appInfo = await bundle.getApplicationInfo('ohos.acts.security.access_token.normal', bundleFlag, userID);
tokenID = appInfo.accessTokenId;
console.log("AccessTokenTest accessTokenId:" + appInfo.accessTokenId + ", name:" + appInfo.name
+ ", bundleName:" + appInfo.bundleName)
var atManager = abilityAccessCtrl.createAtManager();
var result = await atManager.verifyAccessToken(tokenID, permissionNameUser);
if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
// Execute the operation.
} else {
// Apply for dynamic user authorization using requestPermissionsFromUser.
}
}
```
> ![icon-note.gif](../public_sys-resources/icon-note.gif)**NOTE**<br/>
> For details about how to use **requestPermissionsFromUser**, see [API Reference] (../reference/apis/js-apis-ability-context.md).
en/application-dev/security/accesstoken-overview.md 0 → 100644
浏览文件 @ 15d48c92
# Access Control Overview
## Introduction
AccessTokenManager (ATM) implements unified app permission management based on access tokens on OpenHarmony.
By default, apps can access limited system resources. However, in some cases, an app needs to access excess data (including personal data) and functions of the system or another app to implement extended functions. Systems or apps must also share their data or functions through interfaces in an explicit manner. OpenHarmony uses app permissions to perform access control and prevent improper or malicious use of these data or functions.
App permissions are used to protect the following objects:
- Data: personal data (such as photos, Contacts, calendar, and location), device data (such as device ID, camera, and microphone), and app data.
- Functions: device functions (such as making calls, sending SMS messages, and connecting to the Internet) and app functions (such as displaying windows and creating shortcuts).
Without the required permissions, an app cannot access or perform operations on the target object. Permissions must be clearly defined for apps. With app permissions, the system can standardize the behavior of apps and protect user privacy. Before an app accesses the target object, the target object verifies the app's permissions and denies the access if the app does not have required permissions.
Currently, ATM performs app permission verification based on the token identity (Token ID). A token ID identifies an app. The ATM manages app permissions based on the app's token ID.
## How to Develop
Determine the permissions required for an app to access data or perform an operation. Declare the required permissions in the app installation package.
Determine whether the required permissions need to be authorized by users. If yes, provide a dialog box dynamically to request user authorization.
After the user grants permissions to the app, the app can access the data or perform the operation.
The figure below shows the process.
![](figures/figure1.png)
## When to Use
### Scenarios
The following describes two common scenarios.
- **Video playback apps**
Video playback apps need to use multimedia functions and read and write media files stored on storage devices. Therefore, the apps must have at least the following permissions:
* ohos.permission.READ_MEDIA (allowing the app to read external media files)
* ohos.permission.WRITE_MEDIA (allowing the app to read and write external media files)
- **Photography apps**
Photography apps need to use the camera function. Before accessing the camera service, the app must have the following permission:
ohos.permission.CAMERA (allowing the app to use the camera to take photos and record videos).
### Basic Principles
Observe the following principles for permission management:
- Provide clear description about the app functions and scenarios and permissions required for using the app so that users can clearly know why, when, and how to apply for permissions for using the app. Do not induce or mislead users' authorization. The permissions on an app must comply with the description provided in the app.
- Use the principle of least authority for user permissions. Allow only necessary permissions for service functions.
- When an app is started for the first time, avoid frequently displaying pop-up windows for users to apply for multiple permissions. Allow users to apply for permissions only when they need to use the corresponding service functions.
- If a user rejects to authorize a permission, the user can still use functions irrelevant to this permission and can register and access the app.
- Provide no more message if a user rejects the authorization required by a function. Provide onscreen instructions to direct the user to give authorization in System Settings if the user triggers this function again or needs to use this function.
- All the permissions granted to apps must come from the Permission List. Custom permissions are not allowed for apps currently.
## Permission Levels
To protect user privacy, ATM defines different permission levels based on the sensitivity of the data involved or the security threat of the ability.
### App APL
The ability privilege level (APL) defines the priority of the app permission requested. Apps of different APLs can apply for permissions of different levels.
The table below describes the APLs.
| APL | Description |
| ---------------- | -------------------------------------- |
| system_core | The apps of this level provide core abilities of the operating system.|
| system_basic| The apps of this level provide basic system services. |
| Normal | The apps of this level are normal apps. |
By default, apps are of the normal APL. To declare the system_basic or higher APL:
- The APL must be approved by the app store.
- The APL must be declared in the **apl** field of the app's profile in the app installation package, and a profile signing certificate must be generated. For details, see [Configuring OpenHarmony App Signature Information]( https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-debugging-and-running-0000001263040487#section17660437768).
### Permission Levels
The permissions open to apps vary with the permission level. The permission levels include the following in ascending order of seniority.
- **normal**
The normal permission allows access to common system resources beyond the default rules. Access to these system resources (including data and functions) has minor risks on user privacy and other apps.
The permissions of this level are available only to apps of the normal or higher APL.
- **system_basic**
The system_basic permission allows access to resources related to basic operating system services. The basic services are basic functions provided or preconfigured by the system, such as system setting and identity authentication. Access to these resources may have considerable risks to user privacy and other apps.
The permissions of this level are available only to the apps of the system_basic APL.
- **system_core**
The system_core permission allows access to core resources of the operating system. These resources are the underlying core services of the system. If these resources are corrupted, the OS cannot run properly.
The permissions of this type are not open to any app currently.
### ACL
As described above, permission levels and app APLs are in one-to-one correspondence. In principle, **an app with a lower APL cannot apply for higher permissions by default**.
The Access Control List (ACL) makes low-level apps to have high-level permissions.
**Example**
The APL of app A is normal. App A needs to have permission B (system_basic level) and permission C (normal level). In this case, you can use the ACL to grant permission B to app A.
For details, see [Using the ACL](#usingacl).
## Permission Authorization Modes
Permissions can be classified into the following types based on the authorization mode:
- **system_grant**
The app permissions are authorized by the system. This type of apps cannot access user or device sensitive information. The allowed operations have minor impact on the system or other apps.
For a system_grant app, the system automatically grants the required permissions to the app when the app is installed. The system_grant permission list must be presented to users on the details page of the app store.
- **user_grant**
The app permissions must be authorized by users. This type of apps may access user or device sensitive information. The allowed operations may have a critical impact on the system or other apps.
This type of permissions must be declared in the app installation package and authorized by users dynamically during the running of the app. The app has the permission only after user authorization.
For example, in the [Permission List](#permissionlist), the permissions for the microphone and camera are user_grant permissions. The list provides reasons for using the permissions.
The user_grant permission list must also be presented on the details page of the app store.
## Authorization Processes
The process for an app obtaining the required permissions varies
depending on the permission authorization mode.
- For a system_grant permission, you need to [declare the permission](accesstoken-guidelines.md) in the **config.json** file. The permission will be pre-granted when the app is installed.
- For a user_grant permission, you need to [declare the permission](accesstoken-guidelines.md) in the **config.json** file, and a dialog box needs to be displayed to request user authorization during the running of the app.
### Permission Authorization Process (user_grant)
The procedure is as follows:
1. In the **config.json** file, declare the permissions required by the app. For details, see [Access Control Development](accesstoken-guidelines.md).
2. Associate the object that requires the permissions in the app with the target permissions. In this way, the user knows the operations to be granted with the specified permissions.
3. Check whether the user has granted the required permissions to the app when the app is running. If yes, the app can access the data or perform the operation. If the user has not granted the permissions to the app, display a dialog box requesting the user authorization when the app attempts to access the data or perform the operation.
4. Check the user authorization result. Allow the next step only after the user has granted the permissions to the app.
**Precautions**
- Check the app's permission each time before the operation requiring the permission is performed.
- To check whether a user has granted specific permissions to your app, use the [verifyAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md) method. This method returns [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md) or [PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md). For details about the sample code, see [Access Control Development](#accesstoken-guidelines.md).
- Users must be able to understand and control the authorization of user_grant permissions. During the running process, the app requiring user authorization must proactively call the API to dynamically request the authorization. Then, the system displays a dialog box asking the user to grant the requested permission. The user will determine whether to grant the permission based on the running context of the app.
- The permission authorized is not permanent, because the user may revoke the authorization at any time. Therefore, even if the user has granted the requested permission to the app, the app must check for the permission before calling the API controlled by this permission.
### Using the ACL
If the permission required by an app has higher level than the app's APL, you can use the ACL to grant the permissions required.
In addition to the preceding [authorization processes](#authorizationprocesses), you need to declare the ACL.
In addition to declaring the required permissions in the **config.json** file, you must declare the high-level permissions in the app's [profile](accesstoken-guidelines.md). The subsequent steps remain unchanged.
**NOTE**
* The ACL must be approved by the app store.
* Declare the target ACL in the **acl** field of the app's profile in the app installation package, and generate a profile signing certificate. For details, see [Configuring OpenHarmony App Signature Information]( https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-debugging-and-running-0000001263040487#section17660437768).
## Permission List
The following lists the permissions defined by the system.
| Permission | APL | Authorization Mode | Enable ACL| Description |
| -------------------------------------------------------- | ------------ | ------------ | ------- | ------------------------------------------------------------ |
| ohos.permission.USE_BLUETOOTH | normal | system_grant | TRUE | Allows an app to access to Bluetooth configuration. |
| ohos.permission.DISCOVER_BLUETOOTH | normal | system_grant | TRUE | Allows an app to configure Bluetooth on a device, initiate or cancel a scan for Bluetooth devices, and pair with Bluetooth devices. |
| ohos.permission.MANAGE_BLUETOOTH | system_basic | system_grant | TRUE | Allows an app to pair with a Bluetooth device and access the Contacts or messages of the device. |
| ohos.permission.INTERNET | normal | system_grant | TRUE | Allows an app to access the Internet. |
| ohos.permission.MODIFY_AUDIO_SETTINGS | normal | system_grant | TRUE | Allows an app to modify audio settings. |
| ohos.permission.GET_TELEPHONY_STATE | system_basic | system_grant | TRUE | Allows an app to read telephony information. |
| ohos.permission.REQUIRE_FORM | system_basic | system_grant | TRUE | Allows an app to obtain the Ability Form. |
| ohos.permission.GET_NETWORK_INFO | normal | system_grant | TRUE | Allows an app to obtain network information. |
| ohos.permission.PLACE_CALL | system_basic | system_grant | TRUE | Allows an app to make calls without starting the dialer. |
| ohos.permission.SET_NETWORK_INFO | normal | system_grant | TRUE | Allows an app to set data network information. |
| ohos.permission.REMOVE_CACHE_FILES | system_basic | system_grant | TRUE | Allows the cache of the specified app to be cleared. |
| ohos.permission.REBOOT | system_basic | system_grant | TRUE | Allows an app to restart the device. |
| ohos.permission.RUNNING_LOCK | normal | system_grant | TRUE | Allows an app to obtain a running lock. |
| ohos.permission.ENROLL_BIOMETRIC | system_core | system_grant | FALSE | Allows an app to add or remove biometric data. |
| ohos.permission.ACCESS_BIOMETRIC | normal | system_grant | FALSE | Allows an app to use biometric recognition for identity authentication. |
| ohos.permission.ACCESS_BIOMETRIC_INTERNAL | system_core | system_grant | FALSE | Allows an app to apply for or release biometric recognition resources. |
| ohos.permission.RESET_BIOMETRIC_LOCKOUT | system_core | system_grant | FALSE | Allows an app to reset the maximum number of failures allowed before biometric authentication is locked. |
| ohos.permission.SET_TIME | system_basic | system_grant | TRUE | Allows an app to set the system time. |
| ohos.permission.SET_TIME_ZONE | system_basic | system_grant | TRUE | Allows an app to set the system time zone. |
| ohos.permission.DOWNLOAD_SESSION_MANAGER | system_core | system_grant | TRUE | Allows an app to manage the downloaded sessions. |
| ohos.permission.COMMONEVENT_STICKY | normal | system_grant | TRUE | Allows an app to publish sticky common events. |
| ohos.permission.SYSTEM_FLOAT_WINDOW | normal | system_grant | TRUE | Allows an app to be displayed in a floating window on top of other apps. |
| ohos.permission.POWER_MANAGER | system_core | system_grant | TRUE | Allows an app to hibernate or wake up the device by calling APIs. |
| ohos.permission.REFRESH_USER_ACTION | system_basic | system_grant | TRUE | Allows an app to reset the screen timeout counter when a user input event occurs, such as pressing a key or tapping the screen. |
| ohos.permission.POWER_OPTIMIZATION | system_basic | system_grant | TRUE | Allows an app to set power saving mode, obtain configuration of the power saving mode, and receive notifications of the configuration changes.|
| ohos.permission.REBOOT_RECOVERY | system_basic | system_grant | TRUE | Allows an app to restart the device and enter Recovery mode. |
| ohos.permission.MANAGE_LOCAL_ACCOUNTS | system_basic | system_grant | TRUE | Allows an app to manage local user accounts. |
| ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | system_basic | system_grant | TRUE | Allows access between multiple OS accounts. |
| ohos.permission.VIBRATE | normal | system_grant | TRUE | Allows an app to control motor vibration. |
| ohos.permission.CONNECT_IME_ABILITY | system_core | system_grant | TRUE | Allows an app or service to bind the **InputMethodAbility**. |
| ohos.permission.CONNECT_SCREEN_SAVER_ABILITY | system_core | system_grant | TRUE | Allows an app or service to bind the **ScreenSaverAbility**. |
| ohos.permission.READ_SCREEN_SAVER | system_basic | system_grant | TRUE | Allows an app to read the screen saver information, such as the list of screen savers that have been installed and the activated one. |
| ohos.permission.WRITE_SCREEN_SAVER | system_basic | system_grant | TRUE | Allows an app to modify the screen saver information, such as activating and previewing a screen saver. |
| ohos.permission.SET_WALLPAPER | normal | system_grant | TRUE | Allows an app to set a static wallpaper. |
| ohos.permission.GET_WALLPAPER | system_basic | system_grant | TRUE | Allows an app to read wallpaper files. |
| ohos.permission.CHANGE_ABILITY_ENABLED_STATE | system_basic | system_grant | TRUE | Allows an app to enable or disable an app or component. |
| ohos.permission.ACCESS_MISSIONS | system_basic | system_grant | TRUE | Allows an app to obtain information about running processes and tasks in a task stack. |
| ohos.permission.CLEAN_BACKGROUND_PROCESSES | normal | system_grant | TRUE | Allows an app to clear background processes based on their bundle names. |
| ohos.permission.KEEP_BACKGROUND_RUNNING | normal | system_grant | TRUE | Allows a service ability to keep running in the background. |
| ohos.permission.UPDATE_CONFIGURATION | system_basic | system_grant | TRUE | Allows an app to modify system settings. |
| ohos.permission.GRANT_SENSITIVE_PERMISSIONS | system_core | system_grant | TRUE | Allows an app to grant sensitive permissions to other apps. |
| ohos.permission.REVOKE_SENSITIVE_PERMISSIONS | system_core | system_grant | TRUE | Allows an app to revoke sensitive permissions granted to other apps. |
| ohos.permission.GET_SENSITIVE_PERMISSIONS | system_core | system_grant | TRUE | Allows an app to obtain the sensitive permissions that have been granted to other apps. |
| ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION | system_core | system_grant | TRUE | Allows an app to set the attributes of apps of other users. |
| ohos.permission.LISTEN_BUNDLE_CHANGE | system_basic | system_grant | TRUE | Allows an app to listen for changes in other apps, when they are installed, updated, or uninstalled. |
| ohos.permission.GET_BUNDLE_INFO | normal | system_grant | TRUE | Allows a non-system app to obtain information about other apps. |
| ohos.permission.ACCELEROMETER | normal | system_grant | TRUE | Allows an app to read data from an acceleration sensor, uncalibrated acceleration sensor, or linear acceleration sensor. |
| ohos.permission.GYROSCOPE | normal | system_grant | TRUE | Allows an app to read data from a gyroscope sensor or uncalibrated gyroscope sensor. |
| ohos.permission.GET_BUNDLE_INFO_PRIVILEGED | system_basic | system_grant | TRUE | Allows a non-system app to obtain information about other apps. |
| ohos.permission.INSTALL_BUNDLE | system_core | system_grant | TRUE | Allows an app to install and uninstall other apps. |
| ohos.permission.MANAGE_SHORTCUTS | system_core | system_grant | TRUE | Allows an app to query and start shortcuts of other apps.|
| ohos.permission.radio.ACCESS_FM_AM | system_core | system_grant | TRUE | Allows an app to access radio services. |
| ohos.permission.SET_TELEPHONY_STATE | system_basic | system_grant | TRUE | Allows an app to change the telephone state. |
| ohos.permission.START_ABILIIES_FROM_BACKGROUND | system_basic | system_grant | TRUE | Allows an app to start Feature abilities in the background. |
| ohos.permission.BUNDLE_ACTIVE_INFO | system_basic | system_grant | TRUE | Allows an app to obtain how long other apps have been running in the foreground or background. |
| ohos.permission.START_INVISIBLE_ABILITY | system_core | system_grant | TRUE | Allows an app to start an invisible ability. |
| ohos.permission.sec.ACCESS_UDID | system_basic | system_grant | TRUE | Allows an app to obtain the Unified Device ID (UDID). |
| ohos.permission.LAUNCH_DATA_PRIVACY_CENTER | system_basic | system_grant | TRUE | Allows an app to switch from its privacy statement page to the <b>Data & privacy</b> page. |
| ohos.permission.MANAGE_MEDIA_RESOURCES | system_basic | system_grant | TRUE | Allows an app to obtain and manage the media resources that are being played on the device.|
| ohos.permission.PUBLISH_AGENT_REMINDER | normal | system_grant | TRUE | Allows an app to use agent-powered reminders. |
| ohos.permission.CONTROL_TASK_SYNC_ANIMATOR | system_core | system_grant | TRUE | Allows apps to use sync task animations. |
| ohos.permission.INPUT_MONITORING | system_core | system_grant | TRUE | Allows the app to listen for input events. Only the system signature apps can apply for this permission. |
| ohos.permission.MANAGE_MISSIONS | system_core | system_grant | TRUE | Allows users to manage ability task stacks. |
| ohos.permission.NOTIFICATION_CONTROLLER | system_core | system_grant | TRUE | Allows an app to manage and subscribe to notifications. Currently, only system apps can apply for this permission. |
| ohos.permission.CONNECTIVITY_INTERNAL | system_basic | system_grant | TRUE | Allows the app to obtain network information or modify network settings. Currently, only system apps can apply for this permission.|
| ohos.permission.ANSWER_CALL | system_basic | user_grant | TRUE | Allows the app to answer incoming calls. |
| ohos.permission.READ_CALENDAR | normal | user_grant | TRUE | Allows an app to read calendar data. |
| ohos.permission.READ_CALL_LOG | system_basic | user_grant | TRUE | Allows an app to read call logs. |
| ohos.permission.READ_CELL_MESSAGES | system_basic | user_grant | TRUE | Allows an app to read cell broadcast messages received by the device. |
| ohos.permission.READ_CONTACTS | system_basic | user_grant | TRUE | Allows an app to read contacts. |
| ohos.permission.READ_MESSAGES | system_basic | user_grant | TRUE | Allows an app to read messages. |
| ohos.permission.RECEIVE_MMS | system_basic | user_grant | TRUE | Allows the app to receive and process MMS messages. |
| ohos.permission.RECEIVE_SMS | system_basic | user_grant | TRUE | Allows the app to receive and process SMS messages. |
| ohos.permission.RECEIVE_WAP_MESSAGES | system_basic | user_grant | TRUE | Allows the app to receive and process WAP messages. |
| ohos.permission.MICROPHONE | normal | user_grant | TRUE | Allows an app to access the microphone. |
| ohos.permission.SEND_MESSAGES | system_basic | user_grant | TRUE | Allows an app to send messages. |
| ohos.permission.WRITE_CALENDAR | normal | user_grant | TRUE | Allows an app to add, remove, and modify calendar events. |
| ohos.permission.WRITE_CALL_LOG | system_basic | user_grant | TRUE | Allows an app to add, remove, and modify call logs. |
| ohos.permission.WRITE_CONTACTS | system_basic | user_grant | TRUE | Allows an app to add, remove, and modify contacts. |
| ohos.permission.DISTRIBUTED_DATASYNC | normal | user_grant | TRUE | Allows an app to exchange data with other devices. |
| ohos.permission.MANAGE_VOICEMAIL | system_basic | user_grant | TRUE | Allows an app to add messages in the voice mailbox. |
| ohos.permission.LOCATION_IN_BACKGROUND | normal | user_grant | FALSE | Allows an app running in the background to obtain the device location. |
| ohos.permission.LOCATION | normal | user_grant | TRUE | Allows an app to obtain the device location. |
| ohos.permission.MEDIA_LOCATION | normal | user_grant | TRUE | Allow an app to access geographical locations in the user's media file. |
| ohos.permission.CAMERA | normal | user_grant | TRUE | Allows an app to use the camera to take photos and record videos. |
| ohos.permission.READ_MEDIA | normal | user_grant | TRUE | Allows an app to read media files from the user's external storage. |
| ohos.permission.WRITE_MEDIA | normal | user_grant | TRUE | Allows an app to read media files from and write media files into the user's external storage. |
| ohos.permission.ACTIVITY_MOTION | normal | user_grant | TRUE | Allows an app to read the current workout status of the user. |
| ohos.permission.READ_HEALTH_DATA | normal | user_grant | TRUE | Allows an app to read the health data of the user. |
en/application-dev/security/huks-guidelines.md 0 → 100644
浏览文件 @ 15d48c92
# HUKS Development
## When to Use
Openharmony Universal KeyStore (HUKS) provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. HUKS also provides APIs for applications to import or generate keys.
## Available APIs
| API | Description |
| ------------------------------------------------------------ | ---------------- |
| function generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HksResult>) : void; | Generates a private key. This method uses an asynchronous callback to return the result. |
| function generateKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>; | Generates a private key. This method uses a promise to return the result. |
| function exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void; | Exports the public key. This method uses an asynchronous callback to return the result. |
| function exportKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>; | Exports the public key. This method uses a promise to return the result. |
| function isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback<boolean>) : void; | Check whether a key exists. This method uses an asynchronous callback to return the result.|
| function isKeyExist(keyAlias: string, options: HuksOptions) : Promise<boolean>; | Check whether a key exists. This method uses a promise to return the result.|
| function deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback<HuksResult>) : void; | Deletes a key. This method uses an asynchronous callback to return the result. |
| function deleteKey(keyAlias: string, options: HuksOptions) : Promise<HuksResult>; | Deletes a key. This method uses a promise to return the result. |
## How to Develop
1. Import the HUKS module.
```js
import huks from '@ohos.security.huks'
```
2. Call **generateKey()** to generate a private key.
**keyAlias** indicates the alias of the key generated. **options** indicates the parameters used for generating the key. Set **options** based on the actual situation.
The value returned indicates whether the key is successfully generated.
```js
var alias = 'testAlias';
var properties = new Array();
properties[0] = {
tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
value: huks.HuksKeyAlg.HUKS_ALG_ECC
};
properties[1] = {
tag: huks.HuksTag.HUKS_TAG_KEY_SIZE,
value: huks.HuksKeySize.HUKS_ECC_KEY_SIZE_224
};
properties[2] = {
tag: huks.HuksTag.HUKS_TAG_PURPOSE,
value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_AGREE
};
properties[3] = {
tag: huks.HuksTag.HUKS_TAG_DIGEST,
value: huks.HuksKeyDigest.HUKS_DIGEST_NONE
};
var options = {
properties: properties
}
var resultA = huks.generateKey(alias, options);
```
3. Call **Init()** to initialize the key.
**Alias** indicates the alias of the key to initialize, and **options** indicates the parameters used for initializing the key.
The value returned indicates whether the **Init** operation is successful.
```js
var alias = 'test001'
var properties = new Array();
properties[0] = {
tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
value: huks.HksKeyAlg.HKS_ALG_DH
};
properties[1] = {
tag: huks.HksTag.HKS_TAG_PURPOSE,
value: huks.HksKeyPurpose.HKS_KEY_PURPOSE_AGREE
};
properties[2] = {
tag: huks.HksTag.HKS_TAG_KEY_SIZE,
value: huks.HksKeySize.HKS_DH_KEY_SIZE_4096
};
var options = {
properties: properties
};
huks.init(alias, options, function(err, data) {
if (err.code !== 0) {
console.log("test init err information: " + JSON.stringify(err));
} else {
console.log(`test init data: ${JSON.stringify(data)}`);
}
})
```
4. Call **update()** to update the key.
**handle** indicates the session ID for updating the key. **options** indicates the parameters used for updating the key.
The value returned indicates whether the **Update** operation is successful.
```js
var properties = new Array();
properties[0] = {
tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
value: huks.HksKeyAlg.HKS_ALG_DH
};
properties[1] = {
tag: huks.HksTag.HKS_TAG_PURPOSE,
value: huks.HksKeyPurpose.HKS_KEY_PURPOSE_AGREE
};
properties[2] = {
tag: huks.HksTag.HKS_TAG_KEY_SIZE,
value: huks.HksKeySize.HKS_DH_KEY_SIZE_4096
};
var options = {
properties: properties
};
var result = huks.update(handle, options)
```
5. Call **finish()** to complete the operation.
**handle** indicates the session ID of the **Finish** operation. **options** indicates the parameters used for this operation.
The value returned indicates whether the **Finish** operation is successful.
```js
var properties = new Array();
properties[0] = {
tag: huks.HuksTag.HUKS_TAG_ALGORITHM,
value: huks.HksKeyAlg.HKS_ALG_DH
};
properties[1] = {
tag: huks.HksTag.HKS_TAG_PURPOSE,
value: huks.HksKeyPurpose.HKS_KEY_PURPOSE_AGREE
};
properties[2] = {
tag: huks.HksTag.HKS_TAG_KEY_SIZE,
value: huks.HksKeySize.HKS_DH_KEY_SIZE_4096
};
var options = {
properties: properties
};
var result = huks.finish(handle, options)
```
en/application-dev/security/huks-overview.md 0 → 100644
浏览文件 @ 15d48c92
# HUKS Overview
### Introduction
Openharmony Universal KeyStore (HUKS) provides KeyStore (KS) capabilities for applications, including key management and key cryptography operations. HUKS also provides APIs for applications to import or generate keys.
### Basic Concepts
- HUKS provides key management functions, including encryption and decryption, signing and signature verification, key agreement and derivation, and Hash-based Message Authentication Code (HMAC) calculation.
- HUKS supports the following algorithms: AES and RSA in encryption and decryption, RSA, ECC, DSA, and ED25519 in signing and signature verification, PBKDF2 in key derivation, and DH, ECDH, and X25519 in key agreement.
- HUKS uses the OpenSSL and Mbed TLS algorithm libraries.
### Working Principles
HUKS manages keys through the following operations:
- **Init**: reads the key, creates a session ID, and returns the session ID to the caller.
- **Update**: updates data by segment based on the session ID obtained.
- **Finish**: processes all data transferred to HUKS and then releases resources.
>![](../public_sys-resources/icon-notice.gif)**NOTICE**:<br/>If an error occurs in the **Init**, **Update**, or **Finish** operation, you must invoke the **Abort** operation to terminate the use of the key.
### Constraints
N/A
en/application-dev/security/userauth-guidelines.md
浏览文件 @ 15d48c92
# User Authentication Development # User Authentication Development
> ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**<br/>
> This development guide applies to the SDK of API Version 8 or later.
## When to Use ## When to Use
OpenHarmony supports 2D and 3D facial recognition that can be used for identity authentication during device unlocking, application login, and payment. 2D and 3D facial recognition used in identity authentication scenarios such as device unlocking, application login, and payment
## Available APIs ## Available APIs
The **userIAM\_userAuth** module provides methods for checking the support for biometric authentication, and performing and canceling authentication. You can perform authentication based on biometric features such as facial characteristics. Before performing biometric authentication, check whether your device supports this capability, including the authentication type, security level, and whether local authentication is used. If biometric authentication is not supported, consider using another authentication type. The following table lists methods in the APIs available for biometric authentication. The userIAM_userAuth module provides methods for checking the support for user authentication, and performing and canceling authentication. You can perform authentication based on biometric features such as facial characteristics. For more details, see [API Reference](../reference/apis/js-apis-useriam-userauth.md).
**Table 1** Methods available for biometric authentication Before performing authentication, check whether the device supports user authentication, including the authentication type and level. If user authentication is not supported, consider using another authentication type. The following table lists the APIs available for user authentication.
| Method | Description | **Table 1** APIs of user authentication
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| getAuthenticator(): Authenticator | Obtains an **Authenticator** object for user authentication. <sup>6+</sup><br>Obtains an **Authenticator** object to check the device's capability of user authentication, perform or cancel user authentication, and obtain the tips generated in the authentication process. <sup>7+</sup> |
| checkAvailability(type: AuthType, level: SecureLevel): number | Checks whether the device supports the specified authentication type and security level. |
| execute(type: AuthType, level: SecureLevel, callback: AsyncCallback\<number>): void | Performs user authentication and returns the authentication result using an asynchronous callback. |
| execute(type: AuthType, level: SecureLevel): Promise\<number> | Performs user authentication and returns the authentication result using a promise. |
| cancel(): void | Cancels the current authentication. |
| on(type: "tip", callback: Callback\<Tip>): void | Subscribes to the events of the specified type. |
| off(type: "tip", callback?: Callback\<Tip>): void | Unsubscribes from the events of the specified type. |
| API | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| getVersion() : number | Obtains the version information of an authentication object. |
| getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel) : number | Checks whether the device supports the specified authentication type and level.|
| auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLevel, callback: IUserAuthCallback): Uint8Array | Performs user authentication. This method uses asynchronous callback to return the result. |
| cancelAuth(contextID : Uint8Array) : number | Cancels an authentication. |
## How to Develop ## How to Develop
Before starting the development, make the following preparations: Before starting the development, make the following preparations:
1. Add the **ohos.permission.ACCESS\_BIOMETRIC** permission declaration to the application permission file. 1. Add the ohos.permission.ACCESS_BIOMETRIC permission declaration to the application permission file.
2. Add **import userIAM\_userAuth from '@ohos.userIAM.userAuth'** to the code file that provides biometric recognition. 2. Add **import userIAM_userAuth from '@ohos.userIAM.userAuth'** to the code file.
The development procedure is as follows: The development procedure is as follows:
1. Obtain an **Authenticator** singleton object. The sample code is as follows: 1. Obtain an **Authenticator** singleton object. The sample code is as follows:
``` ```js
let auth = userIAM_userAuth.getAuthenticator(); let auth = new userIAM_userAuth.UserAuth();
``` ```
2. Check whether the device provides the authentication capability of the specified level. 2. (Optional) Obtain the version information of the authenticated object.
2D facial recognition supports authentication lower than S2, and 3D facial recognition supports authentication lower than S3. The sample code is as follows: ```js
let auth = new userIAM_userAuth.UserAuth();
``` let version = auth.getVersion();
let authenticator = userIAM_userAuth.getAuthenticator(); console.info("auth version = " + version);
let checkCode = authenticator.checkAvailability("FACE_ONLY", "S2"); ```
if (checkCode == userIAM_userAuth.CheckAvailabilityResult.SUPPORTED) {
console.info("check auth support success"); 3. Check whether the device supports the authentication capabilities based on the specified authentication type and level.
} else {
console.error("check auth support fail, code = " + checkCode); ```js
} let auth = new userIAM_userAuth.UserAuth();
``` let checkCode = auth.getAvailableStatus(userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1);
if (checkCode == userIAM_userAuth.ResultCode.SUCCESS) {
3. \(Optional\) Subscribe to tip information. The sample code is as follows: console.info("check auth support success");
// Add the logic to be executed if the specified authentication type is supported.
``` } else {
let authenticator = userIAM_userAuth.getAuthenticator(); console.error("check auth support fail, code = " + checkCode);
let tipCallback = (tip)=>{ // Add the logic to be executed if the specified authentication type is not supported.
console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode +") event(" + }
tip.tipEvent + ") info(" + tip.tipInfo + ")"); ```
};
authenticator.on("tip", tipCallback); 4. Perform an authentication.
```
```js
4. Perform the authentication. The sample code is as follows: let auth = new userIAM_userAuth.UserAuth();
auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
``` onResult: (result, extraInfo) => {
let authenticator = userIAM_userAuth.getAuthenticator(); try {
authenticator.execute("FACE_ONLY", "S2").then((code)=>{ console.info("auth onResult result = " + result);
authenticator.off("tip", tipCallback); console.info("auth onResult extraInfo = " + JSON.stringify(extraInfo));
console.info("auth success"); if (result == 'SUCCESS') {
}).catch((code)=>{ // Add the logic to be executed when the authentication is successful.
authenticator.off("tip", tipCallback); } else {
console.error("auth fail, code = " + code); // Add the logic to be executed when the authentication fails.
}); }
``` } catch (e) {
console.info("auth onResult error = " + e);
5. \(Optional\) Unsubscribe from tip information if you have subscribed to tip information you have subscribed to tip information. }
},
```
let authenticator = userIAM_userAuth.getAuthenticator(); onAcquireInfo: (module, acquire, extraInfo) => {
let tipCallback = (tip)=>{ try {
console.info("receive tip: errorCode(" + tip.errorCode + ") code(" + tip.tipCode + ") event(" + console.info("auth onAcquireInfo module = " + module);
tip.tipEvent + ") info(" + tip.tipInfo + ")"); console.info("auth onAcquireInfo acquire = " + acquire);
}; console.info("auth onAcquireInfo extraInfo = " + JSON.stringify(extraInfo));
// Unsubscribe from a specified callback. } catch (e) {
authenticator.off("tip", tipCallback); console.info("auth onAcquireInfo error = " + e);
// Unsubscribe from all callbacks. }
authenticator.off("tip"); }
``` });
```
6. Cancel authentication. The sample code is as follows:
5. Cancel the authentication.
```
let authenticator = userIAM_userAuth.getAuthenticator(); ```js
let cancelCode = authenticator.cancel(); let auth = new userIAM_userAuth.UserAuth();
if (cancelCode == userIAM_userAuth.Result.SUCCESS) { // Obtain contextId using auth().
console.info("cancel auth success"); let contextId = auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLevel.ATL1, {
} else { onResult: (result, extraInfo) => {
console.error("cancel auth fail"); console.info("auth onResult result = " + result);
} },
```
onAcquireInfo: (module, acquire, extraInfo) => {
console.info("auth onAcquireInfo module = " + module);
}
});
let cancelCode = auth.cancel(contextId);
if (cancelCode == userIAM_userAuth.ResultCode.SUCCESS) {
console.info("cancel auth success");
} else {
console.error("cancel auth fail");
}
```
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或