This document contains information about the OGEMA security sub system as it supported in the current reference implementation and related to the user of the framework. For further details about the conceptional ideas and the whole context of the of OGEMA security please ask for the 'Security Specification for OGEMA 2.0'
In this section an application means not only the OGEMA applications which are special bundles that export the OGEMA defined service org.ogema.core.application.Application but it means any other bundle like a driver bundle or a general service provider bundle too.
In this section information are provided for OGEMA user that show how to deal with OGEMA security as it's implemented in the latest release of the framework. The content of this document describes:
- the way to deal with security as an application or driver developer,
- general settings to control the security sub-system,
- the mechanisms that support the preconfiguration of the security and users in a static way,
- the usage of OGEMA specific permissions,
- the administration interface to create and change the permission configuration for application,
- worth knowing things related to the web access management.
The table below lists the files that are involved in the security configuration.
|ogema.policy||./config||The pre-configuration of the policy table, that is setup at the startup time before any application code is executed, can be defined in this file. It contains a list of policies as specified in section '50.4 Conditional Permissions' of the "OSGi Core release 5, March 2012". This file may contain comment lines that should start with '#' or "//".|
|ogema.roles||./config||With this file the user pre-configuration can be defined. The format of the entries is similar to the entries in ogema.policy. It is explained precisely in the section 'User Management' below. This file may contain comment lines that should start with '#' or "//".|
(as entry of the application jar file)
|The application bundle file could include such a file as entry, that contains the descriptions of the permissions demanded by the application. The format of the entries is specified in section '50.10 Bundle Permission Resoource' of the "OSGi Core release 5, March 2012".|
Since OGEMA security bases on Java and OSGi security the effective permission for an application is determined as
Among other things in the following sections the different portions of the effective permissions are explained.
- 1 Local Permissions
- 2 System Permissions
- 2.1 Default Permissions
- 2.2 Applications specific Permissions
- 2.2.1 PackagePermission
- 2.2.2 ServicePermission
- 2.2.3 Common Java Permissions
- 2.2.4 OGEMA Defined Permission
- 3 Implied Permissions
- 4 Effective Permissions
- 5 Security Configuration GUI
- 6 OGEMA ResourcePermission
- 7 User Management
- 8 Access Control on REST Interface
- 9 Configuration Properties
- 10 When do I need which permissions
- 11 References
The local permissions are those, who are demanded by the application. The permission demands are put as entries in the permissions.perm file provided by the application as bundle archive entry as described in the table above..
The permissions.perm file is an optional entry of the bundle file. If this entry doesn't exist means that the application/driver doesn't limit the demanded permissions at all. But in this case the administrator doesn't get any hints which permissions are needed by the application. In this case the administrator has to grant AllPermission to ensure that the application works properly. But this is an undesirable situation in term of the security. If the application needs any permissions the developer should create a permissions.perm file enter all of the needed permissions therein. The permissions.perm file consists of any number of entries of following format where each entry consists of one line. N is the possible number of the occurrence of the element.
An example permissions.perm file is given at the end of the explanations related to the portions of the Effective Permissions.
The system permission as a portion of the effective permissions for an application are those permissions, who are granted to the application in any way. In OGEMA there are two different ways to change permission configuration.
- The static way allows to grant or deny permission by putting the required information into the policy file ogema.policy. In following the format of a policy definition in ogema.policy file is described.
The examples below show two types of policies the conditional and unconditional policy.
To see an example ogema.policy file click here.
- The dynamic way allows to change the permission configuration via an administrative GUI.
A system permission can be granted to a specific application or a group of applications or it can be application non-specific, which means that the permission is applied to all applications. These two different types of permissions are explained in the following sections. In these examinations we refer to the static way to set policies via ogema.policy file.
The default permissions are an portion of the system permissions in OGEMA. These permissions are defined in ogema.policy file in one or more unconditional policy entries. Such a policy entry could look like this:
The current default permissions configuration results in the following list:
That is the minimum set of permissions granted to all applications in OGEMA. These permissions don't need to be granted explicitly by the framework administration.
Note that these permissions should be put in the permissions.perm file, otherwise granting of such a permission wouldn't have any effect.
Applications specific Permissions
When OGEMA security is enabled, an application will need certain permissions to perform security sensitive actions. A set of are defined that are granted to all applications. In other cases the permission will be granted to the application explicitly which are the other portion of the System Permissions. The most used permissions are discussed in the sections below
The packages that match org.ogema.core.* and org.osgi.framework are already granted trough the, thats why they don't need to be granted explicitly to this application. This results in the following PackagePermission's that the driver needs to get them granted.
That means these two permissions are to be granted in the ogema.policy file to the application modbus-rtu.
Applications need to have a ServicePermission to be able to register or get OSGi services. Normally OGEMA deals with ServicePermissions very restrictively, because the service communication between applications is difficult to control in security context. However there are exceptional cases where ServicePermission is granted to applications. The example application modbus-rtu has the special function of an so called OGEMA low level driver. One of the permissions that has to be additionally granted to all drivers is the following ServicePermission.
This permission is required because the driver should register an instance of this service to be registered as a low level driver in the system. Another permissions that could be required by an driver is the service permission to get the HardwareManager service reference of the system. It is expressed as:
Common Java Permissions
Beyond the OSGi specific permissions as described above the application might need other standard java permissions like java.io.FilePermission, java.util.PropertyPermission, .... For detailed information to the actions and the format of name strings of the standard java permissions see the official API documentation, e.g. http://docs.oracle.com/javase/7/docs/technotes/guides/security/permissions.html. The example application modbus-rtu gets the subsequent java standard permissions.
OGEMA Defined Permission
In OGEMA some permissions are defined to control the access to OGEMA specific resources. The usage of these permissions is described in the subsequent sections.
ResourcePermission protects the tree of OGEMA 2.0 related resources.Generally a ResourcePermission is formed as
The filter string is a comma separated key-value pair like “type= org.ogema.model.devices.buildingtechnology.AirConditioner,path=*,count=12”. The meanings of the possible keys are as follows.
- path: The path information of a resource instance. The value can contain a wildcard. Valid values for this parameter are for instance; “*”, “/myResource/theSubresource/*”, “/theTopLevel/firstChild/leaveResource”. A Value like “/myResource/theSubresource/*/leafValue” is invalid because the wildcard shall be at the end of the path string.
Note that the path should start with a slash.
- type: Fully qualified name of the type definition class. This parameter shall not consist of a wildcarded name but it could be a wildcard only that means that the type is ignored during the evaluation of the permission and only the path information is considered.
The actions string is a comma separated combination of a subset of the actions below:
CREATE: Create a resource in a path with a type (“*” Operator possible)
ADDSUB: add a sub resource to a resource (Checked in Resource, path is “”, counters updated)
READ: Read a resource
WRITE: Write a resource
DELETE: Delete a resource
ACTIVITY: Change the active status of a Resource
If an application has the permission for a certain action on a certain resource the action will be also be possible on all sub resources without references. For this reason wild cards are usually only relevant when paths shall also cover sub paths containing at least one reference. This is quite dangerous, though, as these references could point to any position in the resource database (although these references may not be creatable by the application itself).
Examples and Additional Information
At the development time an application developer doesn't have any information about the paths on the target system thats why it should use in the entries of permissions.perm file the 'type' key only. If an application uses a configuration resource with a fixed name it can still declare access only to this top-level resource by path. In the system permissions that are granted by the content of the ogema.policy or dynamically by the administrator on a running system the usage of both keys 'path' and 'type would be meaningful.
An example for ResourcePermission as a local permission could be:
This demand could be satisfied by granting the Permission
With this permissions the demander application gets access to the specified device. The application doesn't get access to any other device in system or devices that could be added to the system later even if they would match the application demand.
A ResourcePermission does not accept as type "ResourceList" (this just has no effect). Instead the element type of a ResourceList is relevant for the actions of an application allowed on a resource of type ResourceList.
Check of ResourcePermission
In general the following conditions are to be met in order to grant a ResourcePermission. Queried permission means the demanded access to be checked and the granted permission stand for a ResourcePermission entry that should imply the rueried permission.
- Check of the actions: The action flag of the queried permission was set in the granted permission.
- Check of the resource type: The granted permission refers to a resource type (e.g. org.ogema.model.devices.whitegoods.CoolingDevice). In this case the queried path is searched backwards and an element of the granted type is found.
- Check of the resource path: The granted permission refers to a resource path(e.g. myAppartment/rooms/rooms_0/fridge). A wildcard ('*') as last element of the granted path means that sub paths are included, while a path without wildcard means equality to the queried path is required. Generally paths could consist of only the wildcard (Type 1) or of a wildcarded specific path (Type 2) or a not wildcarded specific path (Type 3). The condition for this type of permission check is that the path of the queried path fits into the granted path. The table below shows the combination of these types for the granted and queried paths and result of this condition.
|Type of granted path||Type of queried path||Check result|
ChannelPermission is consumed by application or so called high level driver to get access to low level driver (bus driver) services. A high level driver is an application that communicate with a device trough the low level driver and provide the communicated data as resources in the OGEMA resource tree. Like the ResourcePermission the ChannelPermission gets two strings to be described properly.
The channel description filter string consists of comma separated key-value pair like “busid=/tty/USB*, devaddr=11 16 22 3*,chaddr=12 176 201 ”. All fields are optional and each field can consist of multiple values separated by whitespaces .The meaning of the valid keys are as follows:
- busid: Any description string that specifies the type of the communication protocol (see org.ogema.core.channelmanager.driverspi.DeviceLocator.getInterfaceName()).
- devaddr: A space separated list of any bus type specific address strings (see org.ogema.core.channelmanager.driverspi.DeviceLocator.getDeviceAddress()).
- chaddr: A space separated list of any bus type specific register or other bus parameter (see org.ogemacore.channelmanager.driverspi.ChannelLocator.getChannelAddress()).
Note that devaddr and chaddr are highly dependent on the communication protocol and its implementation in low level drivers.
Possible actions are:
- READ: Read the registers
- WRITE: Write the registers
- DELETE: Delete an existing channel.
The ChannelPermission as a local permission can be written in general way as in the following example
In this example devaddr=* and chaddr=* have no effect and they can be ommited. This permission demand could be satisfied on the system side by granting of the permissions below:
This permission is only used for administrative rights that are categorized further in sub-categories to allow a flexible distribution of rights to the users and application of the system. Like all other permissions AdminPermission provides two ways to express the permission. The permission demand and the administrative granting of the permission are expressed asAdminPermission doesn't accept any filter string but actions string only, that can be used as a comma separated list of a sub set of the actions below:
- user: Installing users, and removing them, definition of their access rights (for details see also user-management)
- app: Installing applications, restricting their rights, and removing them.
- system: Configuring the system settings (e.g. logger settings).
A meaningful expression of an AdminPermission demand could be like:
This demand could be acknowledged by granting of the permission
that grants the system actions only but not the user actions.
WebAccessPermission has a two-fold role. It is required by frontend applications that need to access servlets registered by other apps, and it is used to grant users the right to access pages registered by an app. Here the focus is on the app permissions, user permissions are explained below (User Management).
The filter string is a comma separated key-value pair like “name=org.ogema.apps.common-services, version=[2.1.0,3.0.0)”. The meanings of the possible keys are as follows.
- name: symbolic name of the bundle associated with the application to be accessed
- version: Version or version range of the app as they specified in section 3.2.5 and 3.2.6 of 
The implied permissions is a set of permissions specified by the OSGi ( see section '2.4.1 Implied Permissions' in ) and they are mentioned here for the sake of the compleetness. To achive the effective permission for an entity these permissions are added to the intersection of the appropriate local and system permissions. The implied permissions are listed below:
- java.io.FilePermission to read, write or delete files in the persistent storage area for the bundle that represent an application
- java.lang.PropertyPermission with READ action for OSGi properties that match org.osgi.framework.*
- org.osgi.framework.AdminPermission with the actions RESOURCE, METADATA, CLASS and CONTEXT where the actions applied to the same bundle where the executer code comes.
- org.osgi.framework.CapabilityPermission with the action REQUIRE for the osgi.ee capability
Note that the implied permissions are also to be demanded explicitly by the application.
As it already mentioned above the permissions required by an application should be listed as demand in the local permissions file permissions.perm and additionally they should be granted by the system so the application is able to make security sensitive accesses.
After the OGEMA specific considerations above the effective permissions could be written as
After the examinations on the example application in sections above we assume that it demand the following permissions. The list content could be the content of the permissions.perm file at the same time.
These demands could be than satisfied by the application specific policy:
Security Configuration GUI
In the sections above we have seen the way to manage the application policies via static preconfigured files. In most cases new application are installed dynamically at the runtime and shall be configured concerning the security settings. In OGEMA this is supported by the Security configuration GU. In the main view you have the choice to install a new bundle or to show the installed bundles in the system.
Install New Bundle
To install a new bundle you have to select a the source of the bundle file. As seen in the picture below, either an a registered marketplace could be choocen ore a local file could be uploaded. As default a marketplace supported by the local directory 'file:./appstore' is listed. Registration of new marketplaces is not yet supported by the GUI.
As soon as you select a registered marketplace a list with the available bundles appears.
As soon as you select a bundle file it will be installed and in a new window the permission configuration view is provided. The same thing is achieved after uploading a local file to the OGEMA framework as depicted below
The security configuration view starts with the presentation of the local permissions of the bundle to be installed. The permissions demanded by the bundle as content of the permissions.perm file are listed as in picture below. Note that the permission demands that are satisfied by the Default Permissions, are not included in the list.
By customizing of this list the application specific portion of the system permissions are defined. The permissions that should be granted are to be checked in the heading of the list entry. Additionally each demanded action could be checked to customize the permission to be granted. In special case of the ResourcePermission the currently existing resources that match the demand are presented, when the permission is selected. A sub set of the presented resources can be chosen and for each selected resource and the related actions can be customized on the appeared dialog. There is a special section with more details on how to deal with the ResourcePermission in OGEMA.
When all decisions about the demands are made the dialog is finished with the button 'Save Settings'. As response you get a new list with the system permissions granted to the currently installed bundle. On this view you can customize/remove each granted permission or define new additional permission.
Whereas the 'Remove' commands are sent immediately to the server side, the 'Customize' commands will be sent together, when 'Save Settings' is clicked. As response the list of the granted permissions will be updated. If you have to extend the system permissions of the bundle by a new one, just click 'Add Permission' and a new list entry is appeared at the bottom as depicted below:
On the appeared mask all you have to put all the relevant information like
- the fully qualified name of the permission
- the permission mode (grant/deny)
- the filter string
- and the actions as '*' for all actions or a comma separated list of supported actions.
After that with the 'Apply' command the data is accepted and if no further customization is needed, its committed to the server with 'Save Settings' command.
Note that grant/deny property of list entry is encoded in different colors of the heading in the view of the granted permissions. To accomplish the permission configuration the window is closed with the click on the button 'Quit'. The permission configuration was initiated by installation of a new bundle. With the last step the bundle is in installed state. To start the bundle you can use the 'Installed Bundles' menu on the main page that is described in the next section. The last installed bundle is listed as last element.
This menu provides information about the currently installed bundles and helps to start/stop them.
After the selection of a bundle with a double click on its portlet the following options are available:
- Start: start the bundle
- Stop: stop the bundle
- section above : view/change current permissions of the bundle as explained in the
- Permission Demand: view the permissions demanded by the bundle and optionally reconfigure the permissions starting with the initial step as described in the section above
- Webresources: show all web resources that are reachable over the paths registered by the bundle
- Info: show general information about the bundle (currently the list of the effective permissions only).
As already described above permissions are configured during the installation of an application that can be later customized too. The customizing of ResourcePermissions is done on the currently existing resource tree. Permissions are defined for the chosen resources. Since sub resources can be references to any other nodes in the tree its a special case when a ResourcePermission is defined for such a node.
In the view of the resource tree such nodes are marked with a special icon as it shown in the picture below. Further mark for such a node is the special node name which is built with the name of the sub resource followed by a narrow and the full path of the referenced resource like:
In the resource tree node can be localized by its path information that can contain sub nodes as reference to any other node. The path of such a node can differ from the location information which is the absolut path without any references therein.
When a reference node is chosen to define a permission on it, the location information of the node is used. Before a permission check is done, the path information are converted to location information.
Since OGEMA is a multi user system some ways are provided to manage the user configuration. In order to create a new user a user description including its permissions is to be provided. There are two ways to do that. User configuration can be changed dynamically via the web interface provided by the framework-administration app or statically via the system file ogema.roles. The secondary named way is described below.
To set up a user configuration statically at least one entry of the following format is added to the ogema.roles file for each user. The value of N after // in each line of the description below gives the repeat number of the element.
The ogema.roles file contains each policy definition in one line. Comments are allowed only in a line beginning with #. The following examples shows valid entries in this file:
Two different types of user can be specified. The natural user could use web resources registered by OGEMA applications whereas a 'machine' user could perform access to the rest interface. Thats why the provided permissions to the different user types are not the same type. For 'natural' users only org.ogema.accesscontrol.WebAccessPermission or java.security.AllPermission were meaningful (Note that granting of AllPermission to users should be an exceptional case). The 'machine' user is able to consume a org.ogema.accesscontrol.ResourcePermission only.
Multiple policies can be defined for one user. The policy name has to be unique in the system. If the user specified in the policy definition doesn't yet exist, it will be created at the startup time of the framework. For example the entry in the second line above leads to creation of the user "rest" but not to set of any permission for this user. However in the fourth line a new user with the name "extern" with the specified permission is created and with the fifth entry is restricted.
WebAccessPermission is an OGEMA defined permission that is generally consumed by natural users. This permission is used in user related policy definitions as in ogema.roles file only. It describes the permission for an user to access to web applications provided by an OGEMA application. This permission accepts a filter string but not any actions.
The filter string is comma separated key/value pairs where the possible keys are listed below.
- name: symbolic name of the bundle associated with the application to be accessed to
- version: Version or version range of the app as they specified in section 3.2.5 and 3.2.6 of 
Example permission definition of such a permission is shown below. It describes the access to the web resources of the application with the bundle symbolic name 'org.ogema.ref-impl.framework-gui' and a bundle version higher than 2.0.1 but lower or equal to 3.0.0.
The version is optional.
Access Control on REST Interface
In the table below some java properties are described, that help to control the behavior of the OGEMA security. If the default values of the properties should be overritten, they have to be set in the java command line.
|org.ogema.non-secure.http.enable||In OGEMA it's recommended that communication to the web interface is performed via secure socket connection. For any reason if the non-secure communication is needed, it' could be enabled by setting of the this property to 'true'. This property is set to 'false' by default that causes the rejection of requests via non-secure connection.|
|org.ogema.security||By setting of this property to 'off' the security could be disabled. The default value is 'on'. If security is disabled no security checks are done either if an application code accesses any resources nor if an user accesses the web interface of any applications, but authentication of the user via password is performed only.|
When do I need which permissions
|Use case||Permission||As local permission||As system permission|
|Access to own bundle context e.g. via ApplicationManager.getAppID().getBundle().getBundleContext()||(org.osgi.framework.AdminPermission "*" "context")||X||-|
|Calling java.io.File.getAbsolutePath()||(java.util.PropertyPermission "user.dir" "read") (TODO why "user.dir"?)||X||X|
Access a file in the bundle's storage area.
|(java.util.PropertyPermission "<<ALL FILES>>" "read, write, execute, delete")|
In order to demand access to the own bundle context just add (org.osgi.framework.AdminPermission "*" "context") to the local permissions.
OSGi Core release 5, OSGi Alliance, March 2012