com.dstc.security.ssl
Class SSLSocketFactory

java.lang.Object
  |
  +--javax.net.SocketFactory
        |
        +--javax.net.ssl.SSLSocketFactory
              |
              +--com.dstc.security.ssl.SSLSocketFactory

public class SSLSocketFactory
extends SSLSocketFactory

A concrete factory for SSLSocket implementations.


Constructor Summary
SSLSocketFactory()
          Create a default SSL socket factory.
 
Method Summary
 Socket createSocket(InetAddress host, int port)
          Returns a socket connected to a ServerSocket at the specified network address and port.
 Socket createSocket(InetAddress host, int port, InetAddress clientHost, int clientPort)
          Returns a socket connected to a ServerSocket at the specified network address and port.
 Socket createSocket(Socket s, String host, int port, boolean autoClose)
          Returns a socket layered over an existing socket to a ServerSocket on the named host, at the given port.
 Socket createSocket(String host, int port)
          Returns a socket connected to a ServerSocket on the named host, at the given port.
 Socket createSocket(String host, int port, InetAddress clientHost, int clientPort)
          Returns a socket connected to a ServerSocket on the named host, at the given port.
 String[] getDefaultCipherSuites()
          Returns the list of cipher suites which are enabled by default.
static SSLSocketFactory getInstance(SecureRandom rand, PrivateKey priv, X509Certificate[] certs, TrustEngine trustEngine, String[] suites)
          Create a new SSLSocketFactory.
static SSLSocketFactory getInstance(SecureRandom rand, PrivateKey priv, X509Certificate[] certs, TrustEngine trustEngine, String[] suites, int cacheLimit, int lifetime)
          Create a new SSLSocketFactory, with specific parameters for its session cache.
 String[] getSupportedCipherSuites()
          Returns the names of all the cipher suites that this SSLSocket factory supports.
 void setDebugLevel(int level)
          Enable or disable SSL debugging output:
 void setSessionResumptionForbidden(boolean flag)
          Set the state of the "session resumption forbidden" flag.
 
Methods inherited from class javax.net.ssl.SSLSocketFactory
getDefault
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SSLSocketFactory

public SSLSocketFactory()
                 throws KeyStoreException,
                        IOException,
                        NoSuchAlgorithmException,
                        CertificateException
Create a default SSL socket factory. This is normally invoked by SSLSocketFactory.getDefault().

This socket factory supports server authentication, using a TrustEngine from BasicTrustEngine.getDefault(). It does not support client authentication, so it does not have a private key or cert path, and it uses default parameters for SecureRandom, session-cache size and lifetime, and a default list of cipher suites. In the current release this default list is

{ "SSL_RSA_WITH_IDEA_CBC_SHA", "SSL_RSA_WITH_RC4_128_SHA", "SSL_RSA_EXPORT_WITH_RC4_40_MD5" }

If these default parameters are not suitable, use a static getInstance method instead.

Throws:
KeyStoreException - if the default keystore type is not available (!)
IOException - if the jre/lib/security/cacerts file could not be opened or read
NoSuchAlgorithmException - if the algorithm to check the integrity of the keystore cannot be found
CertificateException - if any of the certificates in the keystore could not be loaded
Method Detail

getInstance

public static SSLSocketFactory getInstance(SecureRandom rand,
                                           PrivateKey priv,
                                           X509Certificate[] certs,
                                           TrustEngine trustEngine,
                                           String[] suites)
Create a new SSLSocketFactory.

This method uses default values for the session cache that is created for this factory. These defaults are subject to change, but indicative values are a maximum lifetime in the session cache of 5 minutes, and a maximum of 10 entries in the cache.

The parameter values for this method are more fully described in getInstance(SecureRandom,PrivateKey,X509Certificate[], TrustEngine,String[],int,int)

Parameters:
rand - a SecureRandom implementation, or null (in which case a default SecureRandom will be used)
priv - the PrivateKey of this client, or normally null
certs - the X509Certificate or certificate path of this client, or normally null.
trustEngine - a TrustEngine, or null
suites - an array of names of cipher suites, or null
Returns:
a new SSLSocketFactory with the specified parameters

getInstance

public static SSLSocketFactory getInstance(SecureRandom rand,
                                           PrivateKey priv,
                                           X509Certificate[] certs,
                                           TrustEngine trustEngine,
                                           String[] suites,
                                           int cacheLimit,
                                           int lifetime)
Create a new SSLSocketFactory, with specific parameters for its session cache.

Each of the reference parameters to this method may be null; normally most, but not all, of these parameters will be null.

By default, an SSL client authenticates a server but not vice versa. As a result the second and third parameters of this method may be null, but the fourth parameter, the TrustEngine, must normally be non-null. The TrustEngine is not needed, and may be set to null, only if

Conversely, the second and third parameters only need to be non-null if The second and third parameters must be consistent:
  1. Either both are null or both are non-null,
  2. The private key and certs[0].getPublicKey() must be a key pair
  3. If certs.length > 1, the elements must be a cert path (or an initial subset of a cert path), in the correct order.

The fifth parameter, an array of String names of cipher suites, is used to set the default set of enabled cipher suites for SSLSocket instances created by this factory, i.e. the value that will be returned by getDefaultCipherSuites(). A null value for this parameter selects the default list defined in SSLSocketFactory().

Parameters:
rand - a SecureRandom implementation, or null (in which case a default SecureRandom will be used)
priv - the PrivateKey of this client, or normally null
certs - the X509Certificate or certificate path of this client, or normally null. This parameter must be consistent with the priv parameter; see above for details
trustEngine - a TrustEngine, or null
suites - an array of names of cipher suites, or null
cacheLimit - the integer maximum number of session-cache entries
lifetime - the integer maximum lifetime (in milliseconds) of entries in the session cache
Returns:
a new SSLSocketFactory with the specified parameters

getDefaultCipherSuites

public String[] getDefaultCipherSuites()
Description copied from class: SSLSocketFactory
Returns the list of cipher suites which are enabled by default. Unless a different list is enabled, handshaking on an SSL connection will use one of these cipher suites. The minimum quality of service for these defaults requires confidentiality protection and server authentication.
Overrides:
getDefaultCipherSuites in class SSLSocketFactory
Tags copied from class: SSLSocketFactory
Returns:
array of the cipher suites enabled by default

getSupportedCipherSuites

public String[] getSupportedCipherSuites()
Returns the names of all the cipher suites that this SSLSocket factory supports.

In the current release this factory supports the suites listed in section A.5 of RFC 2246 except the anonymous Diffie-Hellman suites. That is, it supports the ten TLS_RSA_* suites, six TLS_DH_* suites and six TLS_DHE_* suites, but not the five TLS_DH_anon_* suites.

Overrides:
getSupportedCipherSuites in class SSLSocketFactory
Tags copied from class: SSLSocketFactory
Returns:
an array of cipher suite names

createSocket

public Socket createSocket(Socket s,
                           String host,
                           int port,
                           boolean autoClose)
                    throws IOException
Description copied from class: SSLSocketFactory
Returns a socket layered over an existing socket to a ServerSocket on the named host, at the given port. This constructor can be used when tunneling SSL through a proxy. The host and port refer to the logical destination server. This socket is configured using the socket options established for this factory.
Overrides:
createSocket in class SSLSocketFactory

createSocket

public Socket createSocket(InetAddress host,
                           int port)
                    throws IOException,
                           UnknownHostException
Description copied from class: SocketFactory
Returns a socket connected to a ServerSocket at the specified network address and port. This socket is configured using the socket options established for this factory.
Overrides:
createSocket in class SocketFactory
Tags copied from class: SocketFactory
Parameters:
host - the server host
port - the server port

createSocket

public Socket createSocket(InetAddress host,
                           int port,
                           InetAddress clientHost,
                           int clientPort)
                    throws IOException,
                           UnknownHostException
Description copied from class: SocketFactory
Returns a socket connected to a ServerSocket at the specified network address and port. The client is bound to the specified network address and port, and the socket is configured using the socket options established for this factory.
Overrides:
createSocket in class SocketFactory
Tags copied from class: SocketFactory
Parameters:
address - the server network address
port - the server port
clientAddress - the client network address
clientPort - the client port

createSocket

public Socket createSocket(String host,
                           int port)
                    throws IOException
Description copied from class: SocketFactory
Returns a socket connected to a ServerSocket on the named host, at the given port. This socket is configured using the socket options established for this factory.
Overrides:
createSocket in class SocketFactory
Tags copied from class: SocketFactory
Parameters:
host - the server host
port - the server port

createSocket

public Socket createSocket(String host,
                           int port,
                           InetAddress clientHost,
                           int clientPort)
                    throws IOException
Description copied from class: SocketFactory
Returns a socket connected to a ServerSocket on the named host, at the given port. The client address address is the specified host and port. This socket is configured using the socket options established for this factory.
Overrides:
createSocket in class SocketFactory
Tags copied from class: SocketFactory
Parameters:
host - the server host
port - the server port
clientHost - the client host
clientPort - the client port

setDebugLevel

public void setDebugLevel(int level)
Enable or disable SSL debugging output:

At startup the debugging level is set from the System property "com.dstc.security.ssl.debug_level"; the value may be changed at run time by calling this method.

The debugging levels are:

0 or lower
disables debug output
1
enables debugging of the SSL messages level
2
enables debugging of SSL messages and the SSL record layer
3 or higher
enables debugging of SSL messages, records and crypto
Parameters:
level - the integer debugging level to set

setSessionResumptionForbidden

public void setSessionResumptionForbidden(boolean flag)
Set the state of the "session resumption forbidden" flag. The sockets created by this factory inherit a copy of this state; the default value is false.

An SSL client or server may use the following session policies:

  1. Always create a new session (never resume an existing session)
  2. Always resume an existing session (never create a new session)
  3. Allow either creation or resumption
The standard SSLSocket API provides SSLSocket.setEnableSessionCreation(boolean), where false selects (2) and true selects (3).

JCSI adds this method, where true selects (1).

Note that combining setEnableSessionCreation(false) and setSessionResumptionForbidden(true) is not supported.

Parameters:
flag - a boolean value; if true, session resumption is disallowed.