org.opensaml.security.messaging.impl

Class BaseClientCertAuthSecurityHandler

java.lang.Object

net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

org.opensaml.messaging.handler.AbstractMessageHandler

org.opensaml.security.messaging.impl.BaseTrustEngineSecurityHandler<X509Credential>

org.opensaml.security.messaging.impl.BaseClientCertAuthSecurityHandler

All Implemented Interfaces:

net.shibboleth.utilities.java.support.component.Component, net.shibboleth.utilities.java.support.component.DestructableComponent, net.shibboleth.utilities.java.support.component.InitializableComponent, MessageHandler

Direct Known Subclasses:

SAMLMDClientCertAuthSecurityHandler

public abstract class BaseClientCertAuthSecurityHandler
extends BaseTrustEngineSecurityHandler<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 supplied HttpServletRequest contains a peer X509Credential as returned via ServletRequestX509CredentialAdapter.

The entity ID used to perform trust evaluation of the X509 credential is first retrieved via getCertificatePresenterEntityID(MessageContext). If this value is non-null, then trust evaluation proceeds on that basis. If trust evaluation using this entity ID is successful, the message context's authentication state will be set to true via setAuthenticatedState(MessageContext, boolean) and processing is terminated. If unsuccessful, a MessageHandlerException is thrown.

If no value was available from getCertificatePresenterEntityID(MessageContext), then rule evaluation will be attempted as described in evaluateCertificateNameDerivedPresenters(X509Credential, MessageContext), based on the currently configured certificate name evaluation options. If this method returns a non-null certificate presenter entity ID, it will be set on the message context by calling setAuthenticatedCertificatePresenterEntityID(MessageContext, String). The message context's authentication state will be set to true via setAuthenticatedState(MessageContext, boolean). Rule processing is then terminated. If the method returns null, the client certificate presenter entity ID and message context authentication state will remain unmodified and rule processing continues.

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

Field Summary

Fields

Modifier and Type	Field and Description
private CertificateNameOptions	certNameOptions Options for deriving client cert presenter entity ID's from an X.509 certificate.
private javax.servlet.http.HttpServletRequest	httpServletRequest The HttpServletRequest being processed.
private org.slf4j.Logger	log Logger.

Constructor Summary

Constructors

Constructor and Description
BaseClientCertAuthSecurityHandler()

Method Summary

Modifier and Type	Method and Description
protected net.shibboleth.utilities.java.support.resolver.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(X509Credential requestCredential, MessageContext messageContext) Evaluate the request credential.
protected void	doInitialize()
protected void	doInvoke(MessageContext messageContext) Performs the handler logic.
protected boolean	doPreInvoke(MessageContext messageContext) Called prior to execution, handlers may override this method to perform pre-processing for a request.
protected java.lang.String	evaluateCertificateNameDerivedPresenters(X509Credential requestCredential, MessageContext messageContext) Evaluate candidate presenter 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	evaluateDerivedPresenters(X509Credential requestCredential, MessageContext messageContext) Evaluate any candidate presenter entity ID's which may be derived from the credential or other message context information.
protected java.lang.String	evaluateSubjectAltNames(X509Credential requestCredential, MessageContext messageContext) Evaluate the presenter entity ID as derived from the cert subject alternative names specified by types enumerated in CertificateNameOptions.getSubjectAltNames().
protected java.lang.String	evaluateSubjectCommonName(X509Credential requestCredential, MessageContext messageContext) Evaluate the presenter entity ID as derived from the cert subject common name (CN).
protected java.lang.String	evaluateSubjectDN(X509Credential requestCredential, MessageContext messageContext) Evaluate the presenter 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 certificate name options in use.
protected abstract java.lang.String	getCertificatePresenterEntityID(MessageContext messageContext) Get the entity ID of the presenter of the client TLS certificate, as will be used for trust evaluation purposes.
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.
javax.servlet.http.HttpServletRequest	getHttpServletRequest() Get the HTTP servlet request being processed.
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.
protected TrustEngine<? super X509Credential>	resolveTrustEngine(MessageContext messageContext) Resolve a TrustEngine instance of the appropriate type from the message context.
protected abstract void	setAuthenticatedCertificatePresenterEntityID(MessageContext messageContext, java.lang.String entityID) Store the successfully authenticated derived entity ID of the certificate presenter in the message context.
protected abstract void	setAuthenticatedState(MessageContext messageContext, boolean authenticated) Store the indicated message authentication state in the message context.
void	setHttpServletRequest(javax.servlet.http.HttpServletRequest request) Set the HTTP servlet request being processed.

Methods inherited from class org.opensaml.security.messaging.impl.BaseTrustEngineSecurityHandler

evaluate, evaluate, getTrustEngine

Methods inherited from class org.opensaml.messaging.handler.AbstractMessageHandler

doPostInvoke, doPostInvoke, getLogPrefix, invoke

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

destroy, doDestroy, initialize, isDestroyed, isInitialized

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.shibboleth.utilities.java.support.component.InitializableComponent

initialize, isInitialized

Field Detail

log

@Nonnull
private final org.slf4j.Logger log

Logger.

certNameOptions

@Nullable
private CertificateNameOptions certNameOptions

Options for deriving client cert presenter entity ID's from an X.509 certificate.

httpServletRequest

@NonnullAfterInit
private javax.servlet.http.HttpServletRequest httpServletRequest

The HttpServletRequest being processed.

Constructor Detail

BaseClientCertAuthSecurityHandler

public BaseClientCertAuthSecurityHandler()

Method Detail

getHttpServletRequest

@NonnullAfterInit
public javax.servlet.http.HttpServletRequest getHttpServletRequest()

Get the HTTP servlet request being processed.

Returns:

Returns the request.

setHttpServletRequest

public void setHttpServletRequest(@Nonnull
                                  javax.servlet.http.HttpServletRequest request)

Set the HTTP servlet request being processed.

Parameters:

request - The to set.

getCertificateNameOptions

@Nullable
protected CertificateNameOptions getCertificateNameOptions()

Get the certificate name options in use.

Returns:

Returns the certNameOptions.

doInitialize

protected void doInitialize()
                     throws net.shibboleth.utilities.java.support.component.ComponentInitializationException

Overrides:

doInitialize in class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

Throws:

net.shibboleth.utilities.java.support.component.ComponentInitializationException

resolveTrustEngine

@Nullable
protected TrustEngine<? super X509Credential> resolveTrustEngine(@Nonnull
                                                                           MessageContext messageContext)

Resolve a TrustEngine instance of the appropriate type from the message context.

Specified by:

resolveTrustEngine in class BaseTrustEngineSecurityHandler<X509Credential>

Parameters:

messageContext - the message context which is being evaluated

Returns:

the resolved TrustEngine, may be null

doPreInvoke

protected boolean doPreInvoke(@Nonnull
                              MessageContext messageContext)
                       throws MessageHandlerException

Called prior to execution, handlers may override this method to perform pre-processing for a request.

If false is returned, execution will not proceed.

If returning successfully, the last step should be to return the result of the superclass version of this method.

Overrides:

doPreInvoke in class BaseTrustEngineSecurityHandler<X509Credential>

Parameters:

messageContext - the message context on which to invoke the handler

Returns:

true iff execution should proceed

Throws:

MessageHandlerException - if there is a problem executing the handler pre-routine

doInvoke

protected void doInvoke(@Nonnull
                        MessageContext messageContext)
                 throws MessageHandlerException

Performs the handler logic.

Specified by:

doInvoke in class AbstractMessageHandler

Parameters:

messageContext - the message context on which to invoke the handler

Throws:

MessageHandlerException - if there is an error invoking the handler on the message context

doEvaluate

protected void doEvaluate(@Nonnull
                          X509Credential requestCredential,
                          @Nonnull
                          MessageContext messageContext)
                   throws MessageHandlerException

Evaluate the request credential.

Parameters:

requestCredential - the X509Credential derived from the request

messageContext - the message context being evaluated

Throws:

MessageHandlerException - thrown if a certificate presenter entity ID available from the message context and the client certificate token can not be establishd as trusted on that basis, or if there is error during evaluation processing

getCertificatePresenterEntityID

@Nullable
protected abstract java.lang.String getCertificatePresenterEntityID(@Nonnull
                                                                              MessageContext messageContext)

Get the entity ID of the presenter of the client TLS certificate, as will be used for trust evaluation purposes.

This tends to be performed in a protcol-specific manner, so it is therefore abstract and must be implemented in a concrete subclass.

Parameters:

messageContext - the current message context

Returns:

the entity ID of the client TLS certificate presenter

setAuthenticatedCertificatePresenterEntityID

protected abstract void setAuthenticatedCertificatePresenterEntityID(@Nonnull
                                                                     MessageContext messageContext,
                                                                     @Nullable
                                                                     java.lang.String entityID)

Store the successfully authenticated derived entity ID of the certificate presenter in the message context.

This tends to be performed in a protocol-specific manner, so it is therefore abstract and must be implemented in a concrete subclass.

Parameters:

messageContext - the current message context

entityID - the successfully authenticated derived entity ID of the client TLS certificate presenter

setAuthenticatedState

protected abstract void setAuthenticatedState(@Nonnull
                                              MessageContext messageContext,
                                              boolean authenticated)

Store the indicated message authentication state in the message context.

This tends to be performed in a protocol-specific manner, so it is therefore abstract and must be implemented in a concrete subclass.

Parameters:

messageContext - the current message context

authenticated - flag indicating what authentication state to store

buildCriteriaSet

@Nullable
protected net.shibboleth.utilities.java.support.resolver.CriteriaSet buildCriteriaSet(@Nullable
                                                                                                java.lang.String entityID,
                                                                                                @Nonnull
                                                                                                MessageContext messageContext)
                                                                                         throws MessageHandlerException

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 BaseTrustEngineSecurityHandler<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:

MessageHandlerException - thrown if criteria set can not be constructed

evaluateDerivedPresenters

@Nullable
protected java.lang.String evaluateDerivedPresenters(@Nonnull
                                                               X509Credential requestCredential,
                                                               @Nonnull
                                                               MessageContext messageContext)
                                                        throws MessageHandlerException

Evaluate any candidate presenter 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 presenter entity ID value is implementation-specific.

Parameters:

requestCredential - the X509Credential derived from the request

messageContext - the message context being evaluated

Returns:

a presenter entity ID which was successfully evaluated by the trust engine

Throws:

MessageHandlerException - thrown if there is error during processing

evaluateCertificateNameDerivedPresenters

@Nullable
protected java.lang.String evaluateCertificateNameDerivedPresenters(@Nullable
                                                                              X509Credential requestCredential,
                                                                              @Nonnull
                                                                              MessageContext messageContext)
                                                                       throws MessageHandlerException

Evaluate candidate presenter 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 presenter entity ID's 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 BaseTrustEngineSecurityHandler.buildCriteriaSet(String, MessageContext) will be returned.

Parameters:

requestCredential - the X509Credential derived from the request

messageContext - the message context being evaluated

Returns:

a certificate presenter entity ID which was successfully evaluated by the trust engine

Throws:

MessageHandlerException - thrown if there is error during processing

evaluateSubjectCommonName

@Nullable
protected java.lang.String evaluateSubjectCommonName(@Nonnull
                                                               X509Credential requestCredential,
                                                               @Nonnull
                                                               MessageContext messageContext)
                                                        throws MessageHandlerException

Evaluate the presenter 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:

a presenter entity ID which was successfully evaluated by the trust engine

Throws:

MessageHandlerException - thrown if there is error during processing

evaluateSubjectDN

@Nullable
protected java.lang.String evaluateSubjectDN(@Nonnull
                                                       X509Credential requestCredential,
                                                       @Nonnull
                                                       MessageContext messageContext)
                                                throws MessageHandlerException

Evaluate the presenter entity ID as derived from the cert subject DN.

Parameters:

requestCredential - the X509Credential derived from the request

messageContext - the message context being evaluated

Returns:

a presenter entity ID which was successfully evaluated by the trust engine

Throws:

MessageHandlerException - thrown if there is error during processing

evaluateSubjectAltNames

@Nullable
protected java.lang.String evaluateSubjectAltNames(@Nonnull
                                                             X509Credential requestCredential,
                                                             @Nonnull
                                                             MessageContext messageContext)
                                                      throws MessageHandlerException

Evaluate the presenter 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:

a presenter entity ID which was successfully evaluated by the trust engine

Throws:

MessageHandlerException - thrown if there is error during processing

getCommonName

@Nullable
protected java.lang.String getCommonName(@Nonnull
                                                   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

@Nullable
protected java.lang.String getSubjectName(@Nonnull
                                                    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

@Nonnull
 @NonnullElements
protected java.util.List<java.lang.String> getAltNames(@Nonnull
                                                                                  java.security.cert.X509Certificate cert,
                                                                                  @Nonnull
                                                                                  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