org.opensaml.xml.security.x509
Class PKIXTrustEvaluator

java.lang.Object
  extended by org.opensaml.xml.security.x509.PKIXTrustEvaluator

public class PKIXTrustEvaluator
extends java.lang.Object

Auxillary trust evaluator that validates X.509 credentials using PKIX validation.

The main entry point for calling implementations is: pkixValidate(PKIXValidationInformation, X509Credential). Callers should construct an appropriate set of PKIX validation information from a source of trusted information.

Callers may perform optional trusted key name checking using checkName(X509Credential, Set). This name check can be used to verify that at least one of the supported name type values contained within the untrusted credential's entity certificate matches at least one value from the set of trusted key names supplied from trusted credential information. If the supplied set of trusted key names is null or empty, the match is considered successful.

Name checking may be performed in conjunction with PKIX validation by using the overloaded method pkixValidate(PKIXValidationInformation, Set, X509Credential). If there is a match, the trust engine will procceed with the more costly PKIX validation. If there is no match, the engine will assume the untrusted credential is not a valid credential and will abort the validation.

Supported types of certificate-derived names for name checking purposes are:

  1. Subject alternative names.
  2. The first (i.e. most specific) common name (CN) from the subject distinguished name.
  3. The complete subject distinguished name.

Name checking is enabled by default for all of the supported name types. The types of subject alternative names to process are specified by using the appropriate constant values defined in X509Util. By default the following types of subject alternative names are checked: DNS (X509Util.DNS_ALT_NAME) and URI (X509Util.URI_ALT_NAME).

The subject distinguished name from the untrusted certificate is compared to the trusted key names for complete DN matching purposes by parsing each trusted key name into an X500Principal as returned by the configured instance of X500DNHandler. The resulting distinguished name is then compared with the certificate subject using X500Principal.equals(Object). The default X500DNHandler used is InternalX500DNHandler.


Constructor Summary
PKIXTrustEvaluator()
          Constructor.
 
Method Summary
protected  java.security.cert.CertStore buildCertStore(PKIXValidationInformation validationInfo, X509Credential untrustedCredential)
          Creates the certificate store that will be used during validation.
protected  boolean checkName(X509Credential untrustedCredential, java.util.Set<java.lang.String> trustedNames)
          Checks whether any of the supported name type values contained within the entity certificate of the specified credential, and for which name checking is configured, matches any of the supplied trusted names.
 boolean checkSubjectAltNames()
          Gets whether to check the untrusted credential's entity certificate subject alt names against the trusted key name values.
 boolean checkSubjectDN()
          Gets whether to check the untrusted credential's entity certificate subject DN against the trusted key name values.
 boolean checkSubjectDNCommonName()
          Gets whether to check the untrusted credential's entity certificate subject DN's common name (CN) against the trusted key name values.
protected  java.security.cert.PKIXBuilderParameters getPKIXBuilderParameters(PKIXValidationInformation validationInfo, X509Credential untrustedCredential)
          Creates the set of PKIX builder parameters to use when building the cert path builder.
 java.util.Set<java.lang.Integer> getSubjectAltNameTypes()
          The set of types of subject alternative names to process.
protected  java.util.Set<java.security.cert.TrustAnchor> getTrustAnchors(PKIXValidationInformation validationInfo)
          Creates the collection of trust anchors to use during validation.
 X500DNHandler getX500DNHandler()
          Get the handler which process X.500 distinguished names.
 boolean isNameChecking()
          Gets whether any of the supported name type checking is currently enabled.
 boolean pkixValidate(PKIXValidationInformation validationInfo, java.util.Set<java.lang.String> trustedNames, X509Credential untrustedCredential)
          Attempts to validate the given entity credential using the PKIX information provided.
 boolean pkixValidate(PKIXValidationInformation validationInfo, X509Credential untrustedCredential)
          Attempts to validate the given entity credential using the PKIX information provided.
protected  boolean processSubjectAltNames(java.security.cert.X509Certificate untrustedCertificate, java.util.Set<java.lang.String> trustedNames)
          Process name checking for the subject alt names within the certificate.
protected  boolean processSubjectDN(java.security.cert.X509Certificate untrustedCertificate, java.util.Set<java.lang.String> trustedNames)
          Process name checking for the certificate subject DN.
protected  boolean processSubjectDNCommonName(java.security.cert.X509Certificate untrustedCertificate, java.util.Set<java.lang.String> trustedNames)
          Process name checking for a certificate subject DN's common name.
 void setCheckSubjectAltNames(boolean check)
          Sets whether to check the untrusted credential's entity certificate subject alt names against the trusted key name values.
 void setCheckSubjectDN(boolean check)
          Sets whether to check the untrusted credential's entity certificate subject DN against the trusted key name values.
 void setCheckSubjectDNCommonName(boolean check)
          Sets whether to check the untrusted credential's entity certificate subject DN's common name (CN) against the trusted key name values.
 void setX500DNHandler(X500DNHandler handler)
          Set the handler which process X.500 distinguished names.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PKIXTrustEvaluator

public PKIXTrustEvaluator()
Constructor.

Method Detail

isNameChecking

public boolean isNameChecking()
Gets whether any of the supported name type checking is currently enabled.

Returns:
true if any of the supported name type checking categories is currently enabled, false otherwise

getSubjectAltNameTypes

public java.util.Set<java.lang.Integer> getSubjectAltNameTypes()
The set of types of subject alternative names to process. Name types are represented using the constant OID tag name values defined in X509Util.

Returns:
the modifiable set of alt name identifiers

checkSubjectAltNames

public boolean checkSubjectAltNames()
Gets whether to check the untrusted credential's entity certificate subject alt names against the trusted key name values.

Returns:
whether to check the untrusted credential's entity certificate subject alt names against the trusted key names

setCheckSubjectAltNames

public void setCheckSubjectAltNames(boolean check)
Sets whether to check the untrusted credential's entity certificate subject alt names against the trusted key name values.

Parameters:
check - whether to check the untrusted credential's entity certificate subject alt names against the trusted key names

checkSubjectDNCommonName

public boolean checkSubjectDNCommonName()
Gets whether to check the untrusted credential's entity certificate subject DN's common name (CN) against the trusted key name values.

Returns:
whether to check the untrusted credential's entity certificate subject DN's CN against the trusted key names

setCheckSubjectDNCommonName

public void setCheckSubjectDNCommonName(boolean check)
Sets whether to check the untrusted credential's entity certificate subject DN's common name (CN) against the trusted key name values.

Parameters:
check - whether to check the untrusted credential's entity certificate subject DN's CN against the trusted key names

checkSubjectDN

public boolean checkSubjectDN()
Gets whether to check the untrusted credential's entity certificate subject DN against the trusted key name values.

Returns:
whether to check the untrusted credential's entity certificate subject DN against the trusted key names

setCheckSubjectDN

public void setCheckSubjectDN(boolean check)
Sets whether to check the untrusted credential's entity certificate subject DN against the trusted key name values.

Parameters:
check - whether to check the untrusted credential's entity certificate subject DN against the trusted key names

getX500DNHandler

public X500DNHandler getX500DNHandler()
Get the handler which process X.500 distinguished names. Defaults to InternalX500DNHandler.

Returns:
returns the X500DNHandler instance

setX500DNHandler

public void setX500DNHandler(X500DNHandler handler)
Set the handler which process X.500 distinguished names. Defaults to InternalX500DNHandler.

Parameters:
handler - the new X500DNHandler instance

checkName

protected boolean checkName(X509Credential untrustedCredential,
                            java.util.Set<java.lang.String> trustedNames)
Checks whether any of the supported name type values contained within the entity certificate of the specified credential, and for which name checking is configured, matches any of the supplied trusted names.

Parameters:
untrustedCredential - the credential for the entity to validate
trustedNames - trusted names against which the credential will be evaluated
Returns:
if true the name check succeeds, false if not

processSubjectDNCommonName

protected boolean processSubjectDNCommonName(java.security.cert.X509Certificate untrustedCertificate,
                                             java.util.Set<java.lang.String> trustedNames)
Process name checking for a certificate subject DN's common name.

Parameters:
untrustedCertificate - the certificate to process
trustedNames - the set of trusted names
Returns:
true if the subject DN common name matches the set of trusted names, false otherwise

processSubjectDN

protected boolean processSubjectDN(java.security.cert.X509Certificate untrustedCertificate,
                                   java.util.Set<java.lang.String> trustedNames)
Process name checking for the certificate subject DN.

Parameters:
untrustedCertificate - the certificate to process
trustedNames - the set of trusted names
Returns:
true if the subject DN matches the set of trusted names, false otherwise

processSubjectAltNames

protected boolean processSubjectAltNames(java.security.cert.X509Certificate untrustedCertificate,
                                         java.util.Set<java.lang.String> trustedNames)
Process name checking for the subject alt names within the certificate.

Parameters:
untrustedCertificate - the certificate to process
trustedNames - the set of trusted names
Returns:
true if one of the subject alt names matches the set of trusted names, false otherwise

pkixValidate

public boolean pkixValidate(PKIXValidationInformation validationInfo,
                            java.util.Set<java.lang.String> trustedNames,
                            X509Credential untrustedCredential)
                     throws java.lang.SecurityException
Attempts to validate the given entity credential using the PKIX information provided.

Parameters:
untrustedCredential - the entity credential to validate
trustedNames - trusted names against which the credential will be evaluated if name checking is enabled
validationInfo - the PKIX information to validate the credential against
Returns:
true if the given credential is valid, false if not
Throws:
java.lang.SecurityException - thrown if there is a problem attempting the validation

pkixValidate

public boolean pkixValidate(PKIXValidationInformation validationInfo,
                            X509Credential untrustedCredential)
                     throws java.lang.SecurityException
Attempts to validate the given entity credential using the PKIX information provided.

Parameters:
untrustedCredential - the entity credential to validate
validationInfo - the PKIX information to validate the credential against
Returns:
true if the given credential is valid, false if not
Throws:
java.lang.SecurityException - thrown if there is a problem attempting the validation

getPKIXBuilderParameters

protected java.security.cert.PKIXBuilderParameters getPKIXBuilderParameters(PKIXValidationInformation validationInfo,
                                                                            X509Credential untrustedCredential)
                                                                     throws java.security.GeneralSecurityException
Creates the set of PKIX builder parameters to use when building the cert path builder.

Parameters:
validationInfo - PKIX validation information
untrustedCredential - credential to be validated
Returns:
PKIX builder params
Throws:
java.security.GeneralSecurityException - thrown if the parameters can not be created

getTrustAnchors

protected java.util.Set<java.security.cert.TrustAnchor> getTrustAnchors(PKIXValidationInformation validationInfo)
Creates the collection of trust anchors to use during validation.

Parameters:
validationInfo - PKIX validation information
Returns:
trust anchors to use during validation

buildCertStore

protected java.security.cert.CertStore buildCertStore(PKIXValidationInformation validationInfo,
                                                      X509Credential untrustedCredential)
                                               throws java.security.GeneralSecurityException
Creates the certificate store that will be used during validation.

Parameters:
validationInfo - PKIX validation information
untrustedCredential - credential to be validated
Returns:
certificate store used during validation
Throws:
java.security.GeneralSecurityException - thrown if the certificate store can not be created from the cert and CRL material