org.apache.hc.client5.http.ssl

## Class SSLConnectionSocketFactory

- java.lang.Object
- - org.apache.hc.client5.http.ssl.SSLConnectionSocketFactory

- All Implemented Interfaces:
    ConnectionSocketFactory, LayeredConnectionSocketFactory

      @Contract(threading=STATELESS)
      public class SSLConnectionSocketFactory
      extends Object
      implements LayeredConnectionSocketFactory

  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.

  Since:
    4.3

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SSLConnectionSocketFactory(SSLContext sslContext)`
    `SSLConnectionSocketFactory(SSLContext sslContext, HostnameVerifier hostnameVerifier)`
    `SSLConnectionSocketFactory(SSLContext sslContext, String[] supportedProtocols, String[] supportedCipherSuites, HostnameVerifier hostnameVerifier)`
    `SSLConnectionSocketFactory(SSLSocketFactory socketFactory, HostnameVerifier hostnameVerifier)`
    `SSLConnectionSocketFactory(SSLSocketFactory socketFactory, String[] supportedProtocols, String[] supportedCipherSuites, HostnameVerifier hostnameVerifier)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Socket` | `connectSocket(Socket socket, org.apache.hc.core5.http.HttpHost host, InetSocketAddress remoteAddress, InetSocketAddress localAddress, org.apache.hc.core5.util.Timeout connectTimeout, Object attachment, org.apache.hc.core5.http.protocol.HttpContext context)` Connects the socket to the target host with the given resolved remote address.
    `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)` Connects the socket to the target host with the given resolved remote address.
    `Socket` | `createLayeredSocket(Socket socket, String target, int port, org.apache.hc.core5.http.protocol.HttpContext context)` Returns a socket connected to the given host that is layered over an existing socket.
    `Socket` | `createLayeredSocket(Socket socket, String target, int port, Object attachment, org.apache.hc.core5.http.protocol.HttpContext context)` Returns a socket connected to the given host that is layered over an existing socket.
    `Socket` | `createSocket(org.apache.hc.core5.http.protocol.HttpContext context)` Creates new, unconnected socket.
    `static SSLConnectionSocketFactory` | `getSocketFactory()` Obtains default SSL socket factory with an SSL context based on the standard JSSE trust material (`cacerts` file in the security properties directory).
    `static SSLConnectionSocketFactory` | `getSystemSocketFactory()` Obtains default SSL socket factory with an SSL context based on system properties as described in Java™ Secure Socket Extension (JSSE) Reference Guide.
    `protected void` | `prepareSocket(SSLSocket socket)` Deprecated. Use `prepareSocket(SSLSocket, HttpContext)`
    `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` | `verifySession(String hostname, SSLSession sslSession)`

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

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

- - ### Constructor Detail

    - #### SSLConnectionSocketFactory

          public SSLConnectionSocketFactory(SSLContext sslContext)

    - #### SSLConnectionSocketFactory

          public SSLConnectionSocketFactory(SSLContext sslContext,
                                            HostnameVerifier hostnameVerifier)

      Since:
        4.4

    - #### SSLConnectionSocketFactory

          public SSLConnectionSocketFactory(SSLContext sslContext,
                                            String[] supportedProtocols,
                                            String[] supportedCipherSuites,
                                            HostnameVerifier hostnameVerifier)

      Since:
        4.4

    - #### SSLConnectionSocketFactory

          public SSLConnectionSocketFactory(SSLSocketFactory socketFactory,
                                            HostnameVerifier hostnameVerifier)

      Since:
        4.4

    - #### SSLConnectionSocketFactory

          public SSLConnectionSocketFactory(SSLSocketFactory socketFactory,
                                            String[] supportedProtocols,
                                            String[] supportedCipherSuites,
                                            HostnameVerifier hostnameVerifier)

      Since:
        4.4

  - ### Method Detail

    - #### getSocketFactory

          public static SSLConnectionSocketFactory getSocketFactory()
                                                             throws org.apache.hc.core5.ssl.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:
        default SSL socket factory
      Throws:
        `org.apache.hc.core5.ssl.SSLInitializationException`

    - #### getSystemSocketFactory

          public static SSLConnectionSocketFactory getSystemSocketFactory()
                                                                   throws org.apache.hc.core5.ssl.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:
        default system SSL socket factory
      Throws:
        `org.apache.hc.core5.ssl.SSLInitializationException`

    - #### prepareSocket

          @Deprecated
          protected void prepareSocket(SSLSocket socket)
                                            throws IOException

      Deprecated. Use `prepareSocket(SSLSocket, HttpContext)`
      Throws:
        `IOException`

    - #### prepareSocket

          protected void prepareSocket(SSLSocket socket,
                                       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[])`.
      Throws:
        `IOException` - may be thrown if overridden

    - #### createSocket

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

      Description copied from interface: `ConnectionSocketFactory`
      Creates new, unconnected socket. The socket should subsequently be passed to `connectSocket` method.
      Specified by:
        `createSocket` in interface `ConnectionSocketFactory`
      Returns:
        a new socket
      Throws:
        `IOException` - if an I/O error occurs while creating the socket

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

      Description copied from interface: `ConnectionSocketFactory`
      Connects the socket to the target host with the given resolved remote address.
      Specified by:
        `connectSocket` in interface `ConnectionSocketFactory`
      Parameters:
        `connectTimeout` - connect timeout.
        `socket` - the socket to connect, as obtained from `ConnectionSocketFactory.createSocket(HttpContext)`. `null` indicates that a new socket should be created and connected.
        `host` - target host as specified by the caller (end user).
        `remoteAddress` - the resolved remote address to connect to.
        `localAddress` - the local address to bind the socket to, or `null` for any.
        `context` - the actual HTTP context.
      Returns:
        the connected socket. The returned object may be different from the `sock` argument if this factory supports a layered protocol.
      Throws:
        `IOException` - if an I/O error occurs

    - #### connectSocket

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

      Description copied from interface: `ConnectionSocketFactory`
      Connects the socket to the target host with the given resolved remote address.
      Specified by:
        `connectSocket` in interface `ConnectionSocketFactory`
      Parameters:
        `socket` - the socket to connect, as obtained from `ConnectionSocketFactory.createSocket(HttpContext)`. `null` indicates that a new socket should be created and connected.
        `host` - target host as specified by the caller (end user).
        `remoteAddress` - the resolved remote address to connect to.
        `localAddress` - the local address to bind the socket to, or `null` for any.
        `connectTimeout` - connect timeout.
        `attachment` - connect request attachment.
        `context` - the actual HTTP context.
      Returns:
        the connected socket. The returned object may be different from the `sock` argument if this factory supports a layered protocol.
      Throws:
        `IOException` - if an I/O error occurs

    - #### createLayeredSocket

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

      Description copied from interface: `LayeredConnectionSocketFactory`
      Returns a socket connected to the given host that is layered over an existing socket. Used primarily for creating secure sockets through proxies.
      Specified by:
        `createLayeredSocket` in interface `LayeredConnectionSocketFactory`
      Parameters:
        `socket` - the existing socket
        `target` - the name of the target host.
        `port` - the port to connect to on the target host.
        `context` - the actual HTTP context.
      Returns:
        Socket a new socket
      Throws:
        `IOException` - if an I/O error occurs while creating the socket

    - #### createLayeredSocket

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

      Description copied from interface: `LayeredConnectionSocketFactory`
      Returns a socket connected to the given host that is layered over an existing socket. Used primarily for creating secure sockets through proxies.
      Specified by:
        `createLayeredSocket` in interface `LayeredConnectionSocketFactory`
      Parameters:
        `socket` - the existing socket
        `target` - the name of the target host.
        `port` - the port to connect to on the target host.
        `attachment` - connect request attachment.
        `context` - the actual HTTP context.
      Returns:
        Socket a new socket
      Throws:
        `IOException` - if an I/O error occurs while creating the socket

    - #### verifySession

          protected void verifySession(String hostname,
                                       SSLSession sslSession)
                                throws SSLException

      Throws:
        `SSLException`

Copyright © 1999–2021 The Apache Software Foundation. All rights reserved.