JavaTM 2 Platform
Std. Ed. v1.4.0

javax.net.ssl
Class SSLSocket

java.lang.Object
  |
  +--java.net.Socket
        |
        +--javax.net.ssl.SSLSocket

public abstract class SSLSocket
extends Socket

This class extends Sockets and provides secure socket using protocols such as the "Secure Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.

Such sockets are normal stream sockets, but they add a layer of security protections over the underlying network transport protocol, such as TCP. Those protections include:

These kinds of protection are specified by a "cipher suite", which is a combination of cryptographic algorithms used by a given SSL connection. During the negotiation process, the two endpoints must agree on a ciphersuite that is available in both environments. If there is no such suite in common, no SSL connection can be established, and no data can be exchanged.

The cipher suite used is established by a negotiation process called "handshaking". The goal of this process is to create or rejoin a "session", which may protect many connections over time. After handshaking has completed, you can access session attributes by using the getSession method. The initial handshake on this connection can be initiated in one of three ways:

If handshaking fails for any reason, the SSLSocket is closed, and no futher communications can be done.

There are two groups of cipher suites which you will need to know about when managing cipher suites:

Implementation defaults require that only cipher suites which authenticate servers and provide confidentiality be enabled by default. Only if both sides explicitly agree to unauthenticated and/or non-private (unencrypted) communications will such a ciphersuite be selected.

When SSLSockets are first created, no handshaking is done so that applications may first set their communication preferences: what cipher suites to use, whether the socket should be in client or server mode, etc. However, security is always provided by the time that application data is sent over the connection.

You may register to receive event notification of handshake completion. This involves the use of two additional classes. HandshakeCompletedEvent objects are passed to HandshakeCompletedListener instances, which are registered by users of this API. SSLSockets are created by SSLSocketFactorys, or by accepting a connection from a SSLServerSocket.

A SSL socket may choose to operate in the client or server mode. This will determine who begins the handshaking process, as well as which messages should be sent by each party. However, each connection must have one client and one server, or handshaking will not progress properly.

Since:
1.4
See Also:
Socket, SSLServerSocket, SSLSocketFactory

Constructor Summary
protected SSLSocket()
          Used only by subclasses.
protected SSLSocket(InetAddress address, int port)
          Used only by subclasses.
protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
          Used only by subclasses.
protected SSLSocket(String host, int port)
          Used only by subclasses.
protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
          Used only by subclasses.
 
Method Summary
abstract  void addHandshakeCompletedListener(HandshakeCompletedListener listener)
          Registers an event listener to receive notifications that an SSL handshake has completed on this connection.
abstract  String[] getEnabledCipherSuites()
          Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
abstract  String[] getEnabledProtocols()
          Returns the names of the protocol versions which are currently enabled for use on this connection.
abstract  boolean getEnableSessionCreation()
          Returns true if new SSL sessions may be established by this socket.
abstract  boolean getNeedClientAuth()
          Returns true if the socket will require client authentication.
abstract  SSLSession getSession()
          Returns the SSL Session in use by this connection.
abstract  String[] getSupportedCipherSuites()
          Returns the names of the cipher suites which could be enabled for use on this connection.
abstract  String[] getSupportedProtocols()
          Returns the names of the protocols which could be enabled for use on an SSL connection.
abstract  boolean getUseClientMode()
          Returns true if the socket is set to use client mode in its first handshake.
abstract  boolean getWantClientAuth()
          Returns true if the socket will request client authentication.
abstract  void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
          Removes a previously registered handshake completion listener.
abstract  void setEnabledCipherSuites(String[] suites)
          Controls which particular cipher suites are enabled for use on this connection.
abstract  void setEnabledProtocols(String[] protocols)
          Controls which particular protocol versions are enabled for use on this connection.
abstract  void setEnableSessionCreation(boolean flag)
          Controls whether new SSL sessions may be established by this socket.
abstract  void setNeedClientAuth(boolean need)
          Configures the socket to require client authentication.
abstract  void setUseClientMode(boolean mode)
          Configures the socket to use client (or server) mode in its first handshake.
abstract  void setWantClientAuth(boolean want)
          Configures the socket to request client authentication, but only if such a request is appropriate to the cipher suite negotiated.
abstract  void startHandshake()
          Starts an SSL handshake on this connection.
 
Methods inherited from class java.net.Socket
bind, close, connect, connect, getChannel, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SSLSocket

protected SSLSocket()
Used only by subclasses. Constructs an uninitialized, unconnected TCP socket.


SSLSocket

protected SSLSocket(String host,
                    int port)
             throws IOException,
                    UnknownHostException
Used only by subclasses. Constructs a TCP connection to a named host at a specified port. This acts as the SSL client.

Parameters:
host - name of the host with which to connect
port - number of the server's port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known

SSLSocket

protected SSLSocket(InetAddress address,
                    int port)
             throws IOException,
                    UnknownHostException
Used only by subclasses. Constructs a TCP connection to a server at a specified address and port. This acts as the SSL client.

Parameters:
address - the server's host
port - its port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known

SSLSocket

protected SSLSocket(String host,
                    int port,
                    InetAddress clientAddress,
                    int clientPort)
             throws IOException,
                    UnknownHostException
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.

Parameters:
host - name of the host with which to connect
port - number of the server's port
clientAddress - the client's host
clientPort - number of the client's port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known

SSLSocket

protected SSLSocket(InetAddress address,
                    int port,
                    InetAddress clientAddress,
                    int clientPort)
             throws IOException,
                    UnknownHostException
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.

Parameters:
address - the server's host
port - its port
clientAddress - the client's host
clientPort - number of the client's port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known
Method Detail

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 are useful in specialized applications.

Returns:
an array of cipher suite names
See Also:
getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getEnabledCipherSuites

public abstract 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 support a minium quality of service. Thus, in some environments this value might be empty.

There are several reasons why an enabled cipher suite might not actually be used. For example: the server socket might not have appropriate private keys available to it or the cipher suite might be anonymous, precluding the use of client authentication, while the server socket has been told to require that sort of authentication.

Returns:
an array of cipher suite names
See Also:
getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)
Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by getSupportedCipherSuites() 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
Throws:
IllegalArgumentException - when one or more of the ciphers named by the parameter is not supported, or when the parameter is null.
See Also:
getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedProtocols

public abstract String[] getSupportedProtocols()
Returns the names of the protocols which could be enabled for use on an SSL connection.

Returns:
an array of protocols supported

getEnabledProtocols

public abstract String[] getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use on this connection.

Returns:
an array of protocols
See Also:
setEnabledProtocols(java.lang.String[])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)
Controls which particular protocol versions are enabled for use on this connection. The protocols must have been listed by getSupportedProtocols() as being supported.

Parameters:
protocols - Names of all the protocols to enable.
Throws:
IllegalArgumentException - when one or more of the protocols named by the parameter is not supported or when the protocols parameter is null.
See Also:
getEnabledProtocols()

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".

Returns:
the SSLSession

addHandshakeCompletedListener

public abstract 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
Throws:
IllegalArgumentException - if the argument is null.
See Also:
startHandshake(), removeHandshakeCompletedListener(HandshakeCompletedListener)

removeHandshakeCompletedListener

public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener.

Parameters:
listener - the HandShake Completed event listener
Throws:
IllegalArgumentException - if the listener is not registered, or the argument is null.
See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)

startHandshake

public abstract void startHandshake()
                             throws IOException
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.

Throws:
IOException - on a network level error
See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)

setUseClientMode

public abstract void setUseClientMode(boolean mode)
Configures the socket to use client (or server) mode in its first handshake. Servers normally authenticate themselves, and clients are not required to do so.

Parameters:
mode - true if the socket should start its first handshake in "client" mode
Throws:
IllegalArgumentException - if a mode change is attempted after handshaking has begun.
See Also:
getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()
Returns true if the socket is set to use client mode in its first handshake.

Returns:
true if the socket should start its first handshake in "client" mode
See Also:
setUseClientMode(boolean)

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.

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

Parameters:
need - should be set to true if the clients must authenticate themselves. Setting this parameter to true overrides the current setting of setWantClientAuth(boolean).
See Also:
getNeedClientAuth(), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

getNeedClientAuth

public abstract boolean getNeedClientAuth()
Returns true if the socket will require client authentication. The option is only useful to sockets in the server mode.

Returns:
true if the server mode socket should request that the client authenticate itself.
See Also:
setNeedClientAuth(boolean), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

setWantClientAuth

public abstract void setWantClientAuth(boolean want)
Configures the socket to request client authentication, but only if such a request is appropriate to the cipher suite negotiated. This option is only useful for sockets in the server mode. Unlike setNeedClientAuth(boolean), if the client chooses not to provide authentication information about itself, the negotiations will continue.

The socket must be a server mode socket.

Parameters:
want - should be set to true if the clients should try to authenticate themselves. Setting this parameter to true overrides the current setting of setNeedClientAuth(boolean).
See Also:
getWantClientAuth(), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

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.

Returns:
true if the server mode socket should request that the client authenticate itself
See Also:
setNeedClientAuth(boolean), getNeedClientAuth(), setWantClientAuth(boolean), setUseClientMode(boolean)

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this socket. If sesssion creations are not allowed, and there are no existing sessions to resume, there will be no successful handshaking.

Parameters:
flag - true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed
See Also:
getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()
Returns true if new SSL sessions may be established by this socket.

Returns:
true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed
See Also:
setEnableSessionCreation(boolean)

JavaTM 2 Platform
Std. Ed. v1.4.0

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.