• Security Technical Notes
Skip to end of metadata
Go to start of metadata

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.

The OGEMA 2.0 framework acknowledges user accounts and applications as entities to which assignment of rights might be relevant. As OGEMA 2.0 applications often operate independenly of user interaction (many applications do monitoring and control functionalities), the user and application permissions are defined independently. While a natural user has access to the user interface (applications via web server) according to the provided permissions a machine user has access to the REST mechanism where only the resources are visible that are specified in the user policy. A machine user is either the dynamic content of a web page (javascript code) given by an application on the OGEMA 2.0 Gateway or an application on a remote machine. This separation is needed to prevent an implicit rights forwarding from the user to the application. The exceptional case that a web resource need to access to the rest interface caused by its dynamic content (javascript,...) is handled below in the section Access Control on REST Interface.

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.

FileLocationDescription
ogema.policy./configThe 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./configWith 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 "//".
permissions.perm

OSGI-INF/

(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.

 

Local Permissions

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.

System 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.

Default Permissions

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  default permissions  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

PackagePermission

Applications need this permission in order to be able to import classes from other bundles or to export own classes for other bundles. More details to PackagePermission are in section "3.16.3 Package Permission" of reference [1] . The package permissions required by the application depends on the values of the manifest headers Export-Package, Import-Package and Dynamic-Import. For example the manifest of the modbus-rtu driver contains following headers:
The required PackagePermission after this manifest entries are listed below:

 

The packages that match org.ogema.core.* and org.osgi.framework are already granted trough the Default Permissions, 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.

ServicePermission

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

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

Resource Scope

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.

ResourceList

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.

  1. Check of the actions: The action flag of the queried permission was set in the granted permission.
  2. 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.
  3. 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 pathType of queried pathCheck result
11True
12True
13True
21False
22queryPath.startsWith(grantedPath)
23 queryPath.startsWith(grantedPath)
31False
32False
33queryPath.equals(grantedPath)

ChannelPermission

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:

AdminPermission

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 as

AdminPermission 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

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 [1]

Example:

Implied Permissions

The implied permissions is a set of permissions specified by the OSGi ( see section '2.4.1 Implied Permissions' in [1]) 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.

Effective Permissions

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.

Installed Bundles

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
  • Edit Permissions: view/change current permissions of the bundle as explained in the section above
  • 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).

OGEMA ResourcePermission

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:

temperatureSensor->HM_WDS10_TH_O_THSensor_270A5A/sensors/temperature

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.

User Management

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

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 [1]

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

The standard way to get access to the rest interface is planned as a HTTP Request, where the known machine user name and its password is encoded in the URL. For more details to the usage of the rest interface see Using the OGEMA REST Interface.
In OGEMA security the way to access to the rest interface out of a web site that is downloaded by a natural user is regulated too. The authentication of such an entity (website with javascript) is more complex. To do that the requested web site gets a one time password (OTP) injected as javascript snippet by the framework. The javascript code that should perform the rest access has to use the OTP information to build a valid REST URL as were it a  machine user. An example javascript snippet with the OTP information looks like:

 

 

The variables otpusr and otpwd are globally visible in the whole page. Their values should be used instead of the required machine user name and password as they expected in the REST URL. The REST interface only allows queries with a valid OTP or an authorized machine user. It derives the involved application from the OTP and checks the authorization of this application before it serves the request.  

Hence, an HTTP request from a website registered via the OGEMA WebAccessManager to a servlet registered via the same service must contain the user and pw parameters in its address, such as

 

where otusr and otpwd are to be replaced by the values of the globally visible javascript variables of the respective name.

Configuration Properties

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.

PropertyDescription
org.ogema.non-secure.http.enableIn 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.securityBy 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 casePermissionAs local permissionAs 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"?)XX

Access a file in the bundle's storage area.
Note: the example permission demanding access to "<<ALL FILES>>" is rejected as too general by OGEMA. Instead, only access to the bundle's storage area is granted. This should be fine for most applications, if you need access to other files specify the path explicitly. If possible, use the bundle's storage area, however.

(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.

References

[1] OSGi Core release 5, OSGi Alliance, March 2012

sema-fieldtest-config

  • No labels