1# Access Control by Device and Data Level (ArkTS) 2 3 4## Basic Concepts 5 6Distributed data management implements access control based on data security labels and device security levels. 7 8A higher data security label and device security level indicate stricter encryption and access control measures and higher data security. 9 10 11### Data Security Labels 12 13The data can be rated into four security levels: S1, S2, S3, and S4. 14 15| Risk Level| Security Level| Definition| Example| 16| -------- | -------- | -------- | -------- | 17| Critical| S4 | Special data types defined by industry laws and regulations, involving the most private individual information or data that may cause severe adverse impact on an individual or group once disclosed, tampered with, corrupted, or destroyed.| Political opinions, religious and philosophical belief, trade union membership, genetic data, biological information, health and sexual life status, sexual orientation, device authentication, and personal credit card information| 18| High| S3 | Data that may cause critical adverse impact on an individual or group once disclosed, tampered with, corrupted, or destroyed.| Individual real-time precise positioning information and movement trajectory| 19| Moderate| S2 | Data that may cause major adverse impact on an individual or group once disclosed, tampered with, corrupted, or destroyed.| Detailed addresses and nicknames of individuals| 20| Low| S1 | Data that may cause minor adverse impact on an individual or group once disclosed, tampered with, corrupted, or destroyed.| Gender, nationality, and user application records| 21 22 23### Device Security Levels 24<!--RP1--> 25Device security levels are classified into SL1 to SL5 based on devices' security capabilities, for example, whether a Trusted Execution Environment (TEE) or a secure storage chip is available. For example, the development boards RK3568 and Hi3516 are SL1 (lower security) devices, and tablets are SL4 (higher security) devices. 26 27During device networking, you can run the **hidumper -s 3511** command to query the device security level. The following example shows how to query the security level of the RK3568 board: 28<!--RP1End--> 29<!--Del--> 30 31<!--DelEnd--> 32 33## Access Control Mechanism in Cross-Device Sync 34 35In cross-device data sync, data access is controlled based on the device security level and data security labels. In principle, data can be synced only to the devices whose data security labels are not higher than the device's security level. The access control matrix is as follows: 36 37|Device Security Level|Data Security Labels of the Synchronizable Device| 38|---|---| 39|SL1|S1| 40|SL2|S1 to S2| 41|SL3|S1 to S3| 42|SL4|S1 to S4| 43|SL5|S1 to S4| 44<!--RP2--> 45For example, the security level of development boards RK3568 and Hi3516 is SL1. The database with data security label S1 can be synced with RK3568 and Hi3516, but the databases with database labels S2-S4 cannot. 46<!--RP2End--> 47 48## When to Use 49 50The access control mechanism ensures secure data storage and sync across devices. When creating a database, you need to correctly set the security level for the database. 51 52 53## Setting the Security Level for a KV Store 54 55When a KV store is created, the **securityLevel** parameter specifies the security level of the KV store. The following example shows how to create a KV store with security level of S3. 56 57For details about the APIs, see [Distributed KV Store](../reference/apis-arkdata/js-apis-distributedKVStore.md). 58> **NOTE** 59> 60> For the scenarios involving a single device, you can upgrade the security level of a KV store by modifying the **securityLevel** parameter. When upgrading the database security level, observe the following: 61> * This operation does not apply to the databases that require cross-device sync. Data cannot be synced between databases of different security levels. If you want to upgrade the security level of a database that requires cross-device sync, you are advised to create a database of a higher security level. 62> * You need to close the database before modifying the **securityLevel** parameter, and open it after the security level is upgraded. 63> * You cannot downgrade the database security level. For example, you can change the database security level from S2 to S3, but cannot change it from S3 to S2. 64 65 66```ts 67import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit'; 68import { hilog } from '@kit.PerformanceAnalysisKit'; 69import { distributedKVStore } from '@kit.ArkData'; 70import { BusinessError } from '@kit.BasicServicesKit'; 71 72export default class EntryAbility extends UIAbility { 73 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 74 this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET); 75 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 76 let kvManager: distributedKVStore.KVManager; 77 let kvStore: distributedKVStore.SingleKVStore; 78 let context = this.context; 79 const kvManagerConfig: distributedKVStore.KVManagerConfig = { 80 context: context, 81 bundleName: 'com.example.datamanagertest' 82 } 83 try { 84 kvManager = distributedKVStore.createKVManager(kvManagerConfig); 85 console.info('Succeeded in creating KVManager.'); 86 try { 87 const options: distributedKVStore.Options = { 88 createIfMissing: true, 89 encrypt: true, 90 backup: false, 91 autoSync: false, 92 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 93 securityLevel: distributedKVStore.SecurityLevel.S3 94 }; 95 kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => { 96 if (err) { 97 console.error(`Failed to get KVStore. Code:${err.code},message:${err.message}`); 98 return; 99 } 100 console.info('Succeeded in getting KVStore.'); 101 kvStore = store; 102 }); 103 } catch (e) { 104 let error = e as BusinessError; 105 console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`); 106 } 107 } catch (e) { 108 let error = e as BusinessError; 109 console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`); 110 } 111 } 112} 113``` 114 115## Setting the Security Level for an RDB Store 116 117When an RDB store is created, the **securityLevel** parameter specifies the security level of the RDB store. The following example shows how to create an RDB store with security level of S3. 118 119For details about the APIs, see [RDB Store](../reference/apis-arkdata/js-apis-data-relationalStore.md). 120 121```ts 122import { UIAbility } from '@kit.AbilityKit'; 123import { relationalStore } from '@kit.ArkData'; 124import { BusinessError } from '@kit.BasicServicesKit'; 125 126export default class EntryAbility extends UIAbility { 127 async onCreate(): Promise<void> { 128 let store: relationalStore.RdbStore | undefined = undefined; 129 let context = this.context; 130 131 try { 132 const STORE_CONFIG: relationalStore.StoreConfig = { 133 name: 'RdbTest.db', 134 securityLevel: relationalStore.SecurityLevel.S3 135 }; 136 store = await relationalStore.getRdbStore(context, STORE_CONFIG); 137 console.info('Succeeded in getting RdbStore.') 138 } catch (e) { 139 const err = e as BusinessError; 140 console.error(`Failed to get RdbStore. Code:${err.code}, message:${err.message}`); 141 } 142 } 143} 144``` 145
