1# Device Security Level Management 2 3 4 5## Introduction 6 7The OpenHarmony distributed technology can converge resources from different devices to form a Super Device. Poor security capabilities of any device may threaten the security of the Super Device. The Device Security Level Management (DSLM) module is introduced to manage the security levels of OpenHarmony devices. 8 9The security level of an OpenHarmony device depends on the system security capabilities of the device. The OpenHarmony system security capabilities are based on the root of trust (RoT) for boot, RoT for storage, and RoT for compute on the hardware. Security technologies and capabilities focus on device integrity protection, data confidentiality protection, and vulnerability defense. 10 11The figure below shows the OpenHarmony security architecture. 12 13 14 15The above figure shows the typical security architecture for a single device. The architecture may vary depending on the risk level as well as the software and hardware resources of the device. The security capabilities of OpenHarmony devices are classified into five levels from SL1 to SL5, based on the industry standard security classification model and actual OpenHarmony service scenarios and device types. In the OpenHarmony ecosystem, higher security levels include all the capabilities of lower security levels by default. The figure below shows the security levels of OpenHarmony devices. 16 17 18 19- SL1: SL1 is the lowest security level of OpenHarmony devices. Usually equipped with a lightweight operating system and low-end microprocessors, such devices implement simple services and do not need to process sensitive data. SL1 devices are required to support software integrity protection and eliminate common errors. Devices that cannot meet the requirements of SL1 can only be controlled by OpenHarmony devices. They cannot control OpenHarmony devices for more complex service collaboration. 20 21- SL2: OpenHarmony devices of SL2 can label their own data and define access control rules to implement discretionary access control (DAC). These devices must have basic anti-penetration capabilities. Devices of this level support a lightweight, secure, and isolated environment for deploying a small number of necessary security services. 22 23- OpenHarmony devices of SL3 have comprehensive security protection capabilities, and their operating systems have relatively complete security semantics and support mandatory access control (MAC). The system data can be structured as critical elements and non-critical elements. The critical elements are protected by a well-defined security policy model. Devices of this level must have certain anti-penetration capabilities to defend against common vulnerability exploits. 24 25- SL4: OpenHarmony devices of SL4 must have simplified trusted computing base (TCB) and come with anti-tampering capabilities. The implementation of SL4 should be concise and secure enough. Adequate authentication and arbitration are required for any access to critical elements. Devices of this level have considerable anti-penetration capabilities and can defend against most software attacks. 26 27- SL5: SL5 indicates the highest security protection capabilities for OpenHarmony devices. The system core software modules must have passed formal verification. Key hardware modules, such as the RoT and cryptographic computing engine, must be able to defend against physical attacks and attacks simulated in labs. Devices at this level must have high-security units, such as dedicated security chips, to enhance the boot, storage, and running of the root of trust (RoT). 28 29The security level of each device in a Super Device provides the decision-making criteria for processing or hopping various user data. 30 31For details about the relationship between data risk levels and device security levels, see [Data Transfer Management](https://gitee.com/openharmony/security_dataclassification). 32 33## Directory Structure 34 35The directory structure of the DSLM module is as follows: 36 37```undefined 38base/security/device_security_level 39├── baselib # Base library 40├── common # Common header files 41├── interfaces # Inner APIs 42├── oem_property # OEM adaptation 43├── profile # Component profiles 44├── services # Service framework code 45└── test # Test code 46``` 47 48## Constraints 49 50- Only C and C++ are supported. 51- The default security level of OpenHarmony devices is SL1. Device vendors can [customize](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-security-devicesecuritylevel.md#customizing-device-security-levels) a higher security level as required. 52 53## Description 54 55### Available APIs 56 57When different types of user data are hopped or processed in OpenHarmony distributed devices, the DSLM APIs can be called to obtain the security levels of related devices for subsequent processing. 58 59| API | Description | 60| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | 61| int32_t RequestDeviceSecurityInfo(const DeviceIdentify \*identify, const RequestOption \*option, DeviceSecurityInfo **info); | Requests the security level information of a device synchronously.| 62| int32_t RequestDeviceSecurityInfoAsync(const DeviceIdentify \*identify, const RequestOption \*option, DeviceSecurityInfoCallback callback); | Requests the security level information of a device asynchronously.| 63| void FreeDeviceSecurityInfo(DeviceSecurityInfo \*info); | Releases the device security level information. | 64| int32_t GetDeviceSecurityLevelValue(const DeviceSecurityInfo \*info, int32_t \*level); | Obtains the device security level from the security level information. | 65 66### Usage 67 68All the APIs are native C interfaces for implementing underlying capabilities and are not open to apps. 69 70- Adding Dependencies 71 721. Add the dependencies for compilation. 73 74 ```undefined 75 external_deps += [ "device_security_level:dslm_sdk" ] 76 ``` 77 782. Add the header files of dependencies. 79 80 ```cpp 81 #include "device_security_defines.h" // Header file for defining critical data structures. 82 #include "device_security_info.h" // Header file for defining APIs. 83 ``` 84 85- Example 86 87The following is an example of synchronously obtaining the device security level: 88 89```cpp 90void CheckDestDeviceSecurityLevel(const DeviceIdentify *device, RequestOption *option) 91{ 92 // Pointer to the device security level information. 93 DeviceSecurityInfo *info = NULL; 94 95 // Obtain the security level information of the device. 96 int32_t ret = RequestDeviceSecurityInfo(device, option, &info); 97 if (ret != SUCCESS) { 98 // Failed to obtain the information. You can develop a retry process as required. 99 return; 100 } 101 int32_t level = 0; 102 // Obtain the device security level from the security level information. 103 ret = GetDeviceSecurityLevelValue(info, &level); 104 if (ret != SUCCESS) { 105 // Failed to obtain the device security level. You can develop a retry process as required. 106 FreeDeviceSecurityInfo(info); 107 return; 108 } 109 110 // After the device security level is successfully obtained, check the lowest security level required for the current operation. 111 // The lowest device security level required for the current operation is 3. 112 if (level >= 3) { 113 // The security level of the target device meets the requirements. Services are processed properly. 114 } else { 115 // The security level of the target device does not meet the requirements. A toast or dialog box is displayed as required. 116 } 117 118 // Release the memory before the processing is complete. 119 FreeDeviceSecurityInfo(info); 120} 121``` 122 123The following is an example of asynchronously obtaining the device security level: 124 125```cpp 126// Callback 127void DeviceSecurityInfoCallback(const DeviceIdentify *identify, struct DeviceSecurityInfo *info) 128{ 129 int32_t level = 0; 130 // Obtain the device security level from the security level information. 131 int32_t ret = GetDeviceSecurityLevelValue(info, &level); 132 if (ret != SUCCESS) { 133 // Failed to obtain the information. You can develop a retry process as required. 134 FreeDeviceSecurityInfo(info); 135 return; 136 } 137 138 // After the device security level is successfully obtained, check the lowest security level required for the current operation. 139 // The lowest device security level required for the current operation is 3. 140 if (level >= 3) { 141 // The security level of the target device meets the requirements. Services are processed properly. 142 } else { 143 // The security level of the target device does not meet the requirements. A toast or dialog box is displayed as required. 144 } 145 146 // Release the memory before the processing is complete. 147 FreeDeviceSecurityInfo(info); 148} 149 150void CheckDestDeviceSecurityLevelAsync(const DeviceIdentify *device, RequestOption *option) 151{ 152 // Invoke the asynchronous callback to return the device security level obtained. 153 int ret = RequestDeviceSecurityInfoAsync(device, option, DeviceSecurityInfoCallback); 154 if (ret != SUCCESS) { 155 // Failed to obtain the device security level. You can develop a retry process as required. 156 // In this case, the callback will not be invoked. 157 return; 158 } 159 // The callback is invoked. Wait for the callback to return the device security level. 160} 161``` 162 163## Change Log 164 165- V 1.0 166 167## Repositories Involved 168 169[Data Transfer Management](https://gitee.com/openharmony/security_dataclassification) 170 171[**Device Security Level Management**](https://gitee.com/openharmony/security_device_security_level) 172 173[HUKS](https://gitee.com/openharmony/security_huks) 174 175[Application Permission Management](https://gitee.com/openharmony/security_permission) 176 177[Device Authentication](https://gitee.com/openharmony/security_device_auth) 178 179[SELinux](https://gitee.com/openharmony/security_selinux) 180
