org.opensaml.ws.security.provider
Class ClientCertAuthRule

java.lang.Object
  extended by org.opensaml.ws.security.provider.BaseTrustEngineRule<org.opensaml.xml.security.x509.X509Credential>
      extended by org.opensaml.ws.security.provider.ClientCertAuthRule
All Implemented Interfaces:
SecurityPolicyRule

public class ClientCertAuthRule
extends BaseTrustEngineRule<org.opensaml.xml.security.x509.X509Credential>

Policy rule that checks if the client cert used to authenticate the request is valid and trusted.

This rule is only evaluated if the message context contains a peer X509Credential as returned from the inbound message context's inbound message transport Transport.getPeerCredential().

If the inbound message issuer has been previously set in the message context by another rule, then that issuer is used to evaluate the request's X509Credential. If this trust evaluation is successful, the message context's inbound transport authentication state will be set to true and processing is terminated. If unsuccessful, a SecurityPolicyException is thrown.

If no context issuer was previously set, then rule evaluation will be attempted as described in evaluateCertificateNameDerivedIssuers(X509Credential, MessageContext), based on the currently configured certificate name evaluation options. If this method returns a non-null issuer entity ID, it will be set as the inbound message issuer in the message context, the message context's inbound transport issuer authentication state will be set to true and rule processing is terminated. If the method returns null, the message context issuer and transport authentication state will remain unmodified and rule processing continues.

Finally rule evaluation will proceed as described in evaluateDerivedIssuers(X509Credential, MessageContext). This is primarily an extension point by which subclasses may implement specific custom logic. If this method returns a non-null issuer entity ID, it will be set as the inbound message issuer in the message context, the message context's inbound transport authentication state will be set to true and rule processing is terminated. If the method returns null, the message context issuer and transport authentication state will remain unmodified.


Constructor Summary
ClientCertAuthRule(org.opensaml.xml.security.trust.TrustEngine<org.opensaml.xml.security.x509.X509Credential> engine, CertificateNameOptions nameOptions)
          Constructor.
 
Method Summary
protected  org.opensaml.xml.security.CriteriaSet buildCriteriaSet(java.lang.String entityID, MessageContext messageContext)
          Subclasses are required to implement this method to build a criteria set for the trust engine according to trust engine and application-specific needs.
protected  void doEvaluate(org.opensaml.xml.security.x509.X509Credential requestCredential, MessageContext messageContext)
          Evaluate the request credential.
 void evaluate(MessageContext messageContext)
          Evaluates the message context against the rule.
protected  java.lang.String evaluateCertificateNameDerivedIssuers(org.opensaml.xml.security.x509.X509Credential requestCredential, MessageContext messageContext)
          Evaluate candidate issuer entity ID's which may be derived from the request credential's entity certificate according to the options supplied via CertificateNameOptions.
protected  java.lang.String evaluateDerivedIssuers(org.opensaml.xml.security.x509.X509Credential requestCredential, MessageContext messageContext)
          Evaluate any candidate issuer entity ID's which may be derived from the credential or other message context information.
protected  java.lang.String evaluateSubjectAltNames(org.opensaml.xml.security.x509.X509Credential requestCredential, MessageContext messageContext)
          Evaluate the issuer entity ID as derived from the cert subject alternative names specified by types enumerated in CertificateNameOptions.getSubjectAltNames().
protected  java.lang.String evaluateSubjectCommonName(org.opensaml.xml.security.x509.X509Credential requestCredential, MessageContext messageContext)
          Evaluate the issuer entity ID as derived from the cert subject common name (CN).
protected  java.lang.String evaluateSubjectDN(org.opensaml.xml.security.x509.X509Credential requestCredential, MessageContext messageContext)
          Evaluate the issuer entity ID as derived from the cert subject DN.
protected  java.util.List<java.lang.String> getAltNames(java.security.cert.X509Certificate cert, java.lang.Integer altNameType)
          Get the list of subject alt name values from the certificate which are of the specified alt name type.
protected  CertificateNameOptions getCertificateNameOptions()
          Get the currently configured certificate name options.
protected  java.lang.String getCommonName(java.security.cert.X509Certificate cert)
          Get the first common name (CN) value from the subject DN of the specified certificate.
protected  java.lang.String getSubjectName(java.security.cert.X509Certificate cert)
          Get subject name from a certificate, using the currently configured X500DNHandler and subject DN output format.
 
Methods inherited from class org.opensaml.ws.security.provider.BaseTrustEngineRule
evaluate, evaluate, getTrustEngine
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ClientCertAuthRule

public ClientCertAuthRule(org.opensaml.xml.security.trust.TrustEngine<org.opensaml.xml.security.x509.X509Credential> engine,
                          CertificateNameOptions nameOptions)
Constructor.

Parameters:
engine - Trust engine used to verify the request X509Credential
nameOptions - options for deriving issuer names from an X.509 certificate
Method Detail

evaluate

public void evaluate(MessageContext messageContext)
              throws SecurityPolicyException
Evaluates the message context against the rule.

Parameters:
messageContext - the message context being evaluated
Throws:
SecurityPolicyException - thrown if the message context does not meet the requirements of the rule, or if there is a non-recoverable error during evaluation

getCertificateNameOptions

protected CertificateNameOptions getCertificateNameOptions()
Get the currently configured certificate name options.

Returns:
the certificate name options

doEvaluate

protected void doEvaluate(org.opensaml.xml.security.x509.X509Credential requestCredential,
                          MessageContext messageContext)
                   throws SecurityPolicyException
Evaluate the request credential.

Parameters:
requestCredential - the X509Credential derived from the request
messageContext - the message context being evaluated
Throws:
SecurityPolicyException - thrown if a message context issuer is present and the client certificate token can not be trusted on that basis, or if there is error during evaluation processing

buildCriteriaSet

protected org.opensaml.xml.security.CriteriaSet buildCriteriaSet(java.lang.String entityID,
                                                                 MessageContext messageContext)
                                                          throws SecurityPolicyException
Subclasses are required to implement this method to build a criteria set for the trust engine according to trust engine and application-specific needs.

Specified by:
buildCriteriaSet in class BaseTrustEngineRule<org.opensaml.xml.security.x509.X509Credential>
Parameters:
entityID - the candidate issuer entity ID which is being evaluated
messageContext - the message context which is being evaluated
Returns:
a newly constructly set of criteria suitable for the configured trust engine
Throws:
SecurityPolicyException - thrown if criteria set can not be constructed

evaluateDerivedIssuers

protected java.lang.String evaluateDerivedIssuers(org.opensaml.xml.security.x509.X509Credential requestCredential,
                                                  MessageContext messageContext)
                                           throws SecurityPolicyException
Evaluate any candidate issuer entity ID's which may be derived from the credential or other message context information.

This serves primarily as an extension point for subclasses to implement application-specific logic.

If multiple derived candidate entity ID's would satisfy the trust engine criteria, the choice of which one to return as the canonical issuer value is implementation-specific.

Parameters:
requestCredential - the X509Credential derived from the request
messageContext - the message context being evaluated
Returns:
an issuer entity ID which was successfully evaluated by the trust engine
Throws:
SecurityPolicyException - thrown if there is error during processing

evaluateCertificateNameDerivedIssuers

protected java.lang.String evaluateCertificateNameDerivedIssuers(org.opensaml.xml.security.x509.X509Credential requestCredential,
                                                                 MessageContext messageContext)
                                                          throws SecurityPolicyException
Evaluate candidate issuer entity ID's which may be derived from the request credential's entity certificate according to the options supplied via CertificateNameOptions.

Configured certificate name types are derived as candidate issuers and processed in the following order:

  1. The certificate subject DN string as serialized by the X500DNHandler obtained via CertificateNameOptions.getX500DNHandler() and using the output format indicated by CertificateNameOptions.getX500SubjectDNFormat().
  2. Subject alternative names of the types configured via CertificateNameOptions.getSubjectAltNames(). Note that this is a LinkedHashSet, so the order of evaluation is the order of insertion.
  3. The first common name (CN) value appearing in the certificate subject DN.

The first one of the above which is successfully evaluated by the trust engine using criteria built from BaseTrustEngineRule.buildCriteriaSet(String, MessageContext) will be returned.

Parameters:
requestCredential - the X509Credential derived from the request
messageContext - the message context being evaluated
Returns:
an issuer entity ID which was successfully evaluated by the trust engine
Throws:
SecurityPolicyException - thrown if there is error during processing

evaluateSubjectCommonName

protected java.lang.String evaluateSubjectCommonName(org.opensaml.xml.security.x509.X509Credential requestCredential,
                                                     MessageContext messageContext)
                                              throws SecurityPolicyException
Evaluate the issuer entity ID as derived from the cert subject common name (CN). Only the first CN value from the subject DN is evaluated.

Parameters:
requestCredential - the X509Credential derived from the request
messageContext - the message context being evaluated
Returns:
an issuer entity ID which was successfully evaluated by the trust engine
Throws:
SecurityPolicyException - thrown if there is error during processing

evaluateSubjectDN

protected java.lang.String evaluateSubjectDN(org.opensaml.xml.security.x509.X509Credential requestCredential,
                                             MessageContext messageContext)
                                      throws SecurityPolicyException
Evaluate the issuer entity ID as derived from the cert subject DN.

Parameters:
requestCredential - the X509Credential derived from the request
messageContext - the message context being evaluated
Returns:
an issuer entity ID which was successfully evaluated by the trust engine
Throws:
SecurityPolicyException - thrown if there is error during processing

evaluateSubjectAltNames

protected java.lang.String evaluateSubjectAltNames(org.opensaml.xml.security.x509.X509Credential requestCredential,
                                                   MessageContext messageContext)
                                            throws SecurityPolicyException
Evaluate the issuer entity ID as derived from the cert subject alternative names specified by types enumerated in CertificateNameOptions.getSubjectAltNames().

Parameters:
requestCredential - the X509Credential derived from the request
messageContext - the message context being evaluated
Returns:
an issuer entity ID which was successfully evaluated by the trust engine
Throws:
SecurityPolicyException - thrown if there is error during processing

getCommonName

protected java.lang.String getCommonName(java.security.cert.X509Certificate cert)
Get the first common name (CN) value from the subject DN of the specified certificate.

Parameters:
cert - the certificate being processed
Returns:
the first CN value, or null if there are none

getSubjectName

protected java.lang.String getSubjectName(java.security.cert.X509Certificate cert)
Get subject name from a certificate, using the currently configured X500DNHandler and subject DN output format.

Parameters:
cert - the certificate being processed
Returns:
the subject name

getAltNames

protected java.util.List<java.lang.String> getAltNames(java.security.cert.X509Certificate cert,
                                                       java.lang.Integer altNameType)
Get the list of subject alt name values from the certificate which are of the specified alt name type.

Parameters:
cert - the certificate from which to extract alt names
altNameType - the type of alt name to extract
Returns:
the list of certificate subject alt names


Copyright © 2006-2009 Internet2. All Rights Reserved.