This document is a proposal for supporting use of OASIS eXtensible Access Control Markup Language (XACML) Version 1.0 [2] policies with the Java[TM] 2 Platform, Standard Edition (J2SE[TM] Platform). This proposal is not a commitment from or endorsement by Sun Microsystems or any Java Community Process(SM) group, and does not necessarily represent any official Sun or JCP(SM) position. Comments to the author, Anne Anderson, are welcomed.

This document assumes the reader is familiar with the syntax and semantics of XACML. An introduction is available in A Brief Introduction to XACML [10]. For still more details, see the XACML Specification and schemas [2,3,4].

This document also assumes the reader is familiar with the J2SE Policy API and the use of Permissions in J2SE applications. For more details, see [7].

Contents
Introduction
Objectives
Overview
Notation
Proposal
New J2SE-Specific DataTypes and Functions
New J2SE-Specific DataTypes
New J2SE-Specific Functions
AttributeIds
Existing AttributeIds
New J2SE-Specific AttributeIds
XACML Policy Provider Implementation
Internal Structure
PDP Interface Module
J2SE-Specific Attribute Finder Module
Policy API Support
implies
getPermissions
refresh
PolicyFile to XACML Translator
Issues and Rationale
getPermissions
Overlapping Permissions
KeyStores
Multiple Actions
Property Expansion
General Expansion
References
Contributors
Appendices

Example of a Translated Simple PolicyFile

Example of a Translated Full PolicyFile

Mappings for Standard J2SE Permission Subclasses
Notices

--------------------------------------------------------------------------------

Introduction
This document contains a proposed profile for supporting use of OASIS eXtensible Access Control Markup Language (XACML) Version 1.0 [2] policies for applications written for the Java[TM] 2 Platform, Standard Edition (J2SE[TM]).

Objectives
This proposal has the following objectives.

Allow J2SE applications to obtain the full benefits of XACML policies.
OASIS Standard policy language, written in XML.
Ability to reference external attributes, such as time of day or attribute certificates stored in an LDAP database.
Ability to support role based access control.
Ability to reference distributed policies.
Allow a shared resource accessed by J2SE and non-J2SE applications to be controlled using a single standard XACML policy.
Fully support the J2SE Policy API.
Allow J2SE application policy writers to write, manage, analyze, and debug policies using 3rd-party policy tools that support XACML.
Support translation of existing PolicyFile policies into XACML.
Overview
The proposal recommends creation of a J2SE Policy Provider that accepts XACML policies as its policy input. The Policy Provider accepts standard XACML policies, but also supports new XACML extensions to deal with J2SE-specific objects and concepts. XACML is designed to be extensible, and the proposed extensions are fully in the spirit of those intended.

The profile defines mappings between certain Java Class objects and standard XACML Attributes. Such mappings allow Java applications to use standard XACML policies that protect resources accessed by multiple applications, not all of which are written using the Java programming language. These mappings are as follows:

requesting ProtectionDomain Principal[] array: XACML subject-id Attribute with SubjectCategory access-subject
requesting ProtectionDomain CodeBase URL: XACML subject-id Attribute with SubjectCategory codebase
requested Permission: XACML resource-id and action-id Attributes.
Details of the mappings are described below in the Existing AttributeIds Section and in Appendix 3: Mappings for Standard J2SE Permission Subclasses.

In order to support the full functionality of the Java Policy API, the proposal also defines a set of new XACML Attributes and associated new XACML DataTypes and Functions. These new Attributes allow XACML policies to refer to Java objects that are part of the J2SE Policy API. The objects are not translated into an XACML Request, but are referenced as native Java objects. These Attributes, DataTypes, and Functions are described in the New J2SE-Specific DataTypes, New J2SE-Specific Functions, and New J2SE-Specific AttributeIds Sections below.

The proposal then outlines how the XACML Policy Provider can be implemented using Sun's XACML Implementation, and how this implementation supports the methods in the J2SE Policy API .

The proposal concludes with a description of a tool for translating existing PolicyFile policies into XACML policies, intended to facilitate migration. Appendices provide simple and full examples of PolicyFiles translated into XACML policies according to this proposal.

A discussion of the design choices made follows the proposal itself in the Issues and Rationale section.

Notation
Certain URIs starting with the prefix http://sunlabs.east.sun.com/projects/isrg/xacml/names# are defined and used in this profile. This namespace has been reserved, and can be used for prototyping. These URIs are not defined by XACML, and are being used as a placeholder for a final J2SE-specific prefix. If this proposal is implemented, the final URIs will probably be different.

In the examples and explanatory text in this profile, various URIs and URNs are abbreviated to make them more readable. J2SE-specific URIs use the prefix j2se# in place of the full provisional prefix http://sunlabs.east.sun.com/projects/isrg/xacml/names#. XACML standard URIs and URNs omit the prefix altogether.

Proposal
This section describes the details of the proposed J2SE-specific extensions to XACML, the Policy Provider that supports XACML, the Policy API method support, and the tool that translates PolicyFile policies into XACML policies.

New J2SE-Specific DataTypes and Functions
This proposal recommends extending XACML with the following new DataTypes and FunctionIds. These DataTypes and FunctionIds are used to handle J2SE-specific functionality that is not supported using existing standard XACML DataTypes and functions.

The XACML syntax is designed to be extensible via the definition of new DataTypes and FunctionIds. Such extensions require extending the implementation of any XACML Policy Decision Point (PDP) to implement the new DataTypes and FunctionIds. Sun's XACML Implementation [1] has been designed for easy extensibility in this way. XACML PDPs that have not been extended, however, will not be able to support policies that use the new DataTypes and FunctionIds. This is not viewed as an issue, since policies using these extensions would only be used for Java applications, and Java applications can be configured to use a PDP that has been appropriately extended.

New J2SE-Specific DataTypes
http://sunlabs.east.sun.com/projects/isrg/xacml/names#class:

Defines a namespace for XACML DataTypes where the string following j2se#class: is interpreted as a fully-qualified J2SE Class name.

An <AttributeValue> having this DataType contains a sequence of arguments to be supplied to a Constructor for the J2SE Class. Each of these arguments is an <xacml:AttributeValue> itself and must have an appropriate DataType. The implementation recognizes the DataType http://www.w3.org/2001/XMLSchema#string as equivalent to j2se#class:java.lang.String. If an <AttributeValue> having this DataType does not contain a sequence of arguments compatible with any Constructor for the J2SE Class, then the evaluation of the <AttributeValue> results in an error.

An <AttributeDesignator> having this DataType must have an AttributeId that refers to an instance of the designated Java Class. These AttributeIds are described in the AttributeIds section below. If an <AttributeDesignator> having a DataType in this namespace does not have an AttributeId that refers to an instance of the designated Java Class, then the evaluation of the <AttributeDesignator> results in a processing-error.

Example: an <AttributeValue> that corresponds to the Permission Class instance in the following PolicyFile "permission" statement.

permission java.io.FilePermission "/home/alice/*", "read, write"

is specified in XACML as follows:

<AttributeValue
  DataType="j2se#class:java.io.FilePermission>
    <AttributeValue
      DataType="string">/home/alice/*</AttributeValue>
    <AttributeValue
      DataType="string">read, write</AttributeValue>
</AttributeValue>

New J2SE-Specific Functions
http://sunlabs.east.sun.com/projects/isrg/xacml/names#method:

Defines a namespace for XACML Functions where the string following j2se#method: is interpreted as the name of a J2SE Class method.

Each such function expects its first argument to have a DataType in the j2se#class: namespace. The function is interpreted as a method of this first argument's Class. The function is implemented by invoking the named method in the Class instance represented by the first argument. The remaining arguments and their DataTypes must correspond to arguments expected by the named Class method and are passed as arguments to the method invocation. If the remaining arguments and their DataTypes do not correspond to arguments expected by the named Class method, the evaluation of the function results in a processing-error.

Example: the following PolicyFile "permission"

permission java.net.SocketPermission "129.255.255.255"
                                     "listen, connect"

is specified in XACML as follows:

<ResourceMatch MatchId="j2se#method:implies">
  <AttributeValue
     DataType="j2se#class:java.net.SocketPermission">
    <AttributeValue
       DataType="string">129.255.255.255</AttributeValue>
    <AttributeValue
       DataType="string">listen, connect<AttributeValue>
  </AttributeValue>
  <ResourceAttributeDesignator
     AttributeId="resource:resource-id"
     DataType="j2se#class:java.net.SocketPermission"/>
</ResourceMatch>

An important use of this namespace is for referencing the implies method of a Permission subclass, as in the example just provided. Note that use of the implies method in this way allows use of multiple actions in a single XACML Request without requiring any special handling by the XACML PDP.

http://sunlabs.east.sun.com/projects/isrg/xacml/names#function:getCertificateFromKeyStore

This function is used to retrieve an instance of a java.security.Certificate from a J2SE keystore.

This function expects three arguments.

The "alias" for the desired certificate within the keystore. The DataType of this argument must be http://www.w3.org/2001/XMLSchema#string.

The URL at which the keystore containing the certificate is to be found. The DataType of this argument must be http://www.w3.org/2001/XMLSchema#anyURI.

The type of the keystore file (such as "JKS". The DataType of this argument must be http://www.w3.org/2001/XMLSchema#string.

If the arguments to this function are not of the correct type, the result is a syntax-error.

If the specified alias can be found in a keystore of the specified type at the specified URL, the result of this function is an instance of a java.security.Certificate. Otherwise, the result is "Indeterminate".

Example: an example of use of this function follows.

<Apply FunctionId="j2se#function:getCertificateFromKeyStore">
    <AttributeValue DataType="string">FooSoft</AttributeValue>
    <!-- keystore "file:/opt/keystores/.keystore" "JKS"; -->
    <AttributeValue
      DataType="anyURI">file:/opt/keystores/.keystore</AttributeValue>
    <AttributeValue
      DataType="string">JKS</AttributeValue>
</Apply>

http://sunlabs.east.sun.com/projects/isrg/xacml/names#function:certificate-is-in

This function is an extension to the group of type-is-in functions defined in the XACML specification, and conforms to the semantics of such functions: "This function SHALL take an argument of data-type j2se#class:java.security.Certificate as the first argument and a bag of j2se#class:java.security.Certificate as the second argument. The expression SHALL evaluate to "True" if the first argument matches by the j2se#method:equals function to any value in the bag."

This function is used in J2SE XACML policies to match an instance of the j2se#attribute:signerCertificate AttributeId against a particular certificate. This AttributeId can be used to specify a certificate associated with the signature on the invoking Class in the requesting ProtectionDomain or a certificate associated with a signature on the requested Permission. When used with the signature on the invoking Class, the j2se#attribute:signerCertificate AttributeId occurs in a <SubjectAttributeDesignator>. When used with the signature on the requested Permission, the j2se#attribute:signerCertificate AttributeId occurs in a <ResourceAttributeDesignator>.

In J2SE XACML policies, the j2se#function:certificate-is-in function is used as follows. The first argument to this function is an <Apply> element invoking the j2se#function:getCertificateFromKeyStore function. The second argument to this function is a <SubjectAttributeDesignator> or <ResourceAttributeDesignator> as described above with an AttributeId of j2se#attribute:signerCertificate and a DataType that is a subclass of j2se#class:java.security.Certificate. The function returns "True" if the certificate specified by the keystore alias in the keystore file in getCertificateFromKeyStore is among the certificates used to sign either the requested Permission class (when used with a <ResourceAttributeDesignator>) or the CodeBase of the requesting ProtectionDomain (when used with a <SubjectAttributeDesignator>). Otherwise, the function returns "False".

Example: an example of use of this function follows.

<Apply FunctionId="j2se#function:certificate-is-in">
    <Apply FunctionId="j2se#function:getCertificateFromKeyStore">
        <AttributeValue DataType="string">FooSoft</AttributeValue>
        <!-- keystore "file:/opt/keystores/.keystore" "JKS"; -->
        <AttributeValue
          DataType="anyURI">file:/opt/keystores/.keystore</AttributeValue>
        <AttributeValue
          DataType="string">JKS</AttributeValue>
    </Apply>
    <ResourceAttributeDescriptor
       AttributeId="j2se#attribute:signerCertificate"
       DataType="j2se#class:java.security.Certificate"/>
</Apply>

http://sunlabs.east.sun.com/projects/isrg/xacml/names#function:file-path-match

This function provides the ability to match file paths in order to determine if one file or subdirectory matches or is in a sub-directory of another. It emulates the java.io.Permission implies functionality, but may be used with arguments that are not specific to the J2SE platform. Note that the matching is strictly by name syntax: there is no lookup to see if a given file or subdirectory is actually in another directory on the platform itself.

The function takes two arguments of DataType http://www.w3.org/2001/XMLSchema#string and returns a result of type http://www.w3.org/2001/XMLSchema#boolean. The result of the function is "True" if the file or path specified in the first argument matches the second argument; otherwise, the result is "False". The first argument is the "template" for the match: the desired path or directory name, which may use wildcard characters. The second argument is the literal file or path to be compared to the template. If the first argument is a pathname that ends in "<file-separator>*", it indicates all file and directory names syntactically contained in that directory, including the directory itself. If the first argument is a pathname that ends with "<file-separator>-", it indicates (recursively) all file and subdirectory names syntactically contained in that directory. If the first argument is a pathname consisting of the special token "[[ALL FILES]]", it matches any file. If the characters "*" or "-" are to be treated as filenames rather than as wildcard characters, the characters must be escaped using "\*" or "\-".

This function recognizes and expands the ${some.property} syntax in its literal string arguments.

http://sunlabs.east.sun.com/projects/isrg/xacml/names#function:permission-one-and-only

This function is an extension to the group of type-one-and-only functions defined in the XACML specification, and conforms to the semantics of such functions: "This function SHALL take an argument of a bag of data-type j2se#class:java.security.Permission (or a subclass thereof) and SHALL return a value of DataType j2se#class:java.security.Permission (or a subclass thereof). It SHALL return the only value in the bag. If the bag does not have one and only one value, then the expression SHALL evaluate to "indeterminate"."

In J2SE XACML policies, this function is used to convert the bag of Permissionobjects returned by a <ResourceAttributeDesignator> with an AttributeId of urn:oasis:names:tc:xacml:1.0:resource:resource-id into a single Permission object. This function never fails, since the "resource-id" AttributeId is mapped to the requested Permission in the Policy API, and the Policy API has exactly one such Permission.

Example: an example of the use of this function follows.

<Apply FunctionId="j2se#function:permission-one-and-only">
  <ResourceAttributeDesignator
     AttributeId="resource:resource-id"
     DataType="j2se#class:java.security.Permission"
</Apply>

AttributeIds
This proposal recommends mapping some J2SE objects to existing XACML AttributeIds, and defining some new AttributeIds that are J2SE-specific. These are described as follows.

Existing AttributeIds
This proposal recommends mapping the following existing XACML standard AttributeIds to objects in the Policy API. The mappings are consistent with the semantics of these AttributeIds as defined by XACML.

urn:oasis:names:tc:xacml:1.0:subject:subject-id

XACML specifies that this AttributeId is to be used for the identity of a subject involved in making the access request. J2SE Policy supports two such types of subjects, one of which corresponds to the standard XACML SubjectCategory "access-subject" and the other of which corresponds to the standard XACML SubjectCategory "codebase".

In the J2SE XACML Policy Provider, this AttributeId is supported only in a <SubjectAttributeDesignator> and only for the following SubjectCategory values.

SubjectCategory urn:oasis:names:tc:xacml:1.0:subject-category:access-subject

When this AttributeId is used with a SubjectCategory value of urn:oasis:names:tc:xacml:1.0:subject-category:access-subject, it is mapped to the array of Principal in the ProtectionDomain of the Policy API. The value of the attribute is a bag containing one member for each Principal returned from invoking domain.getPrincipals() that is compatible with the DataType specified for the AttributeId.

If the DataType of the attribute is urn:oasis:names:tc:xacml:1.0:data-type:x500Name, then the bag contains, for each Principal of type javax.security.auth.x500.X500Principal, the value returned from invoking Principal.getName().

If the DataType of the attribute is j2se#class:java.security.Principal or a subclass thereof, then the bag contains one Java object for each Principal corresponding to the named class.

If the DataType is http://www.w3.org/2001/XMLSchema#string or j2se#class:java.lang.String, then the bag contains, for each Principal in the array, the value returned from invoking Principal.getName().

Other DataTypes will be supported only if custom code is added to the J2SE-extended XACML PDP implementation.

SubjectCategory urn:oasis:names:tc:xacml:1.0:subject-category:codebase

When this AttributeId is used with a SubjectCategory value of urn:oasis:names:tc:xacml:1.0:subject-category:codebase then it is mapped to the URL of the CodeSource in the ProtectionDomain in the Policy API. The value of the attribute is a bag consisting of one member. The value of the bag member depends on the DataType.

If the DataType is http://www.w3.org/2001/XMLSchema#anyURI or http://www.w3.org/2001/XMLSchema#string, then the bag member is the value returned by invoking URL.toString().

If the DataType is j2se#class:java.net.URL or a subclass thereof, then the bag member is the Java object that is the URL.

Other DataTypes will be supported only if custom code is added to the J2SE-extended XACML PDP implementation.

urn:oasis:names:tc:xacml:1.0:resource:resource-id

XACML specifies that this AttributeId is to be used for the identity of the resource being accessed.

In the J2SE XACML Policy Provider, this AttributeId is mapped to the requested Permission object in the Policy API. This AttributeId is supported only in a <ResourceAttributeDesignator>.

The value of the attribute is a bag containing one member. The value of the member depends on the DataType specified for the attribute.

If the DataType is j2se#class:java.security.Permission or a subclass thereof, then the value of the member is the requested Permission object passed in the Policy API.

If the DataType of this attribute is http://www.w3.org/2001/XMLSchema#string or j2se#class:java.lang.String, then the value of the member is as follows.

If the value of Permission.getActions() is the empty string or null, then the value of the bag member is the fully qualified name of the Permission subclass. For example, if the requested Permission subclass is javax.sound.sampled.AudioPermission, the value of the bag member is javax.sound.sampled.AudioPermission.

Otherwise, the value of the bag member is the value of Permission.getName().

Other DataTypes will be supported only if custom code is added to the J2SE-extended XACML PDP implementation.

urn:oasis:names:tc:xacml:1.0:action:action-id

This AttributeId is mapped to the requested Permission object in the Policy API. The AttributeId is supported only in an <ActionAttributeDesignator>.

This AttributeId is handled in a special way for certain standard J2SE Permission classes that support multiple actions in a single Permission. If such a Permission instance is passed as the requested permission via the Policy API, then the PDP Interface Module parses the value returned from Permission.getActions(). If the value contains more than one action, then the PDP Interface Module does the following. For each action value, the PDP Interface Module makes one call to the PDP.evaluate() API. For each such call, the PDP Interface Module supplies only the one action value to the J2SE-Specific Attribute Finder Module in response to a request for the urn:oasis:names:tc:xacml:1.0:action:action-id AttributeId. If any such call fails to evaluate to "Permit", then the PDP Interface Module returns "False" as the Policy API return value. If all such calls evaluate to "Permit", then the PDP Interface Module returns "True" as the Policy API return value. The Appendix Mappings for Standard J2SE Permission Subclasses identifies the standard J2SE Permission subclasses for which this special handling is performed.

The value of the attribute is a bag containing one member. The value of the member depends on the DataType specified for the attribute.

If the DataType of this attribute is http://www.w3.org/2001/XMLSchema#string or j2se#class:java.lang.String, then the value of the member is as follows.

If the value of Permission.getActions() is the empty string or null, then the value of the bag member is the value of Permission.getName().

Otherwise, the value of the bag member is the value of Permission.getActions().

Other DataTypes will be supported only if custom code is added to the J2SE-extended XACML PDP implementation.

New J2SE-Specific AttributeIds
This proposal recommends defining the following new XACML AttributeIds.

http://sunlabs.east.sun.com/projects/isrg/xacml/names#attribute:signerCertificate

This AttributeId is supported only in a <SubjectAttributeDesignator> or <ResourceAttributeDesignator> as follows.

SubjectAttributeDesignator

When used in a <SubjectAttributeDesignator>, this AttributeId is mapped to the array of java.security.Certificate that is part of the CodeSource in the ProtectionDomain of the Policy API. This AttributeId is supported only with a SubjectCategory of urn:oasis:names:tc:xacml:1.0:subject-category:codebase. The value of the attribute is a bag containing one member for each Certificate returned from invoking domain.getCodeSource().getCertificates() that is compatible with the DataType specified for the attribute.

If the DataType of the attribute is urn:oasis:names:tc:xacml:1.0:data-type:x500Name, http://www.w3.org/2001/XMLSchema#string, or j2se#class:java.lang.String, then the bag contains one member for each Certificate that is of class java.security.cert.x509Certificate. The value of the member is the value returned by invoking x509Certificate.getSubjectDN().getName().

If the DataType of the attribute is in the namespace j2se#class:, then the named class must be a subclass of java.security.cert.Certificate. The bag contains one member for each Certificate that is of this subclass. The value of the member is the Java object that is the Certificate.

Other DataTypes will be supported only if custom code is added to the J2SE-extended XACML PDP implementation.

ResourceAttributeDesignator

When used as a <ResourceAttributeDesignator>, this AttributeId is mapped to the array of Certificate that is part of the ProtectionDomain associated with the Class of the requested Permission. The value of the attribute is a bag containing one member for each Certificate returned from invoking Permission.getClass().getProtectionDomain.getCodeSource.getCertificates() that can support the DataType specified for the attribute (or Permission.getClass().getSigners(), using only objects from the resulting Object[] that are of type java.security.cert.x509Certificate. This is equivalent.)

If the DataType of the attribute is urn:oasis:names:tc:xacml:1.0:data-type:x500Name, http://www.w3.org/2001/XMLSchema#string, or j2se#class:java.lang.String then the bag contains one member for each Certificate that is of class java.security.cert.x509Certificate. The value of the member is the value returned by invoking x509Certificate.getSubjectDN().getName().

If the DataType of the attribute is j2se#class:java.security.Certificate or a subclass thereof, then the bag contains one member for each Certificate that is of this class or subclass. The value of the member is the Java object that is the Certificate.

Other DataTypes will be supported only if custom code is added to the J2SE-extended XACML PDP implementation.