/*
* @(#)PolicyReference.java
*
* Copyright 2003-2005 Sun Microsystems, Inc. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistribution of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistribution in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* Neither the name of Sun Microsystems, Inc. or the names of contributors may
* be used to endorse or promote products derived from this software without
* specific prior written permission.
*
* This software is provided "AS IS," without a warranty of any kind. ALL
* EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING
* ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
* OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN")
* AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE
* AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
* DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
* REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,
* INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY
* OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE,
* EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
*
* You acknowledge that this software is not designed or intended for use in
* the design, construction, operation or maintenance of any nuclear facility.
*/
package com.sun.xacml;
import java.io.OutputStream;
import java.io.PrintStream;
import java.net.URI;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.w3c.dom.NamedNodeMap;
import org.w3c.dom.Node;
import com.sun.xacml.combine.CombinerElement;
import com.sun.xacml.combine.CombiningAlgorithm;
import com.sun.xacml.ctx.Result;
import com.sun.xacml.ctx.Status;
import com.sun.xacml.finder.PolicyFinder;
import com.sun.xacml.finder.PolicyFinderResult;
/**
* This class is used as a placeholder for the PolicyIdReference and PolicySetIdReference fields in
* a PolicySetType. When a reference is used in a policy set, it is telling the PDP to use an
* external policy in the current policy. Each time the PDP needs to evaluate that policy reference,
* it asks the policy finder for the policy. Typically the policy finder will have cached the
* referenced policy, so this isn't too slow.
* <p>
* NOTE: all of the accessor methods, the match method, and the evaluate method require this class
* to ask its <code>PolicyFinder</code> for the referenced policy, which can be a slow operation.
* Care should be taken, therefore in calling these methods too often. Also note that it's not safe
* to cache the results of these calls, since the referenced policy may change.
*
* @since 1.0
* @author Seth Proctor
*/
public class PolicyReference extends AbstractPolicy {
/**
* Identifies this as a reference to a <code>Policy</code>
*/
public static final int POLICY_REFERENCE = 0;
/**
* Identifies this as a reference to a <code>PolicySet</code>
*/
public static final int POLICYSET_REFERENCE = 1;
// the reference
private URI reference;
// the reference type
private int policyType;
// and version constraints on this reference
private VersionConstraints constraints;
// the finder to use in finding the referenced policy
private PolicyFinder finder;
// the meta-data for the parent policy
private PolicyMetaData parentMetaData;
// the logger we'll use for all messages
private static final Logger logger = Logger.getLogger(PolicyReference.class.getName());
/**
* Creates a new <code>PolicyReference</code> instance. This has no constraints on version
* matching. Note that an XACML 1.x reference may not have any constraints.
*
* @param reference
* the reference to the policy
* @param policyType
* one of the two fields in this class
* @param finder
* the <code>PolicyFinder</code> used to handle the reference
* @param parentMetaData
* the meta-data associated with the containing (parent) policy
*
* @throws IllegalArgumentException
* if the input policyType isn't valid
*/
public PolicyReference(URI reference, int policyType, PolicyFinder finder,
PolicyMetaData parentMetaData) throws IllegalArgumentException {
this(reference, policyType, new VersionConstraints(null, null, null), finder,
parentMetaData);
}
/**
* Creates a new <code>PolicyReference</code> instance with version constraints. Note that an
* XACML 1.x reference may not have any constraints.
*
* @param reference
* the reference to the policy
* @param policyType
* one of the two fields in this class
* @param constraints
* any optional constraints on the version of the referenced policy (this is never
* null, but it may impose no constraints, and in fact will never impose constraints
* when used from a pre-2.0 XACML policy)
* @param finder
* the <code>PolicyFinder</code> used to handle the reference
* @param parentMetaData
* the meta-data associated with the containing (parent) policy
*
* @throws IllegalArgumentException
* if the input policyType isn't valid
*/
public PolicyReference(URI reference, int policyType, VersionConstraints constraints,
PolicyFinder finder, PolicyMetaData parentMetaData) throws IllegalArgumentException {
// check if input policyType is a valid value
if ((policyType != POLICY_REFERENCE) && (policyType != POLICYSET_REFERENCE))
throw new IllegalArgumentException("Input policyType is not a" + "valid value");
this.reference = reference;
this.policyType = policyType;
this.constraints = constraints;
this.finder = finder;
this.parentMetaData = parentMetaData;
}
/**
* Creates an instance of a <code>PolicyReference</code> object based on a DOM node.
*
* @deprecated As of 2.0 you should avoid using this method and should instead use the version
* that takes a <code>PolicyMetaData</code> instance. This method will only work for
* XACML 1.x policies.
*
* @param root
* the DOM root of a PolicyIdReference or a PolicySetIdReference XML type
* @param finder
* the <code>PolicyFinder</code> used to handle the reference
*
* @exception ParsingException
* if the node is invalid
*/
public static PolicyReference getInstance(Node root, PolicyFinder finder)
throws ParsingException {
return getInstance(root, finder, new PolicyMetaData());
}
/**
* Creates an instance of a <code>PolicyReference</code> object based on a DOM node.
*
* @param root
* the DOM root of a PolicyIdReference or a PolicySetIdReference XML type
* @param finder
* the <code>PolicyFinder</code> used to handle the reference
* @param metaData
* the meta-data associated with the containing policy
*
* @exception ParsingException
* if the node is invalid
*/
public static PolicyReference getInstance(Node root, PolicyFinder finder,
PolicyMetaData metaData) throws ParsingException {
URI reference = null;
int policyType;
// see what type of reference we are
String name = root.getNodeName();
if (name.equals("PolicyIdReference")) {
policyType = POLICY_REFERENCE;
} else if (name.equals("PolicySetIdReference")) {
policyType = POLICYSET_REFERENCE;
} else {
throw new ParsingException("Unknown reference type: " + name);
}
// next get the reference
try {
reference = new URI(root.getFirstChild().getNodeValue());
} catch (Exception e) {
throw new ParsingException("Invalid URI in Reference", e);
}
// now get any constraints
NamedNodeMap map = root.getAttributes();
String versionConstraint = null;
Node versionNode = map.getNamedItem("Version");
if (versionNode != null)
versionConstraint = versionNode.getNodeValue();
String earlyConstraint = null;
Node earlyNode = map.getNamedItem("EarliestVersion");
if (earlyNode != null)
earlyConstraint = earlyNode.getNodeValue();
String lateConstraint = null;
Node lateNode = map.getNamedItem("LatestVersion");
if (lateNode != null)
lateConstraint = lateNode.getNodeValue();
VersionConstraints constraints = new VersionConstraints(versionConstraint, earlyConstraint,
lateConstraint);
// finally, create the reference
return new PolicyReference(reference, policyType, constraints, finder, metaData);
}
/**
* Returns the refernce identitfier used to resolve the policy.
*
* @return the reference <code>URI</code>
*/
public URI getReference() {
return reference;
}
/**
* Returns the version constraints associated with this reference. This will never be null,
* though the constraints may be empty.
*
* @return the version constraints
*/
public VersionConstraints getConstraints() {
return constraints;
}
/**
* Returns whether this is a reference to a policy or to a policy set.
*
* @return the reference type, either <code>POLICY_REFERENCE</code> or
* <code>POLICYSET_REFERENCE</code>
*/
public int getReferenceType() {
return policyType;
}
/**
* Returns the id of this policy. If the policy is invalid or can't be retrieved, then a runtime
* exception is thrown.
*
* @return the policy id
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public URI getId() {
return resolvePolicy().getId();
}
/**
* Returns the version of this policy. If the policy is invalid or can't be retrieved, then a
* runtime exception is thrown.
*
* @return the policy version
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public String getVersion() {
return resolvePolicy().getVersion();
}
/**
* Returns the combining algorithm used by this policy. If the policy is invalid or can't be
* retrieved, then a runtime exception is thrown.
*
* @return the combining algorithm
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public CombiningAlgorithm getCombiningAlg() {
return resolvePolicy().getCombiningAlg();
}
/**
* Returns the given description of this policy or null if there is no description. If the
* policy is invalid or can't be retrieved, then a runtime exception is thrown.
*
* @return the description or null
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public String getDescription() {
return resolvePolicy().getDescription();
}
/**
* Returns the target for this policy. If the policy is invalid or can't be retrieved, then a
* runtime exception is thrown.
*
* @return the policy's target
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public Target getTarget() {
return resolvePolicy().getTarget();
}
/**
* Returns the default version for this policy. If the policy is invalid or can't be retrieved,
* then a runtime exception is thrown.
*
* @return the policy's default version
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public String getDefaultVersion() {
return resolvePolicy().getDefaultVersion();
}
/**
* Returns the child policy nodes under this node in the policy tree. If the policy is invalid
* or can't be retrieved, then a runtime exception is thrown.
*
* @return the <code>List</code> of child policy nodes
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public List<PolicyTreeElement> getChildren() {
return resolvePolicy().getChildren();
}
/**
* Returns the child policy nodes and their associated parameters. If the policy is invalid or
* can't be retrieved, then a runtime exception is thrown.
*
* @return a <code>List</code> of <code>CombinerElement</code>s
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public List<CombinerElement> getChildElements() {
return resolvePolicy().getChildElements();
}
/**
* Returns the Set of obligations for this policy, which may be empty if there are no
* obligations. If the policy is invalid or can't be retrieved, then a runtime exception is
* thrown.
*
* @return the policy's obligations
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public Set<Obligation> getObligations() {
return resolvePolicy().getObligations();
}
/**
* Returns the meta-data associated with this policy. If the policy is invalid or can't be
* retrieved, then a runtime exception is thrown. Note that this is the meta-data for the
* referenced policy, not the meta-data for the parent policy (which is what gets provided to
* the constructors of this class).
*
* @return the policy's meta-data
*
* @throws ProcessingException
* if the referenced policy can't be retrieved
*/
public PolicyMetaData getMetaData() {
return resolvePolicy().getMetaData();
}
/**
* Given the input context sees whether or not the request matches this policy. This must be
* called by combining algorithms before they evaluate a policy. This is also used in the
* initial policy finding operation to determine which top-level policies might apply to the
* request. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.
*
* @param context
* the representation of the request
*
* @return the result of trying to match the policy and the request
*/
public MatchResult match(EvaluationCtx context) {
try {
return getTarget().match(context);
} catch (ProcessingException pe) {
// this means that we couldn't resolve the policy
ArrayList<String> code = new ArrayList<String>();
code.add(Status.STATUS_PROCESSING_ERROR);
Status status = new Status(code, "couldn't resolve policy ref");
return new MatchResult(MatchResult.INDETERMINATE, status);
}
}
/**
* Private helper method that tried to resolve the policy
*/
private AbstractPolicy resolvePolicy() {
// see if this reference was setup with a finder
if (finder == null) {
if (logger.isLoggable(Level.WARNING))
logger.warning("PolicyReference with id " + reference.toString()
+ " was queried but was " + "not configured with a PolicyFinder");
throw new ProcessingException("couldn't find the policy with " + "a null finder");
}
PolicyFinderResult pfr = finder.findPolicy(reference, policyType, constraints,
parentMetaData);
if (pfr.notApplicable())
throw new ProcessingException("couldn't resolve the policy");
if (pfr.indeterminate())
throw new ProcessingException("error resolving the policy");
return pfr.getPolicy();
}
/**
* Tries to evaluate the policy by calling the combining algorithm on the given policies or
* rules. The <code>match</code> method must always be called first, and must always return
* MATCH, before this method is called.
*
* @param context
* the representation of the request
*
* @return the result of evaluation
*/
public Result evaluate(EvaluationCtx context) {
// if there is no finder, then we return NotApplicable
if (finder == null)
return new Result(Result.DECISION_NOT_APPLICABLE, context.getResourceId().encode());
PolicyFinderResult pfr = finder.findPolicy(reference, policyType, constraints,
parentMetaData);
// if we found nothing, then we return NotApplicable
if (pfr.notApplicable())
return new Result(Result.DECISION_NOT_APPLICABLE, context.getResourceId().encode());
// if there was an error, we return that status data
if (pfr.indeterminate())
return new Result(Result.DECISION_INDETERMINATE, pfr.getStatus(), context
.getResourceId().encode());
// we must have found a policy
return pfr.getPolicy().evaluate(context);
}
/**
* Encodes this <code>PolicyReference</code> into its XML representation and writes this
* encoding to the given <code>OutputStream</code> with no indentation.
*
* @param output
* a stream into which the XML-encoded data is written
*/
public void encode(OutputStream output) {
encode(output, new Indenter(0));
}
/**
* Encodes this <code>PolicyReference</code> into its XML representation and writes this
* encoding to the given <code>OutputStream</code> with indentation.
*
* @param output
* a stream into which the XML-encoded data is written
* @param indenter
* an object that creates indentation strings
*/
public void encode(OutputStream output, Indenter indenter) {
PrintStream out = new PrintStream(output);
String encoded = indenter.makeString();
if (policyType == POLICY_REFERENCE) {
out.println(encoded + "<PolicyIdReference" + encodeConstraints() + ">"
+ reference.toString() + "</PolicyIdReference>");
} else {
out.println(encoded + "<PolicySetIdReference" + encodeConstraints() + ">"
+ reference.toString() + "</PolicySetIdReference>");
}
}
/**
* Private helper method that encodes the variable constraints info. Note that if this is a
* pre-2.0 policy the constraints are always null, so nothing will be added here.
*/
private String encodeConstraints() {
String str = "";
VersionConstraints version = getConstraints();
String v = version.getVersionConstraint();
if (v != null)
str += " Version=\"" + v + "\"";
String e = version.getEarliestConstraint();
if (e != null)
str += " EarliestVersion=\"" + e + "\"";
String l = version.getLatestConstraint();
if (l != null)
str += " LatestVersion=\"" + l + "\"";
return str;
}
}