Conditional Permission Admin service

The ConditionalPermissionAdmin service is defined by the OSGi Service Platform Core Specification release 4. The service extends the concepts of dynamic permission definition of the OSGi Permission Admin service by introducing conditional permissions. It is registered under the org.osgi.service.condpermadmin.ConditionalPermissionAdmin basic interface and under the com.prosyst.mbs.framework.condpermadmin.MbsConditionalPermissionAdmin additionally-defined one, and is available only if the framework is started with security – refer to the "Starting the Framework with Security" section in the Starting the framework document.

Registering bundle

This service is registered by the System bundle.

Basic principles

A conditional permission is associated with a set of conditions and a set of permissions. The permissions of the conditional permission become granted when all associated conditions become satisfied.

Bundle developers can define local permissions which set the maximum of permissions that a bundle should have. This allows for better restriction of permissions as well as for auditing the functions that the bundle has. The local permissions of a bundle should be placed in a file, called permissions.perm and placed within the OSGI-INF directory of the bundle JAR file. Each permission definition should be in a new line following the encoded form supported by its class definition. If the local permission resource is not included in a bundle, the framework will set java.security.AllPermission as local permissions for the bundle.

You can turn off the processing of local permissions by using the mbs.disableLocalPermissions system property.

The ConditionalPermissionAdmin Service Specification introduces two standard conditions - bundle location condition and bundle signer condition. The bundle location condition – org.osgi.service.condpermadmin.BundleLocationCondition, is an analog to the permission definitions used in the OSGi Permission Admin service. The bundle signer condition is related to the principal distinguished name of the certificate the bundle is signed with.

When adding a conditional permission to the ConditionalPermissionAdmin service, you should supply info objects for required conditions and permissions. The encoded string of a condition info should have the format of:

[condition_class_name "condition_arg" "condition_arg"]

and the one of a permission information:

(permission_class_name "permission_name" "permission_actions")

The concept of default permissions from the PermissionAdmin service is still preserved though slightly modified - as default permissions the ConditionalPermissionAdmin treats those conditional permissions which do not have conditions.

In addition, you can explicitly force evaluation of the conditional permissions of a specific bundle by using the methods of the com.prosyst.mbs.framework.condpermadmin.MbsConditionalPermissionAdmin service interface.

Initial configuration of Conditional Permissions Table

At startup, the FW must be able to read an initial table of conditional permissions from a text format file supplied as an URL. The following system properties are used:

• com.prosyst.mbs.initial.cpa.table=<URL> – holds the URL to the policy file
• com.prosyst.mbs.initial.cpa.table.applyAlways=<true|false> – controls the FW behavior when dealing with CPA tables created at previous FW starts. Default is "false"
• com.prosyst.mbs.initial.cpa.table.onError=<exit|ignore> – controls the FW behavior if the policy URL points to an invalid file. Default is "ignore" The following scheme is followed on framework startup.

The following UML diagram describes the startup process:

Conditional Permissions are specified by the policy file. These must be only one permission per line. The proper permission encoding format is:

access {conditions permissions} name

where:

• access: the access decision
• conditions: must have zero or more elements
• permissions: must have one or more elements
• name: the name of the ConditionalPermissionInfo. It is Optional but if presented it must be quoted, beginning and ending with ".

For more information refer to chapters 9.15.6.7, 9.15.8.5 and 10.4.3.5 of the OSGi R4 specification or chapters 50.14.7.7, 50.14.9.5 and 51.4.4.5 of the OSGi R5.

Using a Group of Permissions for a Single Permission Entry

To optimize determining the conditional permissions of bundles in the OSGi platform, the implementation of the ConditionalPermissionAdmin service provides the opportunity to define groups of functionally-related permissions, which will be handled as a whole instead of saving and retrieving permissions one-by-one. The paradigm of functional permissions works as follows:

1. Create a functional permission group containing the required set of permissions by using the com.prosyst.mbs.framework.policy.PolicyManager methods implemented in the FrameworkAccess service.
2. To associate the permissions of the group with conditions in a conditional permission, define a conditional permission in the OSGi Conditional Permission Admin. Specify the relevant conditions and include in the permission set the functional group in the form of a permission definition with a class type equal to the alias of the functional permission and with no name and actions.

If needed, you might later change the permissions directly in the group - to apply the change to the ConditionalPermissionAdmin service, reset the conditional permissions by calling the service's setConditionalPermissionInfo method again by including the permission group in the set of permission definitions.