public abstract class

SSLSocket

extends Socket
java.lang.Object
   ↳ java.net.Socket
     ↳ javax.net.ssl.SSLSocket

Class Overview

The extension of Socket providing secure protocols like SSL (Secure Socket Layer") or TLS (Transport Layer Security).

Summary

Protected Constructors
SSLSocket()
Only to be used by subclasses.
SSLSocket(String host, int port)
Only to be used by subclasses.
SSLSocket(InetAddress address, int port)
Only to be used by subclasses.
SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
Only to be used by subclasses.
SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
Only to be used by subclasses.
Public Methods
abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers the specified listener to receive notification on completion of a handshake on this connection.
abstract boolean getEnableSessionCreation()
Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract String[] getEnabledCipherSuites()
Returns the names of the enabled cipher suites.
abstract String[] getEnabledProtocols()
Returns the names of the enabled protocols.
abstract boolean getNeedClientAuth()
Returns true if the server socket should require client authentication.
SSLParameters getSSLParameters()
Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
abstract SSLSession getSession()
Returns the SSLSession for this connection.
abstract String[] getSupportedCipherSuites()
Returns the names of the supported cipher suites.
abstract String[] getSupportedProtocols()
Returns the names of the supported protocols.
abstract boolean getUseClientMode()
Returns true if this connection will act in client mode when handshaking.
abstract boolean getWantClientAuth()
Returns true if the server should request client authentication.
abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes the specified handshake completion listener.
abstract void setEnableSessionCreation(boolean flag)
Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract void setEnabledCipherSuites(String[] suites)
Sets the names of the cipher suites to be enabled.
abstract void setEnabledProtocols(String[] protocols)
Sets the names of the protocols to be enabled.
abstract void setNeedClientAuth(boolean need)
Sets whether the server should require client authentication.
void setSSLParameters(SSLParameters p)
Sets various SSL handshake parameters based on the SSLParameter argument.
abstract void setUseClientMode(boolean mode)
Sets whether this connection should act in client mode when handshaking.
abstract void setWantClientAuth(boolean want)
Sets whether the server should request client authentication.
void shutdownInput()
Unsupported for SSL because reading from an SSL socket may require writing to the network.
void shutdownOutput()
Unsupported for SSL because writing to an SSL socket may require reading from the network.
abstract void startHandshake()
Starts a new SSL handshake on this connection.
[Expand]
Inherited Methods
From class java.net.Socket
From class java.lang.Object

Protected Constructors

protected SSLSocket ()

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket.

protected SSLSocket (String host, int port)

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port.

Parameters
host the host name to connect to.
port the port number to connect to.
Throws
IOException if creating the socket fails.
UnknownHostException if the specified host is not known.

protected SSLSocket (InetAddress address, int port)

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port.

Parameters
address the address to connect to.
port the port number to connect to.
Throws
IOException if creating the socket fails.

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

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port with the client side bound to the specified address and port.

Parameters
host the host name to connect to.
port the port number to connect to.
clientAddress the client address to bind to
clientPort the client port number to bind to.
Throws
IOException if creating the socket fails.
UnknownHostException if the specified host is not known.

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

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port with the client side bound to the specified address and port.

Parameters
address the address to connect to.
port the port number to connect to.
clientAddress the client address to bind to.
clientPort the client port number to bind to.
Throws
IOException if creating the socket fails.

Public Methods

public abstract void addHandshakeCompletedListener (HandshakeCompletedListener listener)

Since: API Level 1

Registers the specified listener to receive notification on completion of a handshake on this connection.

Parameters
listener the listener to register.
Throws
IllegalArgumentException if listener is null.

public abstract boolean getEnableSessionCreation ()

Since: API Level 1

Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.

Returns
  • true if new sessions may be created, otherwise false.

public abstract String[] getEnabledCipherSuites ()

Since: API Level 1

Returns the names of the enabled cipher suites.

public abstract String[] getEnabledProtocols ()

Since: API Level 1

Returns the names of the enabled protocols.

public abstract boolean getNeedClientAuth ()

Since: API Level 1

Returns true if the server socket should require client authentication. This does not apply to sockets in client mode.

public SSLParameters getSSLParameters ()

Since: API Level 9

Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.

public abstract SSLSession getSession ()

Since: API Level 1

Returns the SSLSession for this connection. If necessary, a handshake will be initiated, in which case this method will block until the handshake has been established. If the handshake fails, an invalid session object will be returned.

Returns
  • the session object.

public abstract String[] getSupportedCipherSuites ()

Since: API Level 1

Returns the names of the supported cipher suites.

public abstract String[] getSupportedProtocols ()

Since: API Level 1

Returns the names of the supported protocols.

public abstract boolean getUseClientMode ()

Since: API Level 1

Returns true if this connection will act in client mode when handshaking.

public abstract boolean getWantClientAuth ()

Since: API Level 1

Returns true if the server should request client authentication. This does not apply to sockets in client mode.

public abstract void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Since: API Level 1

Removes the specified handshake completion listener.

Parameters
listener the listener to remove.
Throws
IllegalArgumentException if the specified listener is not registered or null.

public abstract void setEnableSessionCreation (boolean flag)

Since: API Level 1

Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused. If flag is false and there are no sessions to resume, handshaking will fail.

Parameters
flag true if new sessions may be created.

public abstract void setEnabledCipherSuites (String[] suites)

Since: API Level 1

Sets the names of the cipher suites to be enabled. Only cipher suites returned by getSupportedCipherSuites() are allowed.

Parameters
suites the names of the to be enabled cipher suites.
Throws
IllegalArgumentException if one of the cipher suite names is not supported.

public abstract void setEnabledProtocols (String[] protocols)

Since: API Level 1

Sets the names of the protocols to be enabled. Only protocols returned by getSupportedProtocols() are allowed.

Parameters
protocols the names of the to be enabled protocols.
Throws
IllegalArgumentException if one of the protocols is not supported.

public abstract void setNeedClientAuth (boolean need)

Since: API Level 1

Sets whether the server should require client authentication. This does not apply to sockets in client mode. Client authentication is one of the following:

  • authentication required
  • authentication requested
  • no authentication needed
This method overrides the setting of setWantClientAuth(boolean).

public void setSSLParameters (SSLParameters p)

Since: API Level 9

Sets various SSL handshake parameters based on the SSLParameter argument. Specifically, sets the SSLSocket's enabled cipher suites if the parameter's cipher suites are non-null. Similarly sets the enabled protocols. If the parameters specify the want or need for client authentication, those requirements are set on the SSLSocket, otherwise both are set to false.

public abstract void setUseClientMode (boolean mode)

Since: API Level 1

Sets whether this connection should act in client mode when handshaking.

Parameters
mode true if this connection should act in client mode, false if not.

public abstract void setWantClientAuth (boolean want)

Since: API Level 1

Sets whether the server should request client authentication. Unlike setNeedClientAuth(boolean) this won't stop the negotiation if the client doesn't authenticate. This does not apply to sockets in client mode.The client authentication is one of:

  • authentication required
  • authentication requested
  • no authentication needed
This method overrides the setting of setNeedClientAuth(boolean).

public void shutdownInput ()

Since: API Level 1

Unsupported for SSL because reading from an SSL socket may require writing to the network.

Throws
IOException

public void shutdownOutput ()

Since: API Level 1

Unsupported for SSL because writing to an SSL socket may require reading from the network.

Throws
IOException

public abstract void startHandshake ()

Since: API Level 1

Starts a new SSL handshake on this connection.

Throws
IOException if an error occurs.