Package net.shibboleth.shared.httpclient

# Class TLSSocketFactory

java.lang.Object
net.shibboleth.shared.httpclient.TLSSocketFactory

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

@ThreadSafe public class TLSSocketFactory extends Object implements org.apache.hc.client5.http.socket.LayeredConnectionSocketFactory
An implementation of HttpClient `LayeredConnectionSocketFactory` that is a factory for TLS sockets.

This class is functionally modeled on `SSLConnectionSocketFactory`, but provides better support for subclassing, as well as specific additional features:

- Factory hostname verifier defaults to `DefaultHostnameVerifier` without a configured `PublicSuffixMatcher`.
- Per-request specification of enabled TLS protocols and cipher suites via `HttpContext` attributes.
- Per-request specification of hostname verifier via `HttpContext` attribute.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final HostnameVerifier`
`ALLOW_ALL_HOSTNAME_VERIFIER`
Hostname verifier which passes all hostnames.
`static final String`
`CONTEXT_KEY_HOSTNAME_VERIFIER`
HttpContext key for an instance of `HostnameVerifier`.
`static final String`
`CONTEXT_KEY_TLS_CIPHER_SUITES`
HttpContext key for a a list of TLS cipher suites to enable on the socket.
`static final String`
`CONTEXT_KEY_TLS_PROTOCOLS`
HttpContext key for a a list of TLS protocols to enable on the socket.
`static final String[]`
`DEFAULT_ENABLED_PROTOCOLS`
Default enabled protocols.
`private final HostnameVerifier`
`hostnameVerifier`
Hostname verifier.
`private final org.slf4j.Logger`
`log`
Logger.
`private final SSLSocketFactory`
`socketfactory`
Socket factory.
`static final String`
`SSL`
Protocol: SSL.
`static final String`
`SSLV2`
Protocol: SSLv2.
`static final HostnameVerifier`
`STRICT_HOSTNAME_VERIFIER`
Hostname verifier which implements a strict policy.
`private final String[]`
`supportedCipherSuites`
Factory-wide supported cipher suites.
`private final String[]`
`supportedProtocols`
Factory-wide supported protocols.
`static final String`
`TLS`
Protocol: TLS.

## Constructor Summary

Constructors
Constructor
Description
`TLSSocketFactory(SSLContext sslContext)`
Constructor.
`TLSSocketFactory(SSLContext sslContext, String[] protocols, String[] cipherSuites, HostnameVerifier verifier)`
Constructor.
`TLSSocketFactory(SSLContext sslContext, HostnameVerifier verifier)`
Constructor.
`TLSSocketFactory(SSLSocketFactory factory, String[] protocols, String[] cipherSuites, HostnameVerifier verifier)`
Constructor.
`TLSSocketFactory(SSLSocketFactory factory, HostnameVerifier verifier)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`Socket`
`connectSocket(org.apache.hc.core5.util.TimeValue connectTimeout, Socket socket, 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 HostnameVerifier`
`getHostnameVerifier()`
Get the configured hostname verifier.
`protected String[]`
`getListAttribute(org.apache.hc.core5.http.protocol.HttpContext context, String contextKey)`
Get a normalized String array from a context attribute holding a `List`<`String`>.
`protected SSLSocketFactory`
`getSocketfactory()`
Get the JSSE socket factory instance.
`protected String[]`
`getSupportedCipherSuites()`
Get the configured factory-wide supported cipher suites.
`protected String[]`
`getSupportedProtocols()`
Get the configured factory-wide supported protocols.
`private void`
`logSocketInfo(SSLSocket socket)`
Log various diagnostic information from the `SSLSocket` and `SSLSession`.
`protected void`
`prepareSocket(SSLSocket socket, org.apache.hc.core5.http.protocol.HttpContext context)`
Performs any custom initialization for a newly created SSLSocket (before the SSL handshake happens).
`protected void`
`verifyHostname(SSLSocket sslsock, String hostname, org.apache.hc.core5.http.protocol.HttpContext context)`
Verify the peer's socket hostname against the supplied expected name.

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

### CONTEXT_KEY_TLS_PROTOCOLS

@Nonnull @NotEmpty public static final String CONTEXT_KEY_TLS_PROTOCOLS
HttpContext key for a a list of TLS protocols to enable on the socket. Must be an instance of `List`<`String`>.

See Also:
  - Constant Field Values

### CONTEXT_KEY_TLS_CIPHER_SUITES

@Nonnull @NotEmpty public static final String CONTEXT_KEY_TLS_CIPHER_SUITES
HttpContext key for a a list of TLS cipher suites to enable on the socket. Must be an instance of `List`<`String`>.

See Also:
  - Constant Field Values

### CONTEXT_KEY_HOSTNAME_VERIFIER

@Nonnull @NotEmpty public static final String CONTEXT_KEY_HOSTNAME_VERIFIER
HttpContext key for an instance of `HostnameVerifier`.

See Also:
  - Constant Field Values

### TLS

@Nonnull @NotEmpty public static final String TLS
Protocol: TLS.

See Also:
  - Constant Field Values

### SSL

@Nonnull @NotEmpty public static final String SSL
Protocol: SSL.

See Also:
  - Constant Field Values

### SSLV2

@Nonnull @NotEmpty public static final String SSLV2
Protocol: SSLv2.

See Also:
  - Constant Field Values

### ALLOW_ALL_HOSTNAME_VERIFIER

@Nonnull public static final HostnameVerifier ALLOW_ALL_HOSTNAME_VERIFIER
Hostname verifier which passes all hostnames.

### STRICT_HOSTNAME_VERIFIER

@Nonnull public static final HostnameVerifier STRICT_HOSTNAME_VERIFIER
Hostname verifier which implements a strict policy.

### DEFAULT_ENABLED_PROTOCOLS

@Nonnull public static final String[] DEFAULT_ENABLED_PROTOCOLS
Default enabled protocols.

### log

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

### socketfactory

@Nonnull private final SSLSocketFactory socketfactory
Socket factory.

### hostnameVerifier

@Nonnull private final HostnameVerifier hostnameVerifier
Hostname verifier.

### supportedProtocols

@Nullable private final String[] supportedProtocols
Factory-wide supported protocols.

### supportedCipherSuites

@Nullable private final String[] supportedCipherSuites
Factory-wide supported cipher suites.

## Constructor Details

### TLSSocketFactory

public TLSSocketFactory(@Nonnull SSLContext sslContext)
Constructor.

Parameters:
  `sslContext` - the effective SSLContext instance

### TLSSocketFactory

public TLSSocketFactory(@Nonnull SSLContext sslContext, @Nullable HostnameVerifier verifier)
Constructor.

Parameters:
  `sslContext` - the effective SSLContext instance
  `verifier` - the effective hostname verifier

### TLSSocketFactory

public TLSSocketFactory(@Nonnull SSLContext sslContext, @Nullable String[] protocols, @Nullable String[] cipherSuites, @Nullable HostnameVerifier verifier)
Constructor.

Parameters:
  `sslContext` - the effective SSLContext instance
  `protocols` - the factory-wide enabled TLS protocols
  `cipherSuites` - the factory-wide enabled TLS cipher suites
  `verifier` - the effective hostname verifier

### TLSSocketFactory

public TLSSocketFactory(@Nonnull SSLSocketFactory factory, @Nullable HostnameVerifier verifier)
Constructor.

Parameters:
  `factory` - the effective SSL socket factory
  `verifier` - the effective hostname verifier

### TLSSocketFactory

public TLSSocketFactory(@Nonnull SSLSocketFactory factory, @Nullable String[] protocols, @Nullable String[] cipherSuites, @Nullable HostnameVerifier verifier)
Constructor.

Parameters:
  `factory` - the effective SSL socket factory
  `protocols` - the factory-wide enabled TLS protocols
  `cipherSuites` - the factory-wide enabled TLS cipher suites
  `verifier` - the effective hostname verifier

## Method Details

### getSocketfactory

@Nonnull protected SSLSocketFactory getSocketfactory()
Get the JSSE socket factory instance.

Returns:
  the socket factory

### getHostnameVerifier

@Nonnull protected HostnameVerifier getHostnameVerifier()
Get the configured hostname verifier.

Returns:
  the hostname verifier

### getSupportedProtocols

@Nullable protected String[] getSupportedProtocols()
Get the configured factory-wide supported protocols.

Returns:
  the configured protocols

### getSupportedCipherSuites

@Nullable protected String[] getSupportedCipherSuites()
Get the configured factory-wide supported cipher suites.

Returns:
  the configured cipher suites

### prepareSocket

protected void prepareSocket(@Nonnull SSLSocket socket, @Nullable org.apache.hc.core5.http.protocol.HttpContext context) throws IOException
Performs any custom initialization for a newly created SSLSocket (before the SSL handshake happens). The default implementation is a no-op, but could be overridden to, e.g., call `SSLSocket.setEnabledCipherSuites(String[])`.

Parameters:
  `socket` - the SSL socket instance being prepared
  `context` - the current HttpContext instance
Throws:
  `IOException` - if there is an error customizing the socket

### createSocket

@Nonnull public Socket createSocket(@Nullable 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 socket, 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`

### logSocketInfo

private void logSocketInfo(@Nonnull SSLSocket socket)
Log various diagnostic information from the `SSLSocket` and `SSLSession`.

Parameters:
  `socket` - the SSLSocket instance

### getListAttribute

@Nullable protected String[] getListAttribute(@Nullable org.apache.hc.core5.http.protocol.HttpContext context, @Nonnull String contextKey)
Get a normalized String array from a context attribute holding a `List`<`String`>.

Parameters:
  `context` - the current HttpContext
  `contextKey` - the attribute context key
Returns:
  a String array, or null

### verifyHostname

protected void verifyHostname(@Nonnull SSLSocket sslsock, @Nonnull String hostname, @Nullable org.apache.hc.core5.http.protocol.HttpContext context) throws IOException
Verify the peer's socket hostname against the supplied expected name.

Parameters:
  `sslsock` - the SSL socket being prepared
  `hostname` - the expected hostname
  `context` - the current HttpContext instance
Throws:
  `IOException` - if peer failed hostname verification, or if there was an error during verification