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

  - Only anonymous cipher suites are used, i.e. `DH_anon` (not supported in this release), or
  - All the sockets created by this factory will actually be used in SSL server mode, i.e. `setUseClientMode(false)`.
  Conversely, the second and third parameters only need to be non-`null` if
  - The client sockets created by this factory may communicate with SSL servers that require client authentication, or
  - One or more of the sockets created by this factory will actually be used in SSL server mode, i.e. `setUseClientMode(false)`.
  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.

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