Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
  - Only anonymous cipher suites are used, i.e. `DH_anon` (not supported in this release), or
  - All the server sockets created by this factory will actually be used in SSL client mode, i.e. `setUseClientMode(true)`.

  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD