51 Permission Admin Service Specification

51.1 Introduction

Note: The Permission Admin has been superseded by the Conditional Permission Admin. See Conditional Permission Admin Service Specification.

In the Framework, a bundle can have a single set of permissions. These permissions are used to verify that a bundle is authorized to execute privileged code. For example, a FilePermission defines what files can be used and in what way.

The policy of providing the permissions to the bundle should be delegated to a Management Agent. For this reason, the Framework provides the Permission Admin service so that a Management Agent can administrate the permissions of a bundle and provide defaults for all bundles.

Related mechanisms of the Framework are discussed in Security Overview.

51.1.1 Essentials

  • Status information - The Permission Admin Service must provide status information about the current permissions of a bundle.

  • Administrative - The Permission Admin Service must allow a Management Agent to set the permissions before, during, or after a bundle is installed.

  • Defaults - The Permission Admin Service must provide control over default permissions. These are the permissions for a bundle with no specific permissions set.

51.1.2 Entities

  • PermissionAdmin - The service that provides access to the permission repository of the Framework.

  • PermissionInfo - An object that holds the information needed to construct a Permission object.

  • Bundle location - The string that specifies the bundle location. This is described in Bundle Identifiers.

Figure 51.1 org.osgi.service.permissionadmin package

org.osgi.service.permissionadmin package

51.1.3 Operation

The Framework maintains a repository of permissions. These permissions are stored under the bundle location string. Using the bundle location allows the permissions to be set before a bundle is downloaded. The Framework must consult this repository when it needs the permissions of a bundle. When no specific permissions are set, the bundle must use the default permissions. If no default is set, the bundle must use java.security.AllPermission. If the default permissions are changed, a bundle with no specific permissions must immediately start using the new default permissions.

The Permission Admin service is registered by the Framework's system bundle under the org.osgi.service.permissionadmin.PermissionAdmin interface. This is an optional singleton service, so at most one Permission Admin service is registered at any moment in time.

The Permission Admin service provides access to the permission repository. A Management Agent can get, set, update, and delete permissions from this repository. A Management Agent can also use a SynchronousBundleListener object to set the permissions during the installation or updating of a bundle.

51.2 Permission Admin service

The Permission Admin service needs to manipulate the default permissions and the permissions associated with a specific bundle. The default permissions and the bundle-specific permissions are stored persistently. It is possible to set a bundle's permissions before the bundle is installed in the Framework because the bundle's location is used to set the bundle's permissions.

The manipulation of a bundle's permissions, however, may also be done in real time when a bundle is downloaded or just before the bundle is downloaded. To support this flexibility, a SynchronousBundleListener object may be used by a Management Agent to detect the installation or update of a bundle, and set the required permissions before the installation completes.

Permissions are activated before the first time a permission check for a bundle is performed. This means that if a bundle has opened a file, this file must remain usable even if the permission to open that file is removed at a later time.

Permission information is not specified using java.security.Permission objects. The reason for this approach is the relationship between the required persistence of the information across the Framework restarts and the concept of class loaders in the Framework. Actual Permission classes must be subclasses of Permission and may be exported from any bundle. The Framework can access these permissions as long as they are exported, but the Management Agent would have to import all possible packages that contain permissions. This requirement would severely limit permission types. Therefore, the Permission Admin service uses the PermissionInfo class to specify permission information. Objects of this class are used by the Framework to create Permission objects.

PermissionInfo objects restrict the possible Permission objects that can be used. A Permission subclass can only be described by a PermissionInfo object when it has the following characteristics:

  • It must be a subclass of java.security.Permission.

  • It must use the two-argument public constructor type(name,actions).

  • The class must be available to the Framework code from the system class path or from any exported package so it can be loaded by the Framework.

  • The class must be public.

If any of these conditions is not met, the PermissionInfo object must be ignored and an error message should be logged.

The permissions are always set as an array of PermissionInfo objects to make the assignment of all permissions atomic.

The PermissionAdmin interface provides the following methods:

51.2.1 File Permission for Relative Path Names

A java.io.FilePermission assigned to a bundle via the setPermissions method must receive special treatment if the path argument for the FilePermission is a relative path name. A relative path name is one that is not absolute. See the java.io.File.isAbsolute method for more information on absolute path names.

When a bundle is assigned a FilePermission for a relative path name, the path name is taken to be relative to the bundle's persistent storage area. This allows additional permissions, such as execute, to be assigned to files in the bundle's persistent storage area. For example:

    java.io.FilePermission "-" "execute"

can be used to allow a bundle to execute any file in the bundle's persistent storage area.

This only applies to FilePermission objects assigned to a bundle via the setPermission method. This does not apply to default permissions. A FilePermission for a relative path name assigned via the setDefaultPermission method must be ignored.

51.3 Security

The Permission Admin service is a system service that can be abused. A bundle that can access and use the Permission Admin service has full control over the OSGi framework. However, many bundles can have ServicePermission[PermissionAdmin,GET] because all methods that change the state of the Framework require AdminPermission.

No bundle must have ServicePermission[PermissionAdmin,REGISTER] for this service because only the Framework should provide this service.

51.4 org.osgi.service.permissionadmin

Version 1.2

Permission Admin Package Version 1.2.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.permissionadmin; version="[1.2,2.0)"

51.4.1 Summary

  • PermissionAdmin - The Permission Admin service allows management agents to manage the permissions of bundles.

  • PermissionInfo - Permission representation used by the Permission Admin service.

51.4.2 public interface PermissionAdmin

The Permission Admin service allows management agents to manage the permissions of bundles. There is at most one Permission Admin service present in the OSGi environment.

Access to the Permission Admin service is protected by corresponding ServicePermission. In addition AdminPermission is required to actually set permissions.

Bundle permissions are managed using a permission table. A bundle's location serves as the key into this permission table. The value of a table entry is the set of permissions (of type PermissionInfo) granted to the bundle named by the given location. A bundle may have an entry in the permission table prior to being installed in the Framework.

The permissions specified in setDefaultPermissions are used as the default permissions which are granted to all bundles that do not have an entry in the permission table.

Any changes to a bundle's permissions in the permission table will take effect no later than when bundle's java.security.ProtectionDomain is next involved in a permission check, and will be made persistent.

Only permission classes on the system classpath or from an exported package are considered during a permission check. Additionally, only permission classes that are subclasses of java.security.Permission and define a 2-argument constructor that takes a name string and an actions string can be used.

Permissions implicitly granted by the Framework (for example, a bundle's permission to access its persistent storage area) cannot be changed, and are not reflected in the permissions returned by getPermissions and getDefaultPermissions.

Thread-safe

Consumers of this API must not implement this type

51.4.2.1 public PermissionInfo[] getDefaultPermissions()

Gets the default permissions.

These are the permissions granted to any bundle that does not have permissions assigned to its location.

The default permissions, or null if no default permissions are set.

51.4.2.2 public String[] getLocations()

Returns the bundle locations that have permissions assigned to them, that is, bundle locations for which an entry exists in the permission table.

The locations of bundles that have been assigned any permissions, or null if the permission table is empty.

51.4.2.3 public PermissionInfo[] getPermissions(String location)

The location of the bundle whose permissions are to be returned.

Gets the permissions assigned to the bundle with the specified location.

The permissions assigned to the bundle with the specified location, or null if that bundle has not been assigned any permissions.

51.4.2.4 public void setDefaultPermissions(PermissionInfo[] permissions)

The default permissions, or null if the default permissions are to be removed from the permission table.

Sets the default permissions.

These are the permissions granted to any bundle that does not have permissions assigned to its location.

SecurityException– If the caller does not have AllPermission.

51.4.2.5 public void setPermissions(String location, PermissionInfo[] permissions)

The location of the bundle that will be assigned the permissions.

The permissions to be assigned, or null if the specified location is to be removed from the permission table.

Assigns the specified permissions to the bundle with the specified location.

SecurityException– If the caller does not have AllPermission.

51.4.3 public class PermissionInfo

Permission representation used by the Permission Admin service.

This class encapsulates three pieces of information: a Permission type (class name), which must be a subclass of java.security.Permission, and the name and actions arguments passed to its constructor.

In order for a permission represented by a PermissionInfo to be instantiated and considered during a permission check, its Permission class must be available from the system classpath or an exported package. This means that the instantiation of a permission represented by a PermissionInfo may be delayed until the package containing its Permission class has been exported by a bundle.

Immutable

51.4.3.1 public PermissionInfo(String type, String name, String actions)

The fully qualified class name of the permission represented by this PermissionInfo. The class must be a subclass of java.security.Permission and must define a 2-argument constructor that takes a name string and an actions string.

The permission name that will be passed as the first argument to the constructor of the Permission class identified by type.

The permission actions that will be passed as the second argument to the constructor of the Permission class identified by type.

Constructs a PermissionInfo from the specified type, name, and actions.

NullPointerException– If type is null.

IllegalArgumentException– If action is not null and name is null.

51.4.3.2 public PermissionInfo(String encodedPermission)

The encoded PermissionInfo.

Constructs a PermissionInfo object from the specified encoded PermissionInfo string. White space in the encoded PermissionInfo string is ignored.

IllegalArgumentException– If the specified encodedPermission is not properly formatted.

getEncoded()

51.4.3.3 public boolean equals(Object obj)

The object to test for equality with this PermissionInfo object.

Determines the equality of two PermissionInfo objects. This method checks that specified object has the same type, name and actions as this PermissionInfo object.

true if obj is a PermissionInfo, and has the same type, name and actions as this PermissionInfo object; false otherwise.

51.4.3.4 public final String getActions()

Returns the actions of the permission represented by this PermissionInfo.

The actions of the permission represented by this PermissionInfo, or null if the permission does not have any actions associated with it.

51.4.3.5 public final String getEncoded()

Returns the string encoding of this PermissionInfo in a form suitable for restoring this PermissionInfo.

The encoded format is:

 (type)

or

 (type "name")

or

 (type "name" "actions")

where name and actions are strings that must be encoded for proper parsing. Specifically, the ",\, carriage return, and line feed characters must be escaped using \", \\, \r, and \n, respectively.

The encoded string contains no leading or trailing whitespace characters. A single space character is used between type and "name" and between "name" and "actions".

The string encoding of this PermissionInfo.

51.4.3.6 public final String getName()

Returns the name of the permission represented by this PermissionInfo.

The name of the permission represented by this PermissionInfo, or null if the permission does not have a name.

51.4.3.7 public final String getType()

Returns the fully qualified class name of the permission represented by this PermissionInfo.

The fully qualified class name of the permission represented by this PermissionInfo.

51.4.3.8 public int hashCode()

Returns the hash code value for this object.

A hash code value for this object.

51.4.3.9 public String toString()

Returns the string representation of this PermissionInfo. The string is created by calling the getEncoded method on this PermissionInfo.

The string representation of this PermissionInfo.