If you already familiar with the following concepts, you can skip this section and go to Security Policy of webOS OSE.
- Luna Bus
- Service provider and client
This guide describes the security policy of webOS OSE and how to set it up correctly.
First you need to know about webOS OSE’s communication system, Luna Bus.
Luna Bus, also called LS2, is the bus communication system of webOS OSE platform. Processes running on the platform communicate with each other through Luna Bus.
Components can be classified into service provider and service client:
Communication between processes is established using LS2 API. LS2 API is an interface to access webOS system services via Luna Bus. Using LS2 API, each process can access any other processes registered on Luna Bus. To prevent unauthorized access, LS2 API introduces Access Control Group (ACG) and Trust Level.
A security policy of webOS OSE consists of two values: ACG and Trust Level.
Service providers and clients have their own ACG and Trust Level values. When a client sends a request to a provider, Luna Bus examines the values of both the provider and the client. If the client’s ACG or Trust Level values don’t match with the provider’s values, Luna Bus rejects the request.
The following figure shows this process.
In the above figure, the client has
acg_a for ACG and
trust_level_a for its Trust Level.
Let’s suppose that the client sends a request for calling
Method A belongs to
acg_a belongs to
Method A’s values are as follows:
Which match with those of the client. So the client can call
But in the case of
Method B, the Trust Level is
trust_level_a, but the ACG value is
acg_b. So the client cannot to call
Trust Level defines an access level of each ACG. Below are the trust levels supported in webOS OSE:
dev: APIs belonging to this trust level can be accessed by all trust levels.
part: APIs belonging to this trust level can be accessed by
oem: APIs belonging to this trust level can only be accessed by
The following table summarizes this access limitation.
|Trust level of your service
Suppose your service has
dev trust level (the
trustLevel attribute of the role file is set to
dev). Your service cannot access APIs of other services belonging to the
The following table shows the files related to ACG and trust level.
For Trust Level
Set up the
No need to set up. Trust level is set to
Set up the
Set up Configuration files.
If you develop apps or external services, all you need to do is set up the
requiredPermissions property in
appinfo.json. In case of external services, use the
appinfo.json file of the app packaged together with the service.
The following example shows how to set up an ACG value at the
appinfo.json file. This app can access to services whose ACG value is
If you develop built-in services, you need to set up your own configuration files. A list of required files can vary depending on the service you want to develop.
For more details on how to set up each file, see to Configuration Files.
Components of webOS OSE need a certain types of files to operate properly on the Luna Bus. These files are called LS2 configuration files.
The following table shows the types of configuration files and :
|API permission file
|Client permission file
If a component (either a service client or a service provider) wants to register itself to Luna Bus, the component must provide its logical name to the Luna Bus system. The role file contains this logical name and information about permissions. Luna Bus determines whether to accept or deny the registration request based on the information given in the role file.
A role file has the following attributes:
|Absolute path of the binary executable for the component. Script-based components such as JS services, web apps, and QML apps, do not have a unique executable name. Such components use
appId instead of
|Service type (regular / privileged / devmode). Only privileged services are allowed to change ID during execution.
|Trust level of the service.
|Names to register to Luna Bus. It can be an array of any valid service name strings.
List of inbound and outbound policies for the specified service name. Different permissions can be assigned to different service names.
outbound list can include strings of any valid service names. Use
* for all, empty array
 for none. It is possible to use a wildcard (
*) at the end of a string.
The following code shows an example of role file:
The following code shows an example of role file for script-based components:
|An example role file for script-based components
If you need to register a component during runtime, use the
ls-control command to send the request to the Luna Bus system to update its policy.
$ ls-control scan-services
You can use
ls-control to inform the hub to rescan directories only when the component was installed by using the
This file defines ACG values for each methods in the service. Every LS2 API mehods has an ACG value. Typically, the same ACG value is given to the methods with similar functionality.
The following example shows how to define ACG values for multiple methods of the
If a client wants to call the
com.example.service.native/hello method, the client must contain
exampleservice.acgvalue1 in its ACG values.
This file defines the trust levels of each ACG value. The following example shows an example group file.
In the above example, a trust level,
dev, is assigned to the ACG value,
exampleservice.acgvalue1. So the APIs in
exampleservice.acgvalue1 have the
dev trust level.
A service file, also called a service configuration file, contains descriptions of the service type and launch command.
webOS OSE has two service types: static and dynamic.
A service file has the following attributes:
|Executable path for service
|Type of service
The following code shows an example service file:
All clients (services and applications that use other services) must have a client permission file. You have to check what ACG values are needed and add them to the client permission file. This process is very similar to setting up
Suppose that you want to use the
launch method of
Check the ACG value of the method —
Add it to the client permission file.
The easiest way to find the ACG value is to check LS2 API Reference documents.
Every method in the API reference shows its own ACG value. For example, an ACG value for the createToast method is
notification.opration as shown in the below figure.
The other way is to use the
ls-monitor -i command.
root@raspberrypi4-64:/# ls-monitor -i com.webos.notification | grep "createToast"