public final class

SSLSocketImpl

extends SSLSocket
java.lang.Object
   ↳ java.net.Socket
     ↳ javax.net.ssl.SSLSocket
       ↳ sun.security.ssl.SSLSocketImpl

Class Overview

Implementation of an SSL socket. This is a normal connection type socket, implementing SSL over some lower level socket, such as TCP. Because it is layered over some lower level socket, it MUST override all default socket methods.

This API offers a non-traditional option for establishing SSL connections. You may first establish the connection directly, then pass that connection to the SSL socket constructor with a flag saying which role should be taken in the handshake protocol. (The two ends of the connection must not choose the same role!) This allows setup of SSL proxying or tunneling, and also allows the kind of "role reversal" that is required for most FTP data transfers.

See Also

Summary

Public Methods
synchronized void addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers an event listener to receive notifications that an SSL handshake has completed on this connection.
void bind(SocketAddress bindpoint)
Binds the address to the socket.
void close()
Closes the SSL connection.
void connect(SocketAddress endpoint, int timeout)
Connects this socket to the server with a specified timeout value.
final void connect(SocketAddress endpoint)
Connects this socket to the server.
final SocketChannel getChannel()
Returns the unique java.nio.SocketChannel SocketChannel object associated with this socket, if any.
synchronized boolean getEnableSessionCreation()
Returns true if new connections may cause creation of new SSL sessions.
synchronized String[] getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
synchronized String[] getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use on this connection.
synchronized String getHostnameVerification()
Returns the endpoint identification algorithm of the socket.
final InetAddress getInetAddress()
Returns the address of the remote peer for this connection.
synchronized InputStream getInputStream()
Gets an input stream to read from the peer on the other side.
final boolean getKeepAlive()
Tests if SO_KEEPALIVE is enabled.
final InetAddress getLocalAddress()
Gets the local address to which the socket is bound.
final int getLocalPort()
Returns the number of the local port that this connection uses.
SocketAddress getLocalSocketAddress()
Returns the address of the endpoint this socket is connected to
synchronized boolean getNeedClientAuth()
Returns true if the socket will require client authentication.
final boolean getOOBInline()
Tests if OOBINLINE is enabled.
synchronized OutputStream getOutputStream()
Gets an output stream to write to the peer on the other side.
final int getPort()
Returns the number of the remote port that this connection uses.
final int getReceiveBufferSize()
Gets the value of the SO_RCVBUF option for this Socket, that is the buffer size used by the platform for input on this Socket.
SocketAddress getRemoteSocketAddress()
Returns the address of the endpoint this socket is connected to
final boolean getReuseAddress()
Tests if SO_REUSEADDR is enabled.
final int getSendBufferSize()
Get value of the SO_SNDBUF option for this Socket, that is the buffer size used by the platform for output on this Socket.
SSLSession getSession()
Returns the the SSL Session in use by this connection.
final int getSoLinger()
Returns the socket's linger timeout.
final int getSoTimeout()
Returns the socket timeout.
String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection.
String[] getSupportedProtocols()
Returns the protocols that are supported by this implementation.
final boolean getTcpNoDelay()
Returns true if the Nagle optimization is disabled.
final int getTrafficClass()
Gets traffic class or type-of-service in the IP header for packets sent from this Socket.
synchronized boolean getUseClientMode()
Returns true if the socket is set to use client mode when handshaking.
synchronized boolean getWantClientAuth()
Returns true if the socket will request client authentication.
final boolean isBound()
Returns the binding state of the socket.
boolean isClosed()
Return whether the socket has been explicitly closed by the application.
final boolean isConnected()
Returns the connection state of the socket.
final boolean isInputShutdown()
Returns the input state of the socket
final boolean isOutputShutdown()
Returns the output state of the socket
synchronized void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener.
final void sendUrgentData(int data)
Send one byte of urgent data on the socket.
synchronized void setEnableSessionCreation(boolean flag)
Controls whether new connections may cause creation of new SSL sessions.
synchronized void setEnabledCipherSuites(String[] suites)
Controls which particular cipher suites are enabled for use on this connection.
synchronized void setEnabledProtocols(String[] protocols)
Controls which protocols are enabled for use on this connection.
synchronized void setHost(String host)
final void setKeepAlive(boolean on)
Enable/disable SO_KEEPALIVE.
synchronized void setNeedClientAuth(boolean flag)
Sets the flag controlling whether a server mode socket *REQUIRES* SSL client authentication.
final void setOOBInline(boolean on)
Enable/disable OOBINLINE (receipt of TCP urgent data) By default, this option is disabled and TCP urgent data received on a socket is silently discarded.
void setPerformancePreferences(int connectionTime, int latency, int bandwidth)
Sets performance preferences for this socket.
final void setReceiveBufferSize(int size)
Sets the SO_RCVBUF option to the specified value for this Socket.
final void setReuseAddress(boolean on)
Enable/disable SO_REUSEADDR.
final void setSendBufferSize(int size)
Sets the SO_SNDBUF option to the specified value for this Socket.
final void setSoLinger(boolean flag, int linger)
Assigns the socket's linger timeout.
void setSoTimeout(int timeout)
Assigns the socket timeout.
final void setTcpNoDelay(boolean value)
Enables or disables the Nagle optimization.
final void setTrafficClass(int tc)
Sets traffic class or type-of-service octet in the IP header for packets sent from this Socket.
synchronized void setUseClientMode(boolean flag)
Sets the flag controlling whether the socket is in SSL client or server mode.
synchronized void setWantClientAuth(boolean flag)
Sets the flag controlling whether a server mode socket *REQUESTS* SSL client authentication.
final void shutdownInput()
The semantics of shutdownInput is not supported in TLS 1.0 spec.
final void shutdownOutput()
The semantics of shutdownOutput is not supported in TLS 1.0 spec.
void startHandshake()
Starts an SSL handshake on this connection.
String toString()
Returns a printable representation of this end of the connection.
synchronized boolean trySetHostnameVerification(String identificationAlgorithm)
Try to configure the endpoint identification algorithm of the socket.
Protected Methods
void closeSocket()
final void finalize()
Ensures that the SSL connection is closed down as cleanly as possible, in case the application forgets to do so.
[Expand]
Inherited Methods
From class javax.net.ssl.SSLSocket
From class java.net.Socket
From class java.lang.Object

Public Methods

public synchronized void addHandshakeCompletedListener (HandshakeCompletedListener listener)

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

Parameters
listener the HandShake Completed event listener

public void bind (SocketAddress bindpoint)

Binds the address to the socket.

Parameters
bindpoint the SocketAddress to bind to
Throws
IOException
See Also

public void close ()

Closes the SSL connection. SSL includes an application level shutdown handshake; you should close SSL sockets explicitly rather than leaving it for finalization, so that your remote peer does not experience a protocol error.

Throws
IOException

public void connect (SocketAddress endpoint, int timeout)

Connects this socket to the server with a specified timeout value. This method is either called on an unconnected SSLSocketImpl by the application, or it is called in the constructor of a regular SSLSocketImpl. If we are layering on top on another socket, then this method should not be called, because we assume that the underlying socket is already connected by the time it is passed to us.

Parameters
endpoint the SocketAddress
timeout the timeout value to be used, 0 is no timeout
Throws
IOException if an error occurs during the connection
SocketTimeoutException if timeout expires before connecting

public final void connect (SocketAddress endpoint)

Connects this socket to the server. This method is either called on an unconnected SSLSocketImpl by the application, or it is called in the constructor of a regular SSLSocketImpl. If we are layering on top on another socket, then this method should not be called, because we assume that the underlying socket is already connected by the time it is passed to us.

Parameters
endpoint the SocketAddress
Throws
IOException if an error occurs during the connection

public final SocketChannel getChannel ()

Returns the unique java.nio.SocketChannel SocketChannel object associated with this socket, if any.

Returns
  • the socket channel associated with this socket, or null if this socket was not created for a channel
See Also

public synchronized boolean getEnableSessionCreation ()

Returns true if new connections may cause creation of new SSL sessions.

Returns
  • true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed

public synchronized String[] getEnabledCipherSuites ()

Returns the names of the SSL cipher suites which are currently enabled for use on this connection. When an SSL socket is first created, all enabled cipher suites (a) protect data confidentiality, by traffic encryption, and (b) can mutually authenticate both clients and servers. Thus, in some environments, this value might be empty.

Returns
  • an array of cipher suite names

public synchronized String[] getEnabledProtocols ()

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

Returns
  • an array of protocols

public synchronized String getHostnameVerification ()

Returns the endpoint identification algorithm of the socket.

public final InetAddress getInetAddress ()

Returns the address of the remote peer for this connection.

Returns
  • the remote IP address to which this socket is connected, or null if the socket is not connected.

public synchronized InputStream getInputStream ()

Gets an input stream to read from the peer on the other side. Data read from this stream was always integrity protected in transit, and will usually have been confidentiality protected.

Returns
  • an input stream for reading bytes from this socket.
Throws
IOException

public final boolean getKeepAlive ()

Tests if SO_KEEPALIVE is enabled.

Returns
  • a boolean indicating whether or not SO_KEEPALIVE is enabled.
Throws
SocketException
See Also

public final InetAddress getLocalAddress ()

Gets the local address to which the socket is bound.

Returns
  • the local address to which the socket is bound.

public final int getLocalPort ()

Returns the number of the local port that this connection uses.

Returns
  • the local port number to which this socket is bound or -1 if the socket is not bound yet.

public SocketAddress getLocalSocketAddress ()

Returns the address of the endpoint this socket is connected to

Returns
  • a SocketAddress representing the local endpoint of this socket, or null if it is not bound yet.
See Also

public synchronized boolean getNeedClientAuth ()

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

Returns
  • true if client authentication is required, or false if no client authentication is desired.

public final boolean getOOBInline ()

Tests if OOBINLINE is enabled.

Returns
  • a boolean indicating whether or not OOBINLINE is enabled.
Throws
SocketException
See Also

public synchronized OutputStream getOutputStream ()

Gets an output stream to write to the peer on the other side. Data written on this stream is always integrity protected, and will usually be confidentiality protected.

Returns
  • an output stream for writing bytes to this socket.
Throws
IOException

public final int getPort ()

Returns the number of the remote port that this connection uses.

Returns
  • the remote port number to which this socket is connected, or 0 if the socket is not connected yet.

public final int getReceiveBufferSize ()

Gets the value of the SO_RCVBUF option for this Socket, that is the buffer size used by the platform for input on this Socket.

Returns
  • the value of the SO_RCVBUF option for this Socket.
Throws
SocketException

public SocketAddress getRemoteSocketAddress ()

Returns the address of the endpoint this socket is connected to

Returns
  • a SocketAddress reprensenting the remote endpoint of this socket, or null if it is not connected yet.
See Also

public final boolean getReuseAddress ()

Tests if SO_REUSEADDR is enabled.

Returns
  • a boolean indicating whether or not SO_REUSEADDR is enabled.
Throws
SocketException
See Also

public final int getSendBufferSize ()

Get value of the SO_SNDBUF option for this Socket, that is the buffer size used by the platform for output on this Socket.

Returns
  • the value of the SO_SNDBUF option for this Socket.
Throws
SocketException

public SSLSession getSession ()

Returns the the SSL Session in use by this connection. These can be long lived, and frequently correspond to an entire login session for some user.

Returns
  • the SSLSession

public final int getSoLinger ()

Returns the socket's linger timeout.

Returns
  • the setting for SO_LINGER.
Throws
SocketException
See Also

public final int getSoTimeout ()

Returns the socket timeout.

Returns
  • the setting for SO_TIMEOUT
Throws
SocketException
See Also

public String[] getSupportedCipherSuites ()

Returns the names of the cipher suites which could be enabled for use on an SSL connection. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not support the mutual authentication of servers and clients, or which do not protect data confidentiality. Servers may also need certain kinds of certificates to use certain cipher suites.

Returns
  • an array of cipher suite names

public String[] getSupportedProtocols ()

Returns the protocols that are supported by this implementation. A subset of the supported protocols may be enabled for this connection@ returns an array of protocol names.

Returns
  • an array of protocols supported

public final boolean getTcpNoDelay ()

Returns true if the Nagle optimization is disabled. This relates to low-level buffering of TCP traffic, delaying the traffic to promote better throughput.

Returns
  • a boolean indicating whether or not TCP_NODELAY is enabled.
Throws
SocketException
See Also

public final int getTrafficClass ()

Gets traffic class or type-of-service in the IP header for packets sent from this Socket.

Returns
  • the traffic class or type-of-service already set
Throws
SocketException
See Also

public synchronized boolean getUseClientMode ()

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

Returns
  • true if the socket should do handshaking in "client" mode

public synchronized boolean getWantClientAuth ()

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

Returns
  • true if client authentication is requested, or false if no client authentication is desired.

public final boolean isBound ()

Returns the binding state of the socket.

Returns
  • true if the socket successfuly bound to an address
See Also

public boolean isClosed ()

Return whether the socket has been explicitly closed by the application.

Returns
  • true if the socket has been closed

public final boolean isConnected ()

Returns the connection state of the socket.

Returns
  • true if the socket successfuly connected to a server
See Also

public final boolean isInputShutdown ()

Returns the input state of the socket

Returns
  • true if the input of the socket has been shutdown
See Also

public final boolean isOutputShutdown ()

Returns the output state of the socket

Returns
  • true if the output of the socket has been shutdown
See Also

public synchronized void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Removes a previously registered handshake completion listener.

Parameters
listener the HandShake Completed event listener

public final void sendUrgentData (int data)

Send one byte of urgent data on the socket.

Parameters
data The byte of data to send
Throws
SocketException
See Also

public synchronized void setEnableSessionCreation (boolean flag)

Controls whether new connections may cause creation of new SSL sessions. As long as handshaking has not started, we can change whether we enable session creations. Otherwise, we will need to wait for the next handshake.

Parameters
flag true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed

public synchronized void setEnabledCipherSuites (String[] suites)

Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by getCipherSuites() as being supported. Even if a suite has been enabled, it might never be used if no peer supports it or the requisite certificates (and private keys) are not available.

Parameters
suites Names of all the cipher suites to enable.

public synchronized void setEnabledProtocols (String[] protocols)

Controls which protocols are enabled for use on this connection. The protocols must have been listed by getSupportedProtocols() as being supported.

Parameters
protocols protocols to enable.
Throws
IllegalArgumentException when one of the protocols named by the parameter is not supported.

public synchronized void setHost (String host)

public final void setKeepAlive (boolean on)

Enable/disable SO_KEEPALIVE.

Parameters
on whether or not to have socket keep alive turned on.
Throws
SocketException
See Also

public synchronized void setNeedClientAuth (boolean flag)

Sets the flag controlling whether a server mode socket *REQUIRES* SSL client authentication. As long as handshaking has not started, we can change whether client authentication is needed. Otherwise, we will need to wait for the next handshake.

Parameters
flag set to true if client authentication is required, or false if no client authentication is desired.

public final void setOOBInline (boolean on)

Enable/disable OOBINLINE (receipt of TCP urgent data) By default, this option is disabled and TCP urgent data received on a socket is silently discarded.

Parameters
on true to enable OOBINLINE, false to disable.
Throws
SocketException
See Also

public void setPerformancePreferences (int connectionTime, int latency, int bandwidth)

Sets performance preferences for this socket.

Parameters
connectionTime An int expressing the relative importance of a short connection time
latency An int expressing the relative importance of low latency
bandwidth An int expressing the relative importance of high bandwidth
See Also

public final void setReceiveBufferSize (int size)

Sets the SO_RCVBUF option to the specified value for this Socket. The SO_RCVBUF option is used by the platform's networking code as a hint for the size to set the underlying network I/O buffers.

Increasing the receive buffer size can increase the performance of network I/O for high-volume connection, while decreasing it can help reduce the backlog of incoming data.

Because SO_RCVBUF is a hint, applications that want to verify what size the buffers were set to should call getReceiveBufferSize().

The value of SO_RCVBUF is also used to set the TCP receive window that is advertized to the remote peer. Generally, the window size can be modified at any time when a socket is connected. However, if a receive window larger than 64K is required then this must be requested before the socket is connected to the remote peer. There are two cases to be aware of:

  1. For sockets accepted from a ServerSocket, this must be done by calling setReceiveBufferSize(int) before the ServerSocket is bound to a local address.

  2. For client sockets, setReceiveBufferSize() must be called before connecting the socket to its remote peer.

Parameters
size the size to which to set the receive buffer size. This value must be greater than 0.
Throws
SocketException

public final void setReuseAddress (boolean on)

Enable/disable SO_REUSEADDR.

Parameters
on whether to enable or disable the socket option
Throws
SocketException
See Also

public final void setSendBufferSize (int size)

Sets the SO_SNDBUF option to the specified value for this Socket. The SO_SNDBUF option is used by the platform's networking code as a hint for the size to set the underlying network I/O buffers.

Because SO_SNDBUF is a hint, applications that want to verify what size the buffers were set to should call getSendBufferSize().

Parameters
size the size to which to set the send buffer size. This value must be greater than 0.
Throws
SocketException

public final void setSoLinger (boolean flag, int linger)

Assigns the socket's linger timeout.

Parameters
flag whether or not to linger on.
linger how long to linger for, if on is true.
Throws
SocketException
See Also

public void setSoTimeout (int timeout)

Assigns the socket timeout.

Parameters
timeout the specified timeout, in milliseconds.
Throws
SocketException
See Also

public final void setTcpNoDelay (boolean value)

Enables or disables the Nagle optimization.

Parameters
value true to enable TCP_NODELAY, false to disable.
Throws
SocketException
See Also

public final void setTrafficClass (int tc)

Sets traffic class or type-of-service octet in the IP header for packets sent from this Socket.

Parameters
tc an int value for the bitset.
Throws
SocketException
See Also

public synchronized void setUseClientMode (boolean flag)

Sets the flag controlling whether the socket is in SSL client or server mode. Must be called before any SSL traffic has started.

Parameters
flag true if the socket should start its handshaking in "client" mode

public synchronized void setWantClientAuth (boolean flag)

Sets the flag controlling whether a server mode socket *REQUESTS* SSL client authentication. As long as handshaking has not started, we can change whether client authentication is requested. Otherwise, we will need to wait for the next handshake.

Parameters
flag set to true if client authentication is requested, or false if no client authentication is desired.

public final void shutdownInput ()

The semantics of shutdownInput is not supported in TLS 1.0 spec. Thus when the method is called on an SSL socket, an UnsupportedOperationException will be thrown.

Throws
UnsupportedOperationException
IOException

public final void shutdownOutput ()

The semantics of shutdownOutput is not supported in TLS 1.0 spec. Thus when the method is called on an SSL socket, an UnsupportedOperationException will be thrown.

Throws
UnsupportedOperationException
IOException

public void startHandshake ()

Starts an SSL handshake on this connection.

Throws
IOException

public String toString ()

Returns a printable representation of this end of the connection.

Returns
  • a string representation of this socket.

public synchronized boolean trySetHostnameVerification (String identificationAlgorithm)

Try to configure the endpoint identification algorithm of the socket.

Parameters
identificationAlgorithm the algorithm used to check the endpoint identity.
Returns
  • true if the identification algorithm configuration success.

Protected Methods

protected void closeSocket ()

Throws
IOException

protected final void finalize ()

Ensures that the SSL connection is closed down as cleanly as possible, in case the application forgets to do so. This allows SSL connections to be implicitly reclaimed, rather than forcing them to be explicitly reclaimed at the penalty of prematurly killing SSL sessions.

Throws
Throwable