Package com.sun.ts.lib.util.sec.security.provider

# Class PolicyFile

java.lang.Object
java.security.Policy
com.sun.ts.lib.util.sec.security.provider.PolicyFile

public class PolicyFile extends Policy
This class represents a default implementation for `java.security.Policy`. Note: For backward compatibility with JAAS 1.0 it loads both java.auth.policy and java.policy. However it is recommended that java.auth.policy be not used and the java.policy contain all grant entries including that contain principal-based entries. 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, policy.url.1, policy.url.2, ..., policy.url.X" and 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. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed. Each property value specifies a `URL` pointing to a policy file to be loaded. Read in and load each policy. auth.policy.url is supported only for backward compatibility.
2. The `java.lang.System` property java.security.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. 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. java.security.auth.policy is supported only for backward compatibility. If the java.security.policy or 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). principal entries are optional and need not be present. Italicized items represent variable values. A grant entry must begin with the word `grant`. The `signedBy`,`codeBase` and `principal` 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 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 XXX `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 of any permission that contains the string, "${{self}}", as part of its target name. When such a permission is evaluated (such as during a security check), ${{self}} is replaced with one or more Principal class/name pairs. The exact replacement performed depends upon the contents of the grant clause to which the permission belongs. If the grant clause does not contain any principal information, the permission will be ignored (permissions containing ${{self}} in their target names are only valid in the context of a principal-based grant clause). For example, BarPermission will always be ignored in the following grant clause:

        grant codebase "www.foo.com", signedby "duke" {
          permission BarPermission "... ${{self}} ...";
        };

If the grant clause contains principal information, ${{self}} will be replaced with that same principal information. For example, ${{self}} in BarPermission will be replaced by javax.security.auth.x500.X500Principal "cn=Duke" in the following grant clause:

        grant principal javax.security.auth.x500.X500Principal "cn=Duke" {
          permission BarPermission "... ${{self}} ...";
        };

If there is a comma-separated list of principals in the grant clause, then ${{self}} will be replaced by the same comma-separated list or principals. In the case where both the principal class and name are wildcarded in the grant clause, ${{self}} is replaced with all the principals associated with the `Subject` in the current `AccessControlContext`. For PrivateCredentialPermissions, you can also use "self" instead of "${{self}}". However the use of "self" is deprecated in favour of "${{self}}".

See Also:
  - `CodeSource`
  - `Permissions`
  - `ProtectionDomain`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class java.security.Policy

  `Policy.Parameters`

- ## Field Summary

  ### Fields inherited from class java.security.Policy

  `UNSUPPORTED_EMPTY_COLLECTION`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PolicyFile()`
  Initializes the Policy object and reads the default policy configuration file(s) into the Policy object.
  `PolicyFile(URL url)`
  Initializes the Policy object and reads the default policy from the specified URL only.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `canonPath(String path)`
  `PermissionCollection`
  `getPermissions(CodeSource codesource)`
  Examines this Policy and creates a PermissionCollection object with the set of permissions for the specified CodeSource.
  `PermissionCollection`
  `getPermissions(ProtectionDomain domain)`
  Examines this `Policy` and returns the permissions granted to the specified `ProtectionDomain`.
  `protected Certificate[]`
  `getSignerCertificates(CodeSource cs)`
  `boolean`
  `implies(ProtectionDomain pd, Permission p)`
  Evaluates the the global policy for the permissions granted to the ProtectionDomain and tests whether the permission is granted.
  `void`
  `refresh()`
  Refreshes the policy object by re-reading all the policy files.

  ### Methods inherited from class java.security.Policy

  `getInstance, getInstance, getInstance, getParameters, getPolicy, getProvider, getType, setPolicy`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### PolicyFile

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

  - ### PolicyFile

    public PolicyFile(URL url)
    Initializes the Policy object and reads the default policy from the specified URL only.

- ## Method Details

  - ### refresh

    public void refresh()
    Refreshes the policy object by re-reading all the policy files.
    Overrides:
      `refresh` in class `Policy`

  - ### implies

    public boolean implies(ProtectionDomain pd, Permission p)
    Evaluates the the global policy for the permissions granted to the ProtectionDomain and tests whether the permission is granted.
    Overrides:
      `implies` in class `Policy`
    Parameters:
      `domain` - the ProtectionDomain to test
      `permission` - the Permission object to be tested for implication.
    Returns:
      true if "permission" is a proper subset of a permission granted to this ProtectionDomain.
    See Also:
      - `ProtectionDomain`

  - ### getPermissions

    public PermissionCollection getPermissions(ProtectionDomain domain)
    Examines this `Policy` and returns the permissions granted to the specified `ProtectionDomain`. This includes the permissions currently associated with the domain as well as the policy permissions granted to the domain's CodeSource, ClassLoader, and Principals. 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`.
    Overrides:
      `getPermissions` in class `Policy`
    Parameters:
      `domain` - the Permissions granted to this `ProtectionDomain` are returned.
    Returns:
      the Permissions granted to the provided `ProtectionDomain`.

  - ### getPermissions

    public PermissionCollection getPermissions(CodeSource codesource)
    Examines this Policy and creates a PermissionCollection object with the set of permissions for the specified CodeSource.
    Overrides:
      `getPermissions` in class `Policy`
    Parameters:
      `CodeSource` - the codesource associated with the caller. This encapsulates the original location of the code (where the code came from) and the public key(s) of its signer.
    Returns:
      the set of permissions according to the policy.

  - ### getSignerCertificates

    protected Certificate[] getSignerCertificates(CodeSource cs)

  - ### canonPath

    public static String canonPath(String path) throws IOException
    Throws:
      `IOException`