SSLSocket

See also:

• Socket
• SSLServerSocket
• SSLSocketFactory

SSLSocket

protected SSLSocket ()

Used only by subclasses. Constructs an uninitialized, unconnected TCP socket.

SSLSocket

protected SSLSocket (String host, 
                int port)

Used only by subclasses. Constructs a TCP connection to a named host at a specified port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

SSLSocket

protected SSLSocket (InetAddress address, 
                int port)

Used only by subclasses. Constructs a TCP connection to a server at a specified address and port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

SSLSocket

protected SSLSocket (String host, 
                int port, 
                InetAddress clientAddress, 
                int clientPort)

Used only by subclasses. Constructs an SSL connection to a named host at a specified port, binding the client side of the connection a given address and port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

SSLSocket

protected SSLSocket (InetAddress address, 
                int port, 
                InetAddress clientAddress, 
                int clientPort)

Used only by subclasses. Constructs an SSL connection to a server at a specified address and TCP port, binding the client side of the connection a given address and port. This acts as the SSL client.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

addHandshakeCompletedListener

public abstract void addHandshakeCompletedListener (HandshakeCompletedListener listener)

Registers an event listener to receive notifications that an SSL handshake has completed on this connection.

getApplicationProtocol

public String getApplicationProtocol ()

Returns the most recent application protocol value negotiated for this connection.

If supported by the underlying SSL/TLS implementation, application name negotiation mechanisms such as RFC 7301 , the Application-Layer Protocol Negotiation (ALPN), can negotiate application-level values between peers.

getEnableSessionCreation

public abstract boolean getEnableSessionCreation ()

Returns true if new SSL sessions may be established by this socket.

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites ()

Returns the names of the SSL cipher suites which are currently enabled for use on this connection. When an SSLSocket is first created, all enabled cipher suites support a minimum quality of service. Thus, in some environments this value might be empty.

Even if a suite has been enabled, it might never be used. (For example, the peer does not support it, the requisite certificates (and private keys) for the suite are not available, or an anonymous suite is enabled but authentication is required.

getEnabledProtocols

public abstract String[] getEnabledProtocols ()

Returns the names of the protocol versions which are currently enabled for use on this connection.

getHandshakeApplicationProtocol

public String getHandshakeApplicationProtocol ()

Returns the application protocol value negotiated on a SSL/TLS handshake currently in progress.

Like getHandshakeSession(), a connection may be in the middle of a handshake. The application protocol may or may not yet be available.

getHandshakeApplicationProtocolSelector

public BiFunction<SSLSocket, List<String>, String> getHandshakeApplicationProtocolSelector ()

Retrieves the callback function that selects an application protocol value during a SSL/TLS handshake. See setHandshakeApplicationProtocolSelector for the function's type parameters.

getHandshakeSession

public SSLSession getHandshakeSession ()

Returns the SSLSession being constructed during a SSL/TLS handshake.

TLS protocols may negotiate parameters that are needed when using an instance of this class, but before the SSLSession has been completely initialized and made available via getSession. For example, the list of valid signature algorithms may restrict the type of certificates that can used during TrustManager decisions, or the maximum TLS fragment packet sizes can be resized to better support the network environment.

This method provides early access to the SSLSession being constructed. Depending on how far the handshake has progressed, some data may not yet be available for use. For example, if a remote server will be sending a Certificate chain, but that chain has yet not been processed, the getPeerCertificates method of SSLSession will throw a SSLPeerUnverifiedException. Once that chain has been processed, getPeerCertificates will return the proper value.

Unlike getSession(), this method does not initiate the initial handshake and does not block until handshaking is complete.

getNeedClientAuth

public abstract boolean getNeedClientAuth ()

Returns true if the socket will require client authentication. This option is only useful to sockets in the server mode.

getSSLParameters

public SSLParameters getSSLParameters ()

Returns the SSLParameters in effect for this SSLSocket. The ciphersuites and protocols of the returned SSLParameters are always non-null.

getSession

public abstract SSLSession getSession ()

Returns the SSL Session in use by this connection. These can be long lived, and frequently correspond to an entire login session for some user. The session specifies a particular cipher suite which is being actively used by all connections in that session, as well as the identities of the session's client and server.

This method will initiate the initial handshake if necessary and then block until the handshake has been established.

If an error occurs during the initial handshake, this method returns an invalid session object which reports an invalid cipher suite of "SSL_NULL_WITH_NULL_NULL".

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites ()

Returns the names of the cipher suites which could be enabled for use on this connection. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites might be useful in specialized applications.

Applications should not blindly enable all supported cipher suites. The supported cipher suites can include signaling cipher suite values that can cause connection problems if enabled inappropriately.

The proper way to use this method is to either check if a specific cipher suite is supported via Arrays.asList(getSupportedCipherSuites()).contains(...) or to filter a desired list of cipher suites to only the supported ones via desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites())).

getSupportedProtocols

public abstract String[] getSupportedProtocols ()

Returns the names of the protocols which could be enabled for use on an SSL connection.

getUseClientMode

public abstract boolean getUseClientMode ()

Returns true if the socket is set to use client mode when handshaking.

getWantClientAuth

public abstract boolean getWantClientAuth ()

Returns true if the socket will request client authentication. This option is only useful for sockets in the server mode.

removeHandshakeCompletedListener

public abstract void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Removes a previously registered handshake completion listener.

setEnableSessionCreation

public abstract void setEnableSessionCreation (boolean flag)

Controls whether new SSL sessions may be established by this socket. If session creations are not allowed, and there are no existing sessions to resume, there will be no successful handshaking.

setEnabledCipherSuites

public abstract void setEnabledCipherSuites (String[] suites)

Sets the cipher suites enabled for use on this connection.

Each cipher suite in the suites parameter must have been listed by getSupportedCipherSuites(), or the method will fail. Following a successful call to this method, only suites listed in the suites parameter are enabled for use.

See getEnabledCipherSuites() for more information on why a specific ciphersuite may never be used on a connection.

setEnabledProtocols

public abstract void setEnabledProtocols (String[] protocols)

Sets the protocol versions enabled for use on this connection.

The protocols must have been listed by getSupportedProtocols() as being supported. Following a successful call to this method, only protocols listed in the protocols parameter are enabled for use.

Because of the way the protocol version is negotiated, connections will only be able to use a member of the lowest set of contiguous enabled protocol versions. For example, enabling TLSv1.2 and TLSv1 will result in connections only being able to use TLSv1.

setHandshakeApplicationProtocolSelector

public void setHandshakeApplicationProtocolSelector (BiFunction<SSLSocket, List<String>, String> selector)

Registers a callback function that selects an application protocol value for a SSL/TLS handshake. The function overrides any values supplied using SSLParameters.setApplicationProtocols and it supports the following type parameters:

SSLSocket

The function's first argument allows the current SSLSocket to be inspected, including the handshake session and configuration settings.

List<String>

The function's second argument lists the application protocol names advertised by the TLS peer.

String

The function's result is an application protocol name, or null to indicate that none of the advertised names are acceptable. If the return value is an empty String then application protocol indications will not be used. If the return value is null (no value chosen) or is a value that was not advertised by the peer, the underlying protocol will determine what action to take. (For example, ALPN will send a "no_application_protocol" alert and terminate the connection.)

serverSocket.setHandshakeApplicationProtocolSelector(
         (serverSocket, clientProtocols) -> {
             SSLSession session = serverSocket.getHandshakeSession();
             return chooseApplicationProtocol(
                 serverSocket,
                 clientProtocols,
                 session.getProtocol(),
                 session.getCipherSuite());
         });
 

setNeedClientAuth

public abstract void setNeedClientAuth (boolean need)

Configures the socket to require client authentication. This option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

• client authentication required
• client authentication requested
• no client authentication desired

Unlike setWantClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the connection will be dropped.

Calling this method overrides any previous setting made by this method or setWantClientAuth(boolean).

setSSLParameters

public void setSSLParameters (SSLParameters params)

Applies SSLParameters to this socket.

This means:

• If params.getCipherSuites() is non-null, setEnabledCipherSuites() is called with that value.
• If params.getProtocols() is non-null, setEnabledProtocols() is called with that value.
• If params.getNeedClientAuth() or params.getWantClientAuth() return true, setNeedClientAuth(true) and setWantClientAuth(true) are called, respectively; otherwise setWantClientAuth(false) is called.
• If params.getServerNames() is non-null, the socket will configure its server names with that value.
• If params.getSNIMatchers() is non-null, the socket will configure its SNI matchers with that value.

setUseClientMode

public abstract void setUseClientMode (boolean mode)

Configures the socket to use client (or server) mode when handshaking.

This method must be called before any handshaking occurs. Once handshaking has begun, the mode can not be reset for the life of this socket.

Servers normally authenticate themselves, and clients are not required to do so.

setWantClientAuth

public abstract void setWantClientAuth (boolean want)

Configures the socket to request client authentication. This option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

• client authentication required
• client authentication requested
• no client authentication desired

Unlike setNeedClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.

Calling this method overrides any previous setting made by this method or setNeedClientAuth(boolean).

startHandshake

public abstract void startHandshake ()

Starts an SSL handshake on this connection. Common reasons include a need to use new encryption keys, to change cipher suites, or to initiate a new session. To force complete reauthentication, the current session could be invalidated before starting this handshake.

If data has already been sent on the connection, it continues to flow during this handshake. When the handshake completes, this will be signaled with an event. This method is synchronous for the initial handshake on a connection and returns when the negotiated handshake is complete. Some protocols may not support multiple handshakes on an existing socket and may throw an IOException.

toString

public String toString ()

Converts this socket to a String.