ProtectionDomain (Java Card SPI, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.javacard.spi.security
Class ProtectionDomain

    java.lang.Object
      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:

- `JCREPermission`
- `ContextPermission`
- `JCRuntimePermission`
- `URIPermission`
- `NamedPermission`
- `ServiceRegistryPermission`
- `EventRegistryPermission`
- `TaskRegistryPermission`
- `ConnectorPermission`
- `CardManagementPermission`
- `CryptoServicePermission`

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:

  - check if the permission is implied by the set of permissions resulting from the union of:
    - the set of included permissions defined for the platform protection domain this ProtectionDomain object was bound to at construction-time.
    - the ad-hoc set of permissions directly added to this ProtectionDomain object after construction-time.
  - check if the permission is not implied by the set of excluded permissions defined by the platform protection domain this ProtectionDomain object was bound to at construction-time.

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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