Package org.opensaml.security.messaging.impl

# Class BaseClientCertAuthSecurityHandler

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
org.opensaml.messaging.handler.AbstractMessageHandler
org.opensaml.security.messaging.impl.BaseTrustEngineSecurityHandler<X509Credential>
org.opensaml.security.messaging.impl.BaseClientCertAuthSecurityHandler

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `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
Description
`private CertificateNameOptions`
`certNameOptions`
Options for deriving client cert presenter entity ID's from an X.509 certificate.
`private NonnullSupplier<HttpServletRequest>`
`httpServletRequestSupplier`
The HttpServletRequest being processed.
`private final org.slf4j.Logger`
`log`
Logger.

## Constructor Summary

Constructors
Constructor
Description
`BaseClientCertAuthSecurityHandler()`

## Method Summary

Modifier and Type
Method
Description
`protected CriteriaSet`
`buildCriteriaSet(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 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 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 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 String`
`evaluateSubjectCommonName(X509Credential requestCredential, MessageContext messageContext)`
Evaluate the presenter entity ID as derived from the cert subject common name (CN).
`protected String`
`evaluateSubjectDN(X509Credential requestCredential, MessageContext messageContext)`
Evaluate the presenter entity ID as derived from the cert subject DN.
`protected List<String>`
`getAltNames(X509Certificate cert, 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 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 String`
`getCommonName(X509Certificate cert)`
Get the first common name (CN) value from the subject DN of the specified certificate.
`HttpServletRequest`
`getHttpServletRequest()`
Get the current HTTP request if available.
`NonnullSupplier<HttpServletRequest>`
`getHttpServletRequestSupplier()`
Get the supplier for HTTP request if available.
`protected String`
`getSubjectName(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, 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`
`setHttpServletRequestSupplier(NonnullSupplier<HttpServletRequest> requestSupplier)`
Set the current HTTP request Supplier.

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

`evaluate, evaluate, getTrustEngine`

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

`doPostInvoke, doPostInvoke, getActivationCondition, getLogPrefix, invoke, isPreInvokeCalled, setActivationCondition`

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, doDestroy, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, 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.shared.component.InitializableComponent

`initialize, isInitialized`

## Field Details

### 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.

### httpServletRequestSupplier

@NonnullAfterInit private NonnullSupplier<HttpServletRequest> httpServletRequestSupplier
The HttpServletRequest being processed.

## Constructor Details

### BaseClientCertAuthSecurityHandler

public BaseClientCertAuthSecurityHandler()

## Method Details

### getHttpServletRequest

@NonnullAfterInit public HttpServletRequest getHttpServletRequest()
Get the current HTTP request if available.

Returns:
  current HTTP request

### getHttpServletRequestSupplier

@NonnullAfterInit public NonnullSupplier<HttpServletRequest> getHttpServletRequestSupplier()
Get the supplier for HTTP request if available.

Returns:
  current HTTP request

### setHttpServletRequestSupplier

public void setHttpServletRequestSupplier(@Nullable NonnullSupplier<HttpServletRequest> requestSupplier)
Set the current HTTP request Supplier.

Parameters:
  `requestSupplier` - Supplier for the current HTTP request

### getCertificateNameOptions

@Nullable protected CertificateNameOptions getCertificateNameOptions()
Get the certificate name options in use.

Returns:
  Returns the certNameOptions.

### doInitialize

protected void doInitialize() throws ComponentInitializationException

Overrides:
  `doInitialize` in class `AbstractInitializableComponent`
Throws:
  `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.

The default impl applies the `Predicate` set via the `AbstractMessageHandler.setActivationCondition(Predicate)`.

If false is returned, execution will not proceed.

Subclasses which override this method should generally invoke the super version of this method first, so that the activation condition will be applied up front, and immediately return false if the super version returns false. This avoids unnecessary execution of the remaining pre-invocation code if the handler ultimately will not execute.

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 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 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 CriteriaSet buildCriteriaSet(@Nullable 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 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 String evaluateCertificateNameDerivedPresenters(@Nonnull 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 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 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 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 String getCommonName(@Nonnull 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 String getSubjectName(@Nonnull 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 @Unmodifiable @NotLive protected List<String> getAltNames(@Nonnull X509Certificate cert, @Nonnull 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