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.
-
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.
-
PermissionAdmin - The service that provides access to the permission repository of the Framework.
-
PermissionInfo - An object that holds the information needed to construct a
Permissionobject. -
Bundle location - The string that specifies the bundle location. This is described in Bundle Identifiers.
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.
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:
-
getLocations() - Returns a list of locations that have permissions assigned to them. This method allows a Management Agent to examine the current set of permissions.
-
getPermissions(String) - Returns a list of
PermissionInfoobjects that are set for that location, or returnsnullif no permissions are set. -
setPermissions(String,PermissionInfo[]) - Associates permissions with a specific location, or returns
nullwhen the permissions should be removed. -
getDefaultPermissions() - This method returns the list of default permissions.
-
setDefaultPermissions(PermissionInfo[]) - This method sets the default permissions.
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.
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.
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)"
-
PermissionAdmin- The Permission Admin service allows management agents to manage the permissions of bundles. -
PermissionInfo- Permission representation used by the Permission Admin service.
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
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
Returns the hash code value for this object.
A hash code value for this object.