SSLSocket | Java In A Nutshell, 5th Edition

SSLSocket

javax.net.ssl

Java 1.4

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.

Figure 18-16. javax.net.ssl.SSLSocket

 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;   }

Passed To

HandshakeCompletedEvent.HandshakeCompletedEvent( )

Returned By

HandshakeCompletedEvent.getSocket( )