Apache HttpClient 4.5.14 · org.apache.http.conn.ssl.SSLConnectionSocketFactory

Layered socket factory for TLS/SSL connections.

SSLSocketFactory can be used to validate the identity of the HTTPS server against a list of trusted certificates and to authenticate to the HTTPS server using a private key.

SSLSocketFactory will enable server authentication when supplied with a trust-store file containing one or several trusted certificates. The client secure socket will reject the connection during the SSL session handshake if the target HTTPS server attempts to authenticate itself with a non-trusted certificate.

Use JDK keytool utility to import a trusted certificate and generate a trust-store file:

    keytool -import -alias "my server cert" -file server.crt -keystore my.truststore

In special cases the standard trust verification process can be bypassed by using a custom org.apache.http.conn.ssl.TrustStrategy. This interface is primarily intended for allowing self-signed certificates to be accepted as trusted without having to add them to the trust-store file.

SSLSocketFactory will enable client authentication when supplied with a key-store file containing a private key/public certificate pair. The client secure socket will use the private key to authenticate itself to the target HTTPS server during the SSL session handshake if requested to do so by the server. The target HTTPS server will in its turn verify the certificate presented by the client in order to establish client's authenticity.

Use the following sequence of actions to generate a key-store file

Use JDK keytool utility to generate a new key
```
keytool -genkey -v -alias "my client key" -validity 365 -keystore my.keystore
```
For simplicity use the same password for the key as that of the key-store

Issue a certificate signing request (CSR)

keytool -certreq -alias "my client key" -file mycertreq.csr -keystore my.keystore

Send the certificate request to the trusted Certificate Authority for signature. One may choose to act as her own CA and sign the certificate request using a PKI tool, such as OpenSSL.

Import the trusted CA root certificate

keytool -import -alias "my trusted ca" -file caroot.crt -keystore my.keystore

Import the PKCS#7 file containing the complete certificate chain

keytool -import -alias "my client key" -file mycert.p7 -keystore my.keystore

Verify the content of the resultant keystore file
```
keytool -list -v -keystore my.keystore
```

Field Summary

Modifier and Type	Field and Description
public static final X509HostnameVerifier	ALLOW_ALL_HOSTNAME_VERIFIER Deprecated Use `AllowAllHostnameVerifier#INSTANCE`.
public static final X509HostnameVerifier	BROWSER_COMPATIBLE_HOSTNAME_VERIFIER Deprecated Use `BrowserCompatHostnameVerifier#INSTANCE`.
private final HostnameVerifier	hostnameVerifier
private final Log	log
private final SSLSocketFactory	socketfactory
public static final String	SSL
public static final String	SSLV2
public static final X509HostnameVerifier	STRICT_HOSTNAME_VERIFIER Deprecated Use `StrictHostnameVerifier#INSTANCE`.
private final String[]	supportedCipherSuites
private final String[]	supportedProtocols
public static final String	TLS
private static final List<Pattern>	WEAK_CIPHER_SUITE_PATTERNS
private static final String	WEAK_CIPHERS
private static final String	WEAK_KEY_EXCHANGES

Constructor Summary

Access	Constructor and Description
public	SSLConnectionSocketFactory(final SSLContext sslContext)
public	SSLConnectionSocketFactory(final SSLContext sslContext, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLContext, javax.net.ssl.HostnameVerifier)`
public	SSLConnectionSocketFactory(final SSLContext sslContext, final String[] supportedProtocols, final String[] supportedCipherSuites, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLContext, String[], String[], javax.net.ssl.HostnameVerifier)`
public	SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLSocketFactory, javax.net.ssl.HostnameVerifier)`
public	SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final String[] supportedProtocols, final String[] supportedCipherSuites, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLSocketFactory, String[], String[], javax.net.ssl.HostnameVerifier)`
public	SSLConnectionSocketFactory(final SSLContext sslContext, final HostnameVerifier hostnameVerifier)
public	SSLConnectionSocketFactory(final SSLContext sslContext, final String[] supportedProtocols, final String[] supportedCipherSuites, final HostnameVerifier hostnameVerifier)
public	SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final HostnameVerifier hostnameVerifier)
public	SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final String[] supportedProtocols, final String[] supportedCipherSuites, final HostnameVerifier hostnameVerifier)

Method Summary

Modifier and Type	Method and Description
public Socket	connectSocket(final int connect timeout. connectTimeout, final Socket the socket to connect, as obtained from `createSocket(HttpContext)`. `null` indicates that a new socket should be created and connected. socket, final HttpHost target host as specified by the caller (end user). host, final InetSocketAddress the resolved remote address to connect to. remoteAddress, final InetSocketAddress the local address to bind the socket to, or `null` for any. localAddress, final HttpContext the actual HTTP context. context) Implements org.apache.http.conn.socket.ConnectionSocketFactory.connectSocket. Connects the socket to the target host with the given resolved remote address.
public Socket	createLayeredSocket(final Socket the existing socket socket, final String the name of the target host. target, final int the port to connect to on the target host. port, final HttpContext the actual HTTP context. context) Implements org.apache.http.conn.socket.LayeredConnectionSocketFactory.createLayeredSocket. Returns a socket connected to the given host that is layered over an existing socket.
public Socket	createSocket(final HttpContext context) Implements org.apache.http.conn.socket.ConnectionSocketFactory.createSocket. Creates new, unconnected socket.
public static HostnameVerifier	getDefaultHostnameVerifier()
public static SSLConnectionSocketFactory	Returns: default SSL socket factory getSocketFactory() Obtains default SSL socket factory with an SSL context based on the standard JSSE trust material (`cacerts` file in the security properties directory).
public static SSLConnectionSocketFactory	Returns: default system SSL socket factory getSystemSocketFactory() Obtains default SSL socket factory with an SSL context based on system properties as described in Java™ Secure Socket Extension (JSSE) Reference Guide.
pack-priv static boolean	isWeakCipherSuite(final String cipherSuite)
protected void	prepareSocket(final SSLSocket socket) Performs any custom initialization for a newly created SSLSocket (before the SSL handshake happens).
private static String[]	split(final String s)
private void	verifyHostname(final SSLSocket sslsock, final String hostname)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

ALLOW_ALL_HOSTNAME_VERIFIER	back to summary
public static final X509HostnameVerifier ALLOW_ALL_HOSTNAME_VERIFIER Deprecated Use `AllowAllHostnameVerifier#INSTANCE`. Annotations @Deprecated

BROWSER_COMPATIBLE_HOSTNAME_VERIFIER	back to summary
public static final X509HostnameVerifier BROWSER_COMPATIBLE_HOSTNAME_VERIFIER Deprecated Use `BrowserCompatHostnameVerifier#INSTANCE`. Annotations @Deprecated

hostnameVerifier	back to summary
private final HostnameVerifier hostnameVerifier

log	back to summary
private final Log log

socketfactory	back to summary
private final SSLSocketFactory socketfactory

SSL	back to summary
public static final String SSL

SSLV2	back to summary
public static final String SSLV2

STRICT_HOSTNAME_VERIFIER	back to summary
public static final X509HostnameVerifier STRICT_HOSTNAME_VERIFIER Deprecated Use `StrictHostnameVerifier#INSTANCE`. Annotations @Deprecated

supportedCipherSuites	back to summary
private final String[] supportedCipherSuites

supportedProtocols	back to summary
private final String[] supportedProtocols

TLS	back to summary
public static final String TLS

WEAK_CIPHER_SUITE_PATTERNS	back to summary
private static final List<Pattern> WEAK_CIPHER_SUITE_PATTERNS

WEAK_CIPHERS	back to summary
private static final String WEAK_CIPHERS

WEAK_KEY_EXCHANGES	back to summary
private static final String WEAK_KEY_EXCHANGES

Constructor Detail

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLContext sslContext)

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLContext sslContext, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLContext, javax.net.ssl.HostnameVerifier)` Annotations @Deprecated

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLContext sslContext, final String[] supportedProtocols, final String[] supportedCipherSuites, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLContext, String[], String[], javax.net.ssl.HostnameVerifier)` Annotations @Deprecated

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLSocketFactory, javax.net.ssl.HostnameVerifier)` Annotations @Deprecated

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final String[] supportedProtocols, final String[] supportedCipherSuites, final X509HostnameVerifier hostnameVerifier) Deprecated (4.4) Use `SSLConnectionSocketFactory(javax.net.ssl.SSLSocketFactory, String[], String[], javax.net.ssl.HostnameVerifier)` Annotations @Deprecated

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLContext sslContext, final HostnameVerifier hostnameVerifier) Since 4.4

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLContext sslContext, final String[] supportedProtocols, final String[] supportedCipherSuites, final HostnameVerifier hostnameVerifier) Since 4.4

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final HostnameVerifier hostnameVerifier) Since 4.4

SSLConnectionSocketFactory	back to summary
public SSLConnectionSocketFactory(final SSLSocketFactory socketfactory, final String[] supportedProtocols, final String[] supportedCipherSuites, final HostnameVerifier hostnameVerifier) Since 4.4

Method Detail

connectSocket back to summary

connectSocket	back to summary
public Socket connectSocket(final int connectTimeout, final Socket socket, final HttpHost host, final InetSocketAddress remoteAddress, final InetSocketAddress localAddress, final HttpContext context) throws IOException Implements org.apache.http.conn.socket.ConnectionSocketFactory.connectSocket. Doc from org.apache.http.conn.socket.ConnectionSocketFactory.connectSocket. Connects the socket to the target host with the given resolved remote address. Parameters connectTimeout:int connect timeout. socket:Socket the socket to connect, as obtained from `createSocket(HttpContext)`. `null` indicates that a new socket should be created and connected. host:HttpHost target host as specified by the caller (end user). remoteAddress:InetSocketAddress the resolved remote address to connect to. localAddress:InetSocketAddress the local address to bind the socket to, or `null` for any. context:HttpContext the actual HTTP context. Returns:Socket the connected socket. The returned object may be different from the `sock` argument if this factory supports a layered protocol. Annotations @Override Exceptions IOException: if an I/O error occurs

public Socket connectSocket(final int connectTimeout, final Socket socket, final HttpHost host, final InetSocketAddress remoteAddress, final InetSocketAddress localAddress, final HttpContext context) throws IOException

Implements org.apache.http.conn.socket.ConnectionSocketFactory.connectSocket.

Doc from org.apache.http.conn.socket.ConnectionSocketFactory.connectSocket.

Connects the socket to the target host with the given resolved remote address.

Parameters

connectTimeout:int: connect timeout.
socket:Socket: the socket to connect, as obtained from createSocket(HttpContext). null indicates that a new socket should be created and connected.
host:HttpHost: target host as specified by the caller (end user).
remoteAddress:InetSocketAddress: the resolved remote address to connect to.
localAddress:InetSocketAddress: the local address to bind the socket to, or null for any.
context:HttpContext: the actual HTTP context.

Returns:Socket

the connected socket. The returned object may be different from the sock argument if this factory supports a layered protocol.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs

createLayeredSocket	back to summary
public Socket createLayeredSocket(final Socket socket, final String target, final int port, final HttpContext context) throws IOException Implements org.apache.http.conn.socket.LayeredConnectionSocketFactory.createLayeredSocket. Doc from org.apache.http.conn.socket.LayeredConnectionSocketFactory.createLayeredSocket. Returns a socket connected to the given host that is layered over an existing socket. Used primarily for creating secure sockets through proxies. Parameters socket:Socket the existing socket target:String the name of the target host. port:int the port to connect to on the target host. context:HttpContext the actual HTTP context. Returns:Socket Socket a new socket Annotations @Override Exceptions IOException: if an I/O error occurs while creating the socket

createLayeredSocket

back to summary

public Socket createLayeredSocket(final Socket socket, final String target, final int port, final HttpContext context) throws IOException

Implements org.apache.http.conn.socket.LayeredConnectionSocketFactory.createLayeredSocket.

Doc from org.apache.http.conn.socket.LayeredConnectionSocketFactory.createLayeredSocket.

Returns a socket connected to the given host that is layered over an existing socket. Used primarily for creating secure sockets through proxies.

Parameters

socket:Socket: the existing socket
target:String: the name of the target host.
port:int: the port to connect to on the target host.
context:HttpContext: the actual HTTP context.

Returns:Socket

Socket a new socket

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs while creating the socket

createSocket back to summary

createSocket	back to summary
public Socket createSocket(final HttpContext context) throws IOException Implements org.apache.http.conn.socket.ConnectionSocketFactory.createSocket. Doc from org.apache.http.conn.socket.ConnectionSocketFactory.createSocket. Creates new, unconnected socket. The socket should subsequently be passed to `connectSocket` method. Returns:Socket a new socket Annotations @Override Exceptions IOException: if an I/O error occurs while creating the socket

public Socket createSocket(final HttpContext context) throws IOException

Implements org.apache.http.conn.socket.ConnectionSocketFactory.createSocket.

Doc from org.apache.http.conn.socket.ConnectionSocketFactory.createSocket.

Creates new, unconnected socket. The socket should subsequently be passed to connectSocket method.

Returns:Socket

a new socket

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs while creating the socket

getDefaultHostnameVerifier	back to summary
public static HostnameVerifier getDefaultHostnameVerifier() Since 4.4

getSocketFactory back to summary

getSocketFactory	back to summary
public static SSLConnectionSocketFactory getSocketFactory() throws SSLInitializationException Obtains default SSL socket factory with an SSL context based on the standard JSSE trust material (`cacerts` file in the security properties directory). System properties are not taken into consideration. Returns:SSLConnectionSocketFactory default SSL socket factory

public static SSLConnectionSocketFactory getSocketFactory() throws SSLInitializationException

Obtains default SSL socket factory with an SSL context based on the standard JSSE trust material (cacerts file in the security properties directory). System properties are not taken into consideration.

Returns:SSLConnectionSocketFactory: default SSL socket factory

getSystemSocketFactory	back to summary
public static SSLConnectionSocketFactory getSystemSocketFactory() throws SSLInitializationException Obtains default SSL socket factory with an SSL context based on system properties as described in Java™ Secure Socket Extension (JSSE) Reference Guide. Returns:SSLConnectionSocketFactory default system SSL socket factory

getSystemSocketFactory

back to summary

public static SSLConnectionSocketFactory getSystemSocketFactory() throws SSLInitializationException

Obtains default SSL socket factory with an SSL context based on system properties as described in Java™ Secure Socket Extension (JSSE) Reference Guide.

Returns:SSLConnectionSocketFactory: default system SSL socket factory

isWeakCipherSuite	back to summary
pack-priv static boolean isWeakCipherSuite(final String cipherSuite)

prepareSocket back to summary

prepareSocket	back to summary
protected void prepareSocket(final SSLSocket socket) 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 `javax.net.ssl.SSLSocket#setEnabledCipherSuites(String[])`. Exceptions IOException: may be thrown if overridden

protected void prepareSocket(final SSLSocket socket) 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 javax.net.ssl.SSLSocket#setEnabledCipherSuites(String[]).

Exceptions

IOException:: may be thrown if overridden

split	back to summary
private static String[] split(final String s)

verifyHostname	back to summary
private void verifyHostname(final SSLSocket sslsock, final String hostname) throws IOException

public Class SSLConnectionSocketFactory

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail