com.dstc.security.ssl
Class SSLServerSocketFactory

java.lang.Object
  |
  +--javax.net.ServerSocketFactory
        |
        +--javax.net.ssl.SSLServerSocketFactory
              |
              +--com.dstc.security.ssl.SSLServerSocketFactory

public class SSLServerSocketFactory
extends SSLServerSocketFactory

A concrete factory for SSLServerSocket implementations.


Constructor Summary
SSLServerSocketFactory()
          Create the default SSL server socket factory.
 
Method Summary
 ServerSocket createServerSocket(int port)
          Returns a server socket which uses all network interfaces on the host, and is bound to the specified port.
 ServerSocket createServerSocket(int port, int backlog)
          Returns a server socket which uses all network interfaces on the host, is bound to a the specified port, and uses the specified connection backlog.
 ServerSocket createServerSocket(int port, int backlog, InetAddress ifAddress)
          Returns a server socket which uses only the specified network interface on the local host, is bound to a the specified port, and uses the specified connection backlog.
 String[] getDefaultCipherSuites()
          Returns the list of cipher suites which are enabled by default.
static SSLServerSocketFactory getInstance(SecureRandom rand, PrivateKey priv, X509Certificate[] certs, TrustEngine trustEngine, String[] suites)
          Create a new SSLServerSocketFactory.
static SSLServerSocketFactory getInstance(SecureRandom rand, PrivateKey priv, X509Certificate[] certs, TrustEngine trustEngine, String[] suites, int cacheLimit, int lifetime)
          Create a new SSLServerSocketFactory, with specific parameters for its session cache.
 String[] getSupportedCipherSuites()
          Returns the names of all the cipher suites that this SSLServerSocket factory supports.
 void setDebugLevel(int level)
          Enable or disable SSL debugging output:
 void setNeedClientAuth(boolean flag)
          Set the state of the "client authentication required" flag.
 void setSessionResumptionForbidden(boolean flag)
          Set the state of the "session resumption forbidden" flag.
 
Methods inherited from class javax.net.ssl.SSLServerSocketFactory
getDefault
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SSLServerSocketFactory

public SSLServerSocketFactory()
Create the default SSL server socket factory. This is invoked by SSLServerSocketFactory.getDefault().

Note that, in this release, this constructor cannot produce a usable factory for SSL server-mode applications (because it would need a private-key / public-key (certificate) pair in order to be useful), so instead this constructor always throws a runtime exception.

The getInstance static methods should be used instead to create a usable SSLServerSocketFactory.

Throws:
UnsupportedOperationException - is always thrown in this release
Method Detail

getInstance

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

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 server, or null
certs - the X509Certificate or certificate path of this server, or null.
trustEngine - a TrustEngine, or normally null
suites - an array of names of cipher suites, or null
Returns:
a new SSLServerSocketFactory with the specified parameters

getInstance

public static SSLServerSocketFactory getInstance(SecureRandom rand,
                                                 PrivateKey priv,
                                                 X509Certificate[] certs,
                                                 TrustEngine trustEngine,
                                                 String[] suites,
                                                 int cacheLimit,
                                                 int lifetime)
Create a new SSLServerSocketFactory, 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. Thus this server will generally need a private key and the corresponding certificate (or certificate path); the second and third parameters of this method convey this information. These two 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.
These two parameters are not needed, and may be set to null, only if

The fourth parameter, a TrustEngine, is only needed if this server also desires to authenticate the SSL client, i.e. setNeedClientAuth(true), or if some of the server sockets created by this factory will actually be used in SSL client mode.

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

Parameters:
rand - a SecureRandom implementation, or null (in which case a default SecureRandom will be used)
priv - the PrivateKey of this server, or null
certs - the X509Certificate or certificate path of this server, or null. This parameter must be consistent with the priv parameter; see above for details
trustEngine - a TrustEngine, or normally 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 SSLServerSocketFactory with the specified parameters
See Also:
TrustEngine, BasicTrustEngine

getDefaultCipherSuites

public String[] getDefaultCipherSuites()
Description copied from class: SSLServerSocketFactory
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 SSLServerSocketFactory
Tags copied from class: SSLServerSocketFactory
Returns:
array of the cipher suites enabled by default

getSupportedCipherSuites

public String[] getSupportedCipherSuites()
Returns the names of all the cipher suites that this SSLServerSocket 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 SSLServerSocketFactory
Tags copied from class: SSLServerSocketFactory
Returns:
an array of cipher suite names

createServerSocket

public ServerSocket createServerSocket(int port)
                                throws IOException
Description copied from class: ServerSocketFactory
Returns a server socket which uses all network interfaces on the host, and is bound to the specified port.
Overrides:
createServerSocket in class ServerSocketFactory
Tags copied from class: ServerSocketFactory
Parameters:
port - the port to listen to

createServerSocket

public ServerSocket createServerSocket(int port,
                                       int backlog)
                                throws IOException
Description copied from class: ServerSocketFactory
Returns a server socket which uses all network interfaces on the host, is bound to a the specified port, and uses the specified connection backlog. The socket is configured with the socket options (such as accept timeout) given to this factory.
Overrides:
createServerSocket in class ServerSocketFactory
Tags copied from class: ServerSocketFactory
Parameters:
port - the port to listen to
backlog - how many connections are queued

createServerSocket

public ServerSocket createServerSocket(int port,
                                       int backlog,
                                       InetAddress ifAddress)
                                throws IOException
Description copied from class: ServerSocketFactory
Returns a server socket which uses only the specified network interface on the local host, is bound to a the specified port, and uses the specified connection backlog. The socket is configured with the socket options (such as accept timeout) given to this factory.
Overrides:
createServerSocket in class ServerSocketFactory
Tags copied from class: ServerSocketFactory
Parameters:
port - the port to listen to
backlog - how many connections are queued
ifAddress - the network interface address to use

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 server or client 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 and SSLServerSocket APIs provide 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.

setNeedClientAuth

public void setNeedClientAuth(boolean flag)
Set the state of the "client authentication required" flag. The sockets created by this factory inherit a copy of this flag; the default value is false.

Note that this flag is only relevant for SSL server mode; if setUseClientMode(true) then this flag does not apply.

Parameters:
flag - a boolean that specifies whether server sockets should request credentials from SSL clients.