An
SSLSocket is a "secure
socket" subclass of
java.net.Socket that implements the SSL or TLS
protocols, which are commonly used to authenticate a server to a
client and to encrypt the data transferred between the two. Create a
SSLSocket for connecting to a SSL-enabled server
by calling one of the createSocket( ) methods of a
SSLSocketFactory object. See
SSLSocketFactory for details. If you are writing
server code, then you will obtain a SSLSocket for
communicating with an SSL-enabled client from the inherited
accept( ) method of an
SSLServerSocket. See
SSLServerSocket for details.
SSLSocket inherits all of the standard socket
method of its superclass, and can be used for networking just like an
ordinary java.net.Socket object. In addition,
however, it also defines methods that control how the secure
connection is established. These methods may be called before the SSL
"handshake" occurs. The handshake
does not occur when the socket is first created and connected, so
that you can configure various SSL parameters that control how the
handshake occurs. Calling startHandshake( ),
getSession( ), or reading or writing data on the
socket trigger a handshake, so you must configure the socket before
doing any of these things. If you want to be notified when the
handshake occurs, call addHandshakeCompletedListener(
) to register a listener object to receive the
notification.
getSupportedProtocols(
) returns a list of secure socket protocols
that are supported by the socket implementation.
setEnabledProtocols(
) allows you to specify the name or
names of the supported protocols that you are willing to use for this
socket. getSupportedCipherSuite(
) returns the full set of
cipher suites supported by the underlying
security provider. setEnabledCipherSuites( )
specifies a list of one or more cipher suites that you are willing to
use for the connection. Note that not all supported cipher suites are
enabled by default: only suites that provide encryption and require
the server to authenticate itself to the client are enabled. If you
want to allow the server to remain anonymous, you can use
setEnabledCipherSuites( ) to enable a
nonauthenticating suite. Specific protocols and cipher suites are not
described here because using them correctly requires a detailed
understanding of cryptography, which is beyond the scope of this
reference. Most applications can simply rely on the default set of
enabled protocols and cipher suites.
If you are writing a server and have obtained an
SSLSocket by accepting a connection on an
SSLServerSocket, then you may call
setWantClientAuth(
) to request that the
client authenticate itself to you, and
you may call setNeedClientAuth(
) to require that the client authenticate
itself during the handshake. Note, however, that it is usually more
efficient to request or require client authentication on the server
socket than it is to call these methods on each
SSLSocket it creates.
The configuration methods described above must be called before the
SSL handshake occurs. Call getSession( ) to obtain
an SSLSession object that you can query for for
information about the handshake, such as the protocol and cipher
suite in use, and the identity of the server. Note that a call to
getSession( ) will cause the handshake to occur if
it has not already occurred, so you can call this method at any time.
public abstract class SSLSocket extends java.net.Socket {
// Protected Constructors
protected SSLSocket( );
protected SSLSocket(String host, int port)
throws java.io.IOException, java.net.UnknownHostException;
protected SSLSocket(java.net.InetAddress address, int port)
throws java.io.IOException;
protected SSLSocket(String host, int port, java.net.InetAddress clientAddress,
int clientPort) throws java.io.IOException,
java.net.UnknownHostException;
protected SSLSocket(java.net.InetAddress address, int port, java.net.InetAddress clientAddress,
int clientPort) throws java.io.IOException;
// Event Registration Methods (by event name)
public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener);
public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener);
// Public Instance Methods
public abstract String[ ] getEnabledCipherSuites( );
public abstract String[ ] getEnabledProtocols( );
public abstract boolean getEnableSessionCreation( );
public abstract boolean getNeedClientAuth( );
public abstract SSLSession getSession( );
public abstract String[ ] getSupportedCipherSuites( );
public abstract String[ ] getSupportedProtocols( );
public abstract boolean getUseClientMode( );
public abstract boolean getWantClientAuth( );
public abstract void setEnabledCipherSuites(String[ ] suites);
public abstract void setEnabledProtocols(String[ ] protocols);
public abstract void setEnableSessionCreation(boolean flag);
public abstract void setNeedClientAuth(boolean need);
public abstract void setUseClientMode(boolean mode);
public abstract void setWantClientAuth(boolean want);
public abstract void startHandshake( ) throws java.io.IOException;
}
