# Development Guidelines on Device Security Level Management
## Overview
### DSLM
The OpenHarmony distributed technology can converge resources of different devices and virtualize multiple devices into a Super Device. When different types of user data are hopped or processed in the Super Device, poor security capabilities of any device may threaten the security of the Super Device.
The OpenHarmony Device Security Level Management (DSLM) module is introduced to manage the security levels of OpenHarmony devices. When different types of user data are hopped or processed in OpenHarmony distributed services, the DSLM APIs can be called to obtain the security levels of related devices for subsequent processing.
### Basic Concepts
- Device security level
The 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.
The following figure shows the OpenHarmony security architecture.
The 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 an 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.
- 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 can only be controlled by OpenHarmony devices and cannot control OpenHarmony devices for more complex service collaboration.
- 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.
- SL3: 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.
- 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.
- 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 startup, storage, and running of the root of trust (RoT).
- DSLM
DSLM is a module for OpenHarmony device security level management. It verifies and updates device security level information for OpenHarmony devices in collaboration. It also provides an interface for querying the security level of each device.
### WOrking Principles
The security level of each device in a Super Device provides the decision-making criteria for processing or hopping various user data. For example, the distributed file storage service does not allow sensitive data to be stored on devices with security level lower than SL3.
### Constraints
The default security level of OpenHarmony devices is SL1. Device manufacturers can customize a higher security level based on service requirements. For details, see [Customizing Device Security Levels](#Customizing_Device_Security_Levels).
## Development Guidelines
### When to Use
When processing or hopping various user data, the subsystems can invoke the APIs provided by the DSLM module to obtain the security level information of related devices. Then, the subsystems determine the subsequent processing based on the security level and data to be processed.
### Available APIs
All the APIs are native C interfaces for implementing underlying capabilities and are not open to apps. The APIs are described as follows:
| int32_t RequestDeviceSecurityInfo(const DeviceIdentify \*identify, const RequestOption \*option, DeviceSecurityInfo \*\*info); | Requests the security level information of a device synchronously.|
| int32_t RequestDeviceSecurityInfoAsync(const DeviceIdentify \*identify, const RequestOption \*option, DeviceSecurityInfoCallback callback); | Requests the security level information of a device asynchronously.|
// Define a pointer to the device security level obtained.
DeviceSecurityInfo *info = NULL;
// Call RequestDeviceSecurityInfo to obtain the device security level information of the peer device.
int32_t ret = RequestDeviceSecurityInfo(device, DEFAULT_OPTION, &info);
int32_t level = 0;
// Obtain the device security level from the device security level information.
ret = GetDeviceSecurityLevelValue(info, &level);
if (ret == SUCCESS) {
// The operation is successful.
return;
}
// Release the memory before the processing is complete.
FreeDeviceSecurityInfo(info);
```
### Development Example
A service with file sharing function needs to be developed. To prevent sensitive files from being shared unintentionally, the following judgments must be performed before any file is sent:
- If the security level of the destination device is SL3 or higher, send the file.
- If the security level of the destination device is lower than SL3, deny the file transfer and display a dialog box to notify the user.
**Example of synchronously obtaining the device security level**
// Failed to obtain the security level. You can develop a retry process as required.
// In this case, the callback will not be invoked.
return;
}
// The callback is invoked. Wait for the callback to return the device security level.
}
```
## Customizing Device Security Levels
### Device Security Level Credential
To ensure its integrity and non-repudiation, the security level information must be encapsulated in a "device security level credential" (credential for short) file for transmission between devices. In addition to the security level information of the device, the credential may include device attributes, such as the device model and version. Moreover, the credential must be signed using the public key infrastructure (PKI) technology. Other basic security capabilities of OpenHarmony, such as [Device Authentication] (https://gitee.com/openharmony/security_deviceauth) and [HUKS](https://gitee.com/openharmony/security_huks), are used to ensure secure transmission of credentials.
### Default Implementation
The DSLM module provides default implementation of security level information synchronization and verification. It is assumed that the security level of all OpenHarmony devices is SL1, and a loose verification scheme is used. For details, see the [source code] (https://gitee.com/openharmony/security_device_security_level/tree/master/oem_property/ohos).
You can change the device security level as required. For details about the OpenHarmony device security levels, see [Basic Concepts](#Basic_Concepts). You can also use more severe verification schemes, including but are not limited to using device-specific credential, periodically downloading updated credentials from a server and strictly authenticating the issuer and validity period of the credentials, and using Trusted Execution Environment (TEE) or even Secure Element (SE) for signing credential files.
### Generating a Credential File
The credential file consists of four Base64-encoded strings, separated by periods (.). The following is an example:
The Elliptic Curve Digital Signature algorithm (ECDSA) is used to sign the raw data in the credential file. Generate an ECDSA key pair `<ecc-l3-pk>` and `<ecc-l3-sk>` first.
> This step must be performed in a secure and reliable environment, for example, a cryptographic machine that meets related security requirements, to ensure that the key used for signature is not disclosed.
##### 3.3 Sign the raw data.
Use the ECC private key `<ecc-l3-sk>` to sign `<base64-head>.<base64-payload>`, and encode the signature to Base64 format to obtain `<base64-signature>`.
> This step must be performed in a secure and reliable environment, for example, a cryptographic machine that meets related security requirements, to ensure that the key used for signature is not disclosed.
> The key pairs involved in this step do not need to be generated each time. Secure key pairs can be directly reused.
Put the four pieces of data together with a period (.) in between to obtain `<base64-header>.<base64-payload>.<base64-signature>.<base64-attestation>`. The following is an example:
When detecting a device goes online, the DSLM module requests the device security level credential from the device through the channel provided by [DSoftBus](https://gitee.com/openharmony/communication_dsoftbus).
The packet for requesting the credential is in the following format:
``` json
{
"message":1,
"payload":{
"version":196608,
"challenge":"0102030405060708",
"support":[
300
]
}
}
```
The fields in the request message are described as follows:
| message | Message header. The value **2** indicates a response to the request for the device security level credential.|
| payload | Message payload, which is the specific response information.|
| version | Version of the protocol used by the responder. |
| type | Format of the credential returned, which describes how to parse the **info** field.|
| challenge | Challenge value corresponding to this response message.|
| info | Signed credential information, which also includes the device information and challenge value verification information.|
### Tool
The DSLM module provides a [credential tool](https://gitee.com/openharmony/security_device_security_level/blob/master/oem_property/ohos/dslm_cred_tool.py) to help you better understand the issuing and verification of credentials. This tool is a Python script encapsulated with OpenSSL commands.
You can use the tool as follows:
1. Initialize the signature key.
``` undefined
./dslm_cred_tool.py init
```
2. Generate a credential.
For example, to generate a credential file **cred.txt** with the device model of **rk3568**, device version of **3.0.0**, and device security level of **SL3**, run the following command:
- Q: How can I use the credential tool in a real production environment?
A: The credential tool cannot be directly used in the production environment. It is used to demonstrate the format and generation process of credentials. In a real production environment, you are advised to generate credentials and save related keys in a cryptographic machine that meets related security requirements.
- Q: How do I verify a credential in a real production environment?
A: You are advised to use a properly kept private key to sign the credential and use more severe signature verification process instead of the default verification process provided by the DSLM module. For example, allow only the credentials issued by trusted certification authority (CA), and bind the credential and device ID to enhance the security.
The OpenHarmony security subsystem provides security capabilities that make your applications and devices more secure and help you manage permissions. This subsystem has the following modules:
- Application signature verification
To ensure the content integrity of applications, the system controls sources of the applications through application signatures and profiles. For a debugging application, the system uses the signature verification API to check whether the Unique Device Identifier \(UDID\) of the application matches that of the device, so as to ensure that the application is installed on the right device.
To ensure the content integrity of applications, the system controls sources of the applications through application signatures and profiles. For a debugging application, the system uses the signature verification API to check whether the Unique Device Identifier (UDID) of the application matches that of the device, so as to ensure that the application is installed on the right device.
- Application permission management
...
...
@@ -12,7 +13,11 @@ The OpenHarmony security subsystem provides security capabilities that make your
- Trusted device group management
You can create and query a group of trusted devices that use the same ID or a peer-to-peer group created by scanning a QR code or using OneHop. With this capability, distributed applications can perform trusted authentication between devices and request from the distributed virtual bus for secure sessions between devices.
You can create and query a group of trusted devices that use the same HUAWEI ID or a peer-to-peer group created by scanning a QR code or using OneHop. With this capability, distributed applications can perform trusted authentication between devices and request from the distributed virtual bus for secure sessions between devices.
- DSLM
The OpenHarmony Device Security Level Management (DSLM) module manages the security levels of OpenHarmony devices. When different types of user data are hopped or processed in OpenHarmony distributed services, the DSLM APIs can be called to obtain the security levels of related devices for subsequent processing.
@@ -21,22 +26,22 @@ Before developing an application that depends on the signature verification comp
- Samgr
System Ability Manager \(Samgr\) is a module of OpenHarmony for managing system capabilities. For details, see the Application Framework development guidelines.
System Ability Manager (Samgr) is a module of OpenHarmony for managing system capabilities. For details, see the Application Framework development guidelines.
- BMS
Bundle Manager Service \(BMS\) manages application installation, uninstallation, and data on OpenHarmony.
Bundle Manager Service (BMS) manages application installation, uninstallation, and data on OpenHarmony.
- Profile
The profile in this document refers to HarmonyAppProvision \(profile for short\). HarmonyAppProvision is in JSON format.
The profile in this document refers to HarmonyAppProvision (profile for short). HarmonyAppProvision is in JSON format.
- Debugging application
A debugging application is a HAP that is signed with a debugging certificate and profile obtained from the application market.
A debugging application is a HarmonyOS Ability Package (HAP) that is signed with a debugging certificate and profile obtained from the application market.
- Released application
...
...
@@ -46,11 +51,10 @@ Before developing an application that depends on the signature verification comp
- OpenHarmony self-signed application
A self-signed application is one that has been signed with the signing certificate and profile issued by OpenHarmony's open-source root CA, which is comprised of a certificate and a key.
A self-signed application is one that has been signed with the signing certificate and profile issued by OpenHarmony's open-source root CA, which consists of a certificate and a key.
## Limitations and Constraints<a name="section2029921310472"></a>
## Constraints<a name="section2029921310472"></a>
- Only signatures of debugging, released, and OpenHarmony self-signed applications can be verified.
- To verify the signature of a debugging application, the UDID of the device on which the debugging application is installed must be in the UDID list contained in the profile.
