Package org.opensaml.security.httpclient.impl

# Class SecurityEnhancedTLSSocketFactory

java.lang.Object
org.opensaml.security.httpclient.impl.SecurityEnhancedTLSSocketFactory

All Implemented Interfaces:
  `org.apache.hc.client5.http.socket.ConnectionSocketFactory`, `org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory`

public class SecurityEnhancedTLSSocketFactory extends Object implements org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory
An security-enhanced implementation of HttpClient's TLS-capable `LayeredConnectionSocketFactory`.

This implementation wraps an existing TLS socket factory instance, decorating it with additional support for:

- Loading and clearing thread-local instances of `TrustEngine``<``Credential``>` and `CriteriaSet` used for server TLS.
- Loading and clearing a thread-local instance of `X509Credential` used for client TLS.

The context keys used by this component are as follows, defined in `HttpClientSecurityConstants`:

- `HttpClientSecurityConstants.CONTEXT_KEY_TRUST_ENGINE`: The trust engine instance used. Supplied by the HttpClient caller. Must be an instance of `TrustEngine``<``Credential``>`.
- `HttpClientSecurityConstants.CONTEXT_KEY_CRITERIA_SET`: The criteria set instance used. Supplied by the HttpClient caller. Must be an instance of `CriteriaSet`.
- `HttpClientSecurityConstants.CONTEXT_KEY_SERVER_TLS_CREDENTIAL_TRUSTED`: The result of the trust evaluation, if it was performed. Populated by this component. Will be a `Boolean`, where `true` means the server TLS was evaluated as trusted, `false` means the credential was evaluated as untrusted. A null or missing value means that trust engine evaluation was not performed.
- `HttpClientSecurityConstants.CONTEXT_KEY_CLIENT_TLS_CREDENTIAL`: The client TLS credential used. Supplied by the HttpClient caller. Must be an instance of `X509Credential`.

Support for server TLS via trust engine evaluation requires use of a compatible `TrustManager` implementation configured in the `SSLContext` of the wrapped `LayeredConnectionSocketFactory`, such as `ThreadLocalX509TrustManager`.

Support for client TLS requires use of a compatible `KeyManager` implementation configured in the `SSLContext` of the wrapped `LayeredConnectionSocketFactory`, such as `ThreadLocalX509CredentialKeyManager`.

If the trust engine context attribute is not populated by the caller, then no server TLS thread-local data is populated. If the wrapped socket factory's `X509TrustManager` implementation requires this data (for example `ThreadLocalX509TrustManager`), then a fatal exception is expected to be thrown.

If the client TLS credential context attribute is not populated by the caller, then no client TLS thread-local data is populated, and client TLS will not be attempted.

## Field Summary

Fields
Modifier and Type
Field
Description
`private static final ThreadLocalClientTLSCredentialHandler`
`CLIENT_TLS_HANDLER`
Instance of `ThreadLocalClientTLSCredentialHandler` to use.
`private final org.slf4j.Logger`
`log`
Logger.
`private static final ThreadLocalServerTLSHandler`
`SERVER_TLS_HANDLER`
Instance of `ThreadLocalClientTLSCredentialHandler` to use.
`private org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory`
`wrappedFactory`
The HttpClient socket factory instance wrapped by this implementation.

## Constructor Summary

Constructors
Constructor
Description
`SecurityEnhancedTLSSocketFactory(org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory factory)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected void`
`checkAndEvaluateServerTLS(Socket socket)`
Check that the evaluation of the socket certificate using the data in `ThreadLocalX509TrustEngineContext` has been performed, if applicable, and if not, evaluate it.
`Socket`
`connectSocket(org.apache.hc.core5.util.TimeValue connectTimeout, Socket sock, org.apache.hc.core5.http.HttpHost host, InetSocketAddress remoteAddress, InetSocketAddress localAddress, org.apache.hc.core5.http.protocol.HttpContext context)`
`Socket`
`createLayeredSocket(Socket socket, String target, int port, org.apache.hc.core5.http.protocol.HttpContext context)`
`Socket`
`createSocket(org.apache.hc.core5.http.protocol.HttpContext context)`
`protected void`
`setup(org.apache.hc.core5.http.protocol.HttpContext context, String hostname)`
Setup calling execution environment for server TLS and client TLS based on information supplied in the `HttpContext`.
`protected void`
`setupClientTLS(org.apache.hc.core5.http.protocol.HttpContext context)`
Setup thread-local data for server TLS and client TLS based on information supplied in the `HttpContext`.
`protected void`
`setupServerTLS(org.apache.hc.core5.http.protocol.HttpContext context, String hostname)`
Setup thread-local data for server TLS.
`protected void`
`teardown(org.apache.hc.core5.http.protocol.HttpContext context)`
Schedule the deferred clearing of the `ThreadLocalX509CredentialContext` of the client TLS credential obtained from the `HttpContext`.

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface org.apache.hc.client5.http.socket.ConnectionSocketFactory

`connectSocket, createSocket`

### Methods inherited from interface org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory

`createLayeredSocket`

## Field Details

### SERVER_TLS_HANDLER

@Nonnull private static final ThreadLocalServerTLSHandler SERVER_TLS_HANDLER
Instance of `ThreadLocalClientTLSCredentialHandler` to use.

### CLIENT_TLS_HANDLER

@Nonnull private static final ThreadLocalClientTLSCredentialHandler CLIENT_TLS_HANDLER
Instance of `ThreadLocalClientTLSCredentialHandler` to use.

### log

@Nonnull private final org.slf4j.Logger log
Logger.

### wrappedFactory

@Nonnull private org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory wrappedFactory
The HttpClient socket factory instance wrapped by this implementation.

## Constructor Details

### SecurityEnhancedTLSSocketFactory

public SecurityEnhancedTLSSocketFactory(@Nonnull org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory factory)
Constructor.

Parameters:
  `factory` - the underlying HttpClient socket factory wrapped by this implementation.

## Method Details

### createSocket

public Socket createSocket(org.apache.hc.core5.http.protocol.HttpContext context) throws IOException

Specified by:
  `createSocket` in interface `org.apache.hc.client5.http.socket.ConnectionSocketFactory`
Throws:
  `IOException`

### connectSocket

public Socket connectSocket(org.apache.hc.core5.util.TimeValue connectTimeout, Socket sock, org.apache.hc.core5.http.HttpHost host, InetSocketAddress remoteAddress, InetSocketAddress localAddress, org.apache.hc.core5.http.protocol.HttpContext context) throws IOException

Specified by:
  `connectSocket` in interface `org.apache.hc.client5.http.socket.ConnectionSocketFactory`
Throws:
  `IOException`

### createLayeredSocket

public Socket createLayeredSocket(Socket socket, String target, int port, org.apache.hc.core5.http.protocol.HttpContext context) throws IOException

Specified by:
  `createLayeredSocket` in interface `org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory`
Throws:
  `IOException`

### checkAndEvaluateServerTLS

protected void checkAndEvaluateServerTLS(@Nonnull Socket socket) throws IOException
Check that the evaluation of the socket certificate using the data in `ThreadLocalX509TrustEngineContext` has been performed, if applicable, and if not, evaluate it.

This will usually be called only in the case of TLS session resumption, when the standard JSSE trust manager evaluation has not run.

Parameters:
  `socket` - the current socket being evaluated
Throws:
  `IOException` - if the certificate chain was not trusted by the supplied TrustEngine

### setup

protected void setup(@Nullable org.apache.hc.core5.http.protocol.HttpContext context, @Nonnull String hostname) throws SSLPeerUnverifiedException
Setup calling execution environment for server TLS and client TLS based on information supplied in the `HttpContext`.

Parameters:
  `context` - the HttpContext instance
  `hostname` - the hostname for the connection
Throws:
  `SSLPeerUnverifiedException` - if required data is not available from the context

### setupClientTLS

protected void setupClientTLS(@Nonnull org.apache.hc.core5.http.protocol.HttpContext context)
Setup thread-local data for server TLS and client TLS based on information supplied in the `HttpContext`.

Parameters:
  `context` - the HttpContext instance

### setupServerTLS

protected void setupServerTLS(@Nonnull org.apache.hc.core5.http.protocol.HttpContext context, @Nonnull String hostname)
Setup thread-local data for server TLS.

Parameters:
  `context` - the HttpContext instance
  `hostname` - the hostname for the connection

### teardown

protected void teardown(@Nullable org.apache.hc.core5.http.protocol.HttpContext context)
Schedule the deferred clearing of the `ThreadLocalX509CredentialContext` of the client TLS credential obtained from the `HttpContext`.

Parameters:
  `context` - the HttpContext instance