com.sun.javacard.spi.security
Class ProtectionDomain

java.lang.Object
  extended by com.sun.javacard.spi.security.ProtectionDomain

@TransactionType(value=NOT_SUPPORTED)
public final class ProtectionDomain
extends Object

This ProtectionDomain class encapsulates the characteristics of a domain, which is bound to a group context whose applications are granted a set of permissions.

A ProtectionDomain can be constructed such that it is bound to a set of permissions defined by the Platform Policy - a Platform Protection Domain. The platform policy defines permission sets (platform protection domains) enforcing the consistency of the application models and the integrity of platform.

In order to support specific policy configuration on a per-application basis, an ad-hoc set of permissions can be added to a ProtectionDomain by the card management applications after it has been constructed; such ad-hoc permissions are granted by the domain in addition to (still in consistency with) the permissions granted by the platform policy in force. This ad-hoc set of permissions can be updated throughout the lifetime of the ProtectionDomain object by the card management applications.

When marked read-only, no permission can be added to or removed from the set of ad-hoc permissions. This is to prevent sensitive applications from having their effective set of permissions (the combination of both the permissions granted by the platform protection domain and the ad-hoc set of permissions) altered. Note that Platform Protection Domains are read-only.

A ProtectionDomain object is bound to a single group context. Therefore ad- hoc permission updates on a ProtectionDomain object do not affect others. ProtectionDomain objects are Java Card runtime environment-owned objects; permissions referenced by a ProtectionDomain objects may be exact Java Card RE-owned copies of the permission objects that were added to the protection domain.

By default, only direct instances of the following Permission subclasses can be added to a ProtectionDomain object:

The platform policy defines platform protection domains for each of the application models. A group context whose applications implement a particular application model must be bound thru the ProtectionDomain object bound to its group context to the platform protection domain which correspond to that application model. Additionally, the platform policy defines a platform protection domain for card management applications so that they have the required privileges to operate. The platform protection domains are not only defined with a set of included permissions but also with a set of excluded permissions such that no ad-hoc permissions can be granted which may compromise the consistency of the application models and the integrity of platform.

Note: Permission objects must be stored in a manner that allows them to be inserted in any order, but that also enables the ProtectionDomain implies method to be implemented in an efficient (and consistent) manner. Since this may differ with each Permission subclass, the ProtectionDomain class must implement efficient strategies for each of the Permission subclasses defined in this API. ProtectionDomain objects must reject any other permission object.

ProtectionDomain objects are permanent Java Card runtime environment Entry Point Objects.

Since:
Java Card 3.0
See Also:
Permission, AccessController, AccessControlException

Field Summary
static String DEFAULT_CARD_MANAGEMENT_DOMAIN_ALIAS
          Default platform protection domain alias for Card Management applications ("CardManagement").
static String DEFAULT_CLASSIC_DOMAIN_ALIAS
          Default platform protection domain alias for Classic Applet applications ("Classic").
static String DEFAULT_EXTENDED_DOMAIN_ALIAS
          Default platform protection domain alias for Extended Applet applications ("Extended").
static String DEFAULT_WEB_DOMAIN_ALIAS
          Default platform protection domain alias for Web applications ("Web").
 
Method Summary
 void add(Permission permission)
          Adds a permission to this protection domain (to the ad-hoc set of permissions).
static ProtectionDomain createProtectionDomain(String name, String platformDomainAlias)
          Creates a new Java Card runtime environment-owned ProtectionDomain object bound to the platform protection domain defined in the Platform Policy under the given alias.
 Enumeration<Permission> elements()
          Returns an enumeration of all the permissions directly granted by this protection domain (the ad-hoc permission set).
 ApplicationGroup getApplicationGroup()
          Returns the application group this protection domain is bound to.
 String getName()
          Returns the name of this protection domain.
 boolean implies(Permission permission)
          Checks if this ProtectionDomain object implies the permissions expressed in the Permission object.
static void initializePlatformPolicy()
          Initializes the Platform Policy.
 boolean isBoundToDomain(String name)
          Indicates whether this ProtectionDomain object has the provided name or is bound to a platform protection domain which has the provided name.
 boolean isReadOnly()
          Returns true if this ProtectionDomain object is marked as read-only.
 boolean remove(Permission permission)
          Removes a permission from this protection domain (from the ad-hoc set of permissions).
 void setApplicationGroup(ApplicationGroup applicationGroup)
          Sets the application group this protection domain is bound to.
 void setReadOnly()
          Marks this ProtectionDomain object as read-only.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_CARD_MANAGEMENT_DOMAIN_ALIAS

public static final String DEFAULT_CARD_MANAGEMENT_DOMAIN_ALIAS
Default platform protection domain alias for Card Management applications ("CardManagement").

See Also:
Constant Field Values

DEFAULT_CLASSIC_DOMAIN_ALIAS

public static final String DEFAULT_CLASSIC_DOMAIN_ALIAS
Default platform protection domain alias for Classic Applet applications ("Classic").

See Also:
Constant Field Values

DEFAULT_EXTENDED_DOMAIN_ALIAS

public static final String DEFAULT_EXTENDED_DOMAIN_ALIAS
Default platform protection domain alias for Extended Applet applications ("Extended").

See Also:
Constant Field Values

DEFAULT_WEB_DOMAIN_ALIAS

public static final String DEFAULT_WEB_DOMAIN_ALIAS
Default platform protection domain alias for Web applications ("Web").

See Also:
Constant Field Values
Method Detail

initializePlatformPolicy

public static void initializePlatformPolicy()
Initializes the Platform Policy.

This method must be called before any ProtectionDomain object is created by a call to createProtectionDomain(String, String).

Throws:
IllegalStateException - if the Platform Policy has already been initialized.

createProtectionDomain

public static final ProtectionDomain createProtectionDomain(String name,
                                                            String platformDomainAlias)
Creates a new Java Card runtime environment-owned ProtectionDomain object bound to the platform protection domain defined in the Platform Policy under the given alias. The permissions granted to this domain include both the ad-hoc permissions subsequently added to this domain, and any permissions granted to this domain by the platform protection domain. The ad-hoc permissions granted to this domain can be changed by calling add() and remove() provided this ProtectionDomain object has not been marked read-only by a call to setReadOnly(). When marked read-only, the permissions granted to this protection domain are a snapshot of both the permissions granted by the platform protection domain and the ad-hoc set of permissions at the time of marked read-only.

The created ProtectionDomain object is assigned the given name. This name is used for ContextPermission target names.

Parameters:
name - the name assigned to this protection domain
platformDomainAlias - the alias of the platform protection domain
Throws:
IllegalArgumentException -
  • if platformDomainAlias does not map to a Platform Policy domain,
  • or, if name is the name of a Platform Policy domain,
  • or, if name is the empty string "".
NullPointerException - if name or platformDomainAlias is null.

add

public void add(Permission permission)
Adds a permission to this protection domain (to the ad-hoc set of permissions).

Parameters:
permission - the permission to be added.
Throws:
IllegalArgumentException - if permission is not supported by this ProtectionDomain object.
SecurityException - if this ProtectionDomain object is read-only or if adding permission would violate the platform policy.

elements

public Enumeration<Permission> elements()
Returns an enumeration of all the permissions directly granted by this protection domain (the ad-hoc permission set).

Returns:
the enumeration of all the ad-hoc permissions.

getName

public String getName()
Returns the name of this protection domain.

Returns:
the name directly assigned to this protection domain.

implies

public boolean implies(Permission permission)
Checks if this ProtectionDomain object implies the permissions expressed in the Permission object.

This check is performed as follows:

Parameters:
permission - the Permission object to check.
Returns:
true if the permission checked is implicit to this ProtectionDomain.

isBoundToDomain

public boolean isBoundToDomain(String name)
Indicates whether this ProtectionDomain object has the provided name or is bound to a platform protection domain which has the provided name.

Parameters:
name - the name
Returns:
true if this ProtectionDomain object has the provided name or is bound to a platform protection domain which has the provided name; false otherwise.

isReadOnly

public boolean isReadOnly()
Returns true if this ProtectionDomain object is marked as read-only.

By default, the object is not read-only. It can be marked read-only by a call to setReadOnly.

Returns:
true if this ProtectionDomain object is marked as read-only, false otherwise.

remove

public boolean remove(Permission permission)
Removes a permission from this protection domain (from the ad-hoc set of permissions). Removes the first occurrence of the specified permission object. If this protection domain does not contain the permission object as can be determined by the Permission.equals(Object), it is unchanged.

Parameters:
permission - the permission to be removed.
Returns:
true if this ProtectionDomain object contained the specified permission.
Throws:
SecurityException - if this ProtectionDomain object is read-only.

setReadOnly

public void setReadOnly()
Marks this ProtectionDomain object as read-only. After a ProtectionDomain object is marked as read-only, no permission can be added to or removed from the set of ad-hoc permissions.


getApplicationGroup

public ApplicationGroup getApplicationGroup()
Returns the application group this protection domain is bound to.

Returns:
the application group this protection domain is bound to.

setApplicationGroup

public void setApplicationGroup(ApplicationGroup applicationGroup)
Sets the application group this protection domain is bound to.

Parameters:
applicationGroup - the application group.
Throws:
IllegalStateException - if this protection domain object have already been assigned to another application group (hence context).


Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.