java.lang.Object java.net.Socket javax.net.ssl.SSLSocket
public abstract class SSLSocket
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 must 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. Each connection must have one client and one server, or handshaking will not progress properly. Once the initial handshaking has started, a socket can not switch between client and server modes, even when performing renegotiations.
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. |
SSLParameters |
getSSLParameters
()
Returns the SSLParameters in effect for this SSLSocket. |
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 when handshaking. |
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) Sets the cipher suites enabled for use on this connection. |
abstract void |
setEnabledProtocols
(
String
[] protocols) Sets the protocol versions 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. |
void |
setSSLParameters
(
SSLParameters
Applies SSLParameters to this socket. |
abstract void |
setUseClientMode
(boolean mode) Configures the socket to use client (or server) mode when handshaking. |
abstract void |
setWantClientAuth
(boolean want) Configures the socket to request client authentication. |
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 , setPerformancePreferences , 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 |
---|
protected SSLSocket()
protected SSLSocket(String host, int port) throws IOException, UnknownHostException
protected SSLSocket(InetAddress address, int port) throws IOException
protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) throws IOException, UnknownHostException
protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) throws IOException
Method Detail |
---|
public abstract String[] getSupportedCipherSuites()
public abstract String[] getEnabledCipherSuites()
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.
public abstract void setEnabledCipherSuites(String[] suites)
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.
public abstract String[] getSupportedProtocols()
public abstract String[] getEnabledProtocols()
public abstract void setEnabledProtocols(String[] protocols)
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.
public abstract SSLSession getSession()
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".
public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)
public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
public abstract void startHandshake() throws IOException
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.
public abstract void setUseClientMode(boolean mode)
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.
public abstract boolean getUseClientMode()
public abstract void setNeedClientAuth(boolean need)
A socket's client authentication setting is one of the following:
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) .
public abstract boolean getNeedClientAuth()
public abstract void setWantClientAuth(boolean want)
A socket's client authentication setting is one of the following:
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) .
public abstract boolean getWantClientAuth()
public abstract void setEnableSessionCreation(boolean flag)
public abstract boolean getEnableSessionCreation()
public SSLParametersgetSSLParameters ()
public void setSSLParameters ( SSLParameters params)