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

## com.ibm.security.auth
Class PolicyFile

    java.lang.Object
      javax.security.auth.Policy
          com.ibm.security.auth.PolicyFile

Deprecated. As of JDK 1.4, replaced by sun.security.provider.PolicyFile. This class is entirely deprecated.

    public class PolicyFile

extends Policy

This class represents a default implementation for `javax.security.auth.Policy`.

This object stores the policy for entire Java runtime, and is the amalgamation of multiple static policy configurations that resides in files. The algorithm for locating the policy file(s) and reading their information into this `Policy` object is:

1. Loop through the `java.security.Security` properties, auth.policy.url.1, auth.policy.url.2, ..., auth.policy.url.X". These properties are set in the Java security properties file, which is located in the file named <JAVA_HOME>/lib/security/java.security, where <JAVA_HOME> refers to the directory where the JDK was installed. Each property value specifies a `URL` pointing to a policy file to be loaded. Read in and load each policy.
2. The `java.lang.System` property java.security.auth.policy may also be set to a `URL` pointing to another policy file (which is the case when a user uses the -D switch at runtime). If this property is defined, and its use is allowed by the security property file (the Security property, policy.allowSystemProperty is set to true), also load that policy.
3. If the java.security.auth.policy property is defined using "==" (rather than "="), then ignore all other specified policies and only load this policy.

Each policy file consists of one or more grant entries, each of which consists of a number of permission entries.

       grant signedBy "alias", codeBase "URL",
             principal principalClass "principalName",
             principal principalClass "principalName",
             ... {

         permission Type "name "action",
             signedBy "alias";
         permission Type "name "action",
             signedBy "alias";
         ....
       };

All non-bold items above must appear as is (although case doesn't matter and some are optional, as noted below). Italicized items represent variable values.

A grant entry must begin with the word `grant`. The `signedBy` and `codeBase` name/value pairs are optional. If they are not present, then any signer (including unsigned code) will match, and any codeBase will match. Note that the `principal` name/value pair is not optional. This `Policy` implementation only permits Principal-based grant entries. Note that the principalClass may be set to the wildcard value, *, which allows it to match any `Principal` class. In addition, the principalName may also be set to the wildcard value, *, allowing it to match any `Principal` name. When setting the principalName to the *, do not surround the * with quotes.

A permission entry must begin with the word `permission`. The word `Type` in the template above is a specific permission type, such as `java.io.FilePermission` or `java.lang.RuntimePermission`.

The "action" is required for many permission types, such as `java.io.FilePermission` (where it specifies what type of file access that is permitted). It is not required for categories such as `java.lang.RuntimePermission` where it is not necessary - you either have the permission specified by the `"name"` value following the type name or you don't.

The `signedBy` name/value pair for a permission entry is optional. If present, it indicates a signed permission. That is, the permission class itself must be signed by the given alias in order for it to be granted. For example, suppose you have the following grant entry:

       grant principal foo.com.Principal "Duke" {
         permission Foo "foobar", signedBy "FooSoft";
       }

Then this permission of type Foo is granted if the `Foo.class` permission has been signed by the "FooSoft" alias, or if `Foo.class` is a system class (i.e., is found on the CLASSPATH).

Items that appear in an entry must appear in the specified order (`permission`, Type, "name", and "action"). An entry is terminated with a semicolon.

Case is unimportant for the identifiers (`permission`, `signedBy`, `codeBase`, etc.) but is significant for the Type or for any string that is passed in as a value.

An example of two entries in a policy configuration file is

       // if the code is comes from "foo.com" and is running as "Duke",
       // grant it read/write to all files in /tmp.

       grant codeBase "foo.com", principal foo.com.Principal "Duke" {
                    permission java.io.FilePermission "/tmp/*", "read,write";
       };

       // grant any code running as "Duke" permission to read
       // the "java.vendor" Property.

       grant principal foo.com.Principal "Duke" {
               permission java.util.PropertyPermission "java.vendor";

This `Policy` implementation supports special handling for PrivateCredentialPermissions. If a grant entry is configured with a `PrivateCredentialPermission`, and the "Principal Class/Principal Name" for that `PrivateCredentialPermission` is "self", then the entry grants the specified `Subject` permission to access its own private Credential. For example, the following grants the `Subject` "Duke" access to its own a.b.Credential.

       grant principal foo.com.Principal "Duke" {
            permission javax.security.auth.PrivateCredentialPermission
                    "a.b.Credential self",
                    "read";
        };

The following grants the `Subject` "Duke" access to all of its own private Credentials:

       grant principal foo.com.Principal "Duke" {
            permission javax.security.auth.PrivateCredentialPermission
                    "* self",
                    "read";
        };

The following grants all Subjects authenticated as an `AIXPrincipal` (regardless of their respective names) permission to access their own private Credentials:

       grant principal com.ibm.security.auth.AIXPrincipal * {
            permission javax.security.auth.PrivateCredentialPermission
                    "* self",
                    "read";
        };

The following grants all Subjects permission to access their own private Credentials:

       grant principal * * {
            permission javax.security.auth.PrivateCredentialPermission
                    "* self",
                    "read";
        };

Version:
  1.22, 01/25/00
See Also:
  `CodeSource`, `Permissions`, `ProtectionDomain`

Constructor Summary
`PolicyFile()` Deprecated. Initializes the Policy object and reads the default policy configuration file(s) into the Policy object.

Method Summary
`java.security.PermissionCollection` | `getPermissions(Subject subject, java.security.CodeSource codesource)` Deprecated. Examines this `Policy` and returns the Permissions granted to the specified `Subject` and `CodeSource`.
`void` | `refresh()` Deprecated. Refreshes the policy object by re-reading all the policy files.

Methods inherited from class javax.security.auth.Policy
`getPolicy, setPolicy`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### PolicyFile

    public PolicyFile()

  Deprecated.
  Initializes the Policy object and reads the default policy configuration file(s) into the Policy object.

Method Detail

### refresh

    public void refresh()

  Deprecated.
  Refreshes the policy object by re-reading all the policy files.

  Specified by:
    `refresh` in class `Policy`
  Throws:
    `java.lang.SecurityException` - if the caller doesn't have permission to refresh the `Policy`.

### getPermissions

    public java.security.PermissionCollection getPermissions(Subject subject,
                                                             java.security.CodeSource codesource)

  Deprecated.
  Examines this `Policy` and returns the Permissions granted to the specified `Subject` and `CodeSource`.

  Permissions for a particular grant entry are returned if the `CodeSource` constructed using the codebase and signedby values specified in the entry `implies` the `CodeSource` provided to this method, and if the `Subject` provided to this method contains all of the Principals specified in the entry.

  The `Subject` provided to this method contains all of the Principals specified in the entry if, for each `Principal`, "P1", specified in the grant entry one of the following two conditions is met:

  1. the `Subject` has a `Principal`, "P2", where `P2.getClass().getName()` equals the P1's class name, and where `P2.getName()` equals the P1's name.
  2. P1 implements `com.ibm.security.auth.PrincipalComparator`, and `P1.implies` the provided `Subject`.

  Note that this `Policy` implementation has special handling for PrivateCredentialPermissions. When this method encounters a `PrivateCredentialPermission` which specifies "self" as the `Principal` class and name, it does not add that `Permission` to the returned `PermissionCollection`. Instead, it builds a new `PrivateCredentialPermission` for each `Principal` associated with the provided `Subject`. Each new `PrivateCredentialPermission` contains the same Credential class as specified in the originally granted permission, as well as the Class and name for the respective `Principal`.

  Specified by:
    `getPermissions` in class `Policy`
  Parameters:
    `subject` - the Permissions granted to this `Subject` and the additionally provided `CodeSource` are returned.

    `codesource` - the Permissions granted to this `CodeSource` and the additionally provided `Subject` are returned.
  Returns:
    the Permissions granted to the provided `Subject` `CodeSource`.

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