de.tu_darmstadt.sp.ssl
Class SSLeaySocketFactory

java.lang.Object
  |
  +--javax.net.SocketFactory
        |
        +--javax.net.ssl.SSLSocketFactory
              |
              +--de.tu_darmstadt.sp.ssl.SSLeaySocketFactory
Direct Known Subclasses:
RMISSLSocketFactory

public class SSLeaySocketFactory
extends SSLSocketFactory
implements java.io.Serializable

Class SSLeaySocketFactory creates SSLeaySockets. Each SSLeaySocketFactory uses exactly one SSLeaySessionContext. Every socket created using this factory will use this SSLeaySessionContext for the session corresponding to its own connection. The default ciphers which are going to be used by the sockets created by this factory are actually default ciphers of the SSLeaySessionContext of this factory.

Instantiation of the Session Context

The SSLeaySessionContext is instantiated "lazy", namely in the first call of one of the following methods:

This property is very useful when serializing and deserializing SSLeaySocketObject factories. If the context would have been initialized upon creation, de deserialization of a factory would work only in the presence of cryptographic information, like certificate files. Using "lazy" instantiation for the used context means the context (and thus the capability of produces sockets) will be created only when somebody realy wants to use a factory object for socket creation.

The methods specified above will fail by throwing a SSLException if the necessary information for setting up the context is not there. Socket creation will fail in one of the two cases:

  1. The CA information is not present or incomplete, so the SSLeaySessionContext could not verify a peer.
  2. If the system property iti.ssl.clientIdentityRequired is true, but neither of the environment variables or system properties controlling the user identity are defined (See SSLeaySessionContext). In this case, a SSLeayRuntimeException will be thrown. For any other value of the property, no exception will be raised. By default, the iti.ssl.clientIdentityRequired property has the value false.

    Secure connections can be created even if this information is not available, but the peer will not be able to check our identity. This exception is catchable; the new socket factory will create sockets. false.

Extending and customizing SSLeaySocketFactory

Using the setSSLPolicy method you can specify the modes of the connections to be established or decide whether to start or not a SSL handshake in the createSocket methods. This method is a template method, which you can redefine in subclasses of this class in order to specify different policies for the sockets of this factory. setSSLPolicy is called after creating a socket in all createSocket methods.

SSLeaySocketFactories together with SSLeaySockets are the means to specify the socket security on a given platform. Some applications need to extend the current SSLSocket implemtation (which is SSLeaySocket). To help extensions of this factory use other socket types than the default, the protected method setSocketPrototype is provided. Used in a constructor, sets the type of sockets the factory will produce.

Version:
$Revision: 1.7 $
Author:
Andrei Popovici
See Also:
Serialized Form

Field Summary
protected  SSLeaySessionContext context
           
protected  java.lang.Class socketType
           
 
Constructor Summary
SSLeaySocketFactory()
          Create a new SSLeaySocketFactory using a new SSLeaySessionContext.
SSLeaySocketFactory(SSLeaySessionContext context)
          Create a new SSLeaySocketFactory using context as the SSLeaySessionContext for all connections initiated by this factory.
 
Method Summary
 java.net.Socket createSocket(java.net.InetAddress address, int port)
          Returns a socket connected to a ServerSocket at the specified network address and port.
 java.net.Socket createSocket(java.net.InetAddress address, int port, java.net.InetAddress clientAddr, int clientPort)
          Returns a socket connected to a ServerSocket at the specified network address and port.
 java.net.Socket createSocket(java.lang.String host, int port)
          Returns a socket connected to a ServerSocket on the named host, at the given port.
 java.net.Socket createSocket(java.lang.String host, int port, java.net.InetAddress clientAddr, int clientPort)
          Returns a socket connected to a ServerSocket on the named host, at the given port.
 java.lang.String[] getDefaultCipherSuites()
          Returns the names of the cipher suites which could be enabled for use on an SSL connection created by this factory.
 java.lang.Class getSocketPrototypeClass()
          Return the type of sockets created by this factory.
 java.lang.String[] getSupportedCipherSuites()
          Returns the list of cipher suites which are enabled by default.
 void setDefaultCipherSuites(java.lang.String[] ciphers)
          Specify the list of cipher suites which are enabled by default.
protected  void setSocketPrototype(SSLeaySocket proto)
          Specify the type of sockets (class) returned by the createSocket methods.
protected  void setSSLPolicy(SSLSocket s)
          This is a template method called in the createSocket methods after creating and connecting a SSLeaySocket.
 
Methods inherited from class javax.net.ssl.SSLSocketFactory
getDefault, setDefault
 
Methods inherited from class javax.net.SocketFactory
setDefault
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

context

protected transient SSLeaySessionContext context

socketType

protected java.lang.Class socketType
Constructor Detail

SSLeaySocketFactory

public SSLeaySocketFactory(SSLeaySessionContext context)
Create a new SSLeaySocketFactory using context as the SSLeaySessionContext for all connections initiated by this factory.
Parameters:
context - the SessionConxtext of all connections of this factory

SSLeaySocketFactory

public SSLeaySocketFactory()
Create a new SSLeaySocketFactory using a new SSLeaySessionContext. The instantiation of the factory object is lazy.
Throws:
SSLeayRuntimeException - no identity information
java.lang.Error - no CA information
Method Detail

createSocket

public java.net.Socket createSocket(java.lang.String host,
                                    int port)
                             throws java.net.UnknownHostException,
                                    java.io.IOException
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.

By default, the class of the returned socket is SSLeaySocket. Subclasses can tune the type of socket they return using the setSocketPrototype method.

Parameters:
host - the host name.
port - the port number.
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLException - could not create the session context for this factory
SSLeayIdentityException - could not set the identity of the user
Overrides:
createSocket in class SSLSocketFactory

createSocket

public java.net.Socket createSocket(java.net.InetAddress address,
                                    int port)
                             throws java.io.IOException
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.

By default, the class of the returned socket is SSLeaySocket. Subclasses can tune the type of socket they return using the setSocketPrototype method.

Parameters:
address - the IP address.
port - the port number.
Throws:
java.io.IOException - if the connection can't be established
SSLException - could not create the session context for this factory
SSLeayIdentityException - could not set the identity of the user
Overrides:
createSocket in class SSLSocketFactory

createSocket

public java.net.Socket createSocket(java.lang.String host,
                                    int port,
                                    java.net.InetAddress clientAddr,
                                    int clientPort)
                             throws java.io.IOException,
                                    java.net.UnknownHostException
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.

By default, the class of the returned socket is SSLeaySocket. Subclasses can tune the type of socket they return using the setSocketType method.

Parameters:
host - the name of the remote host
port - the remote port
clientAddr - the local address the socket is bound to
clientPort - the local port the socket is bound to
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLException - could not create the session context for this factory
SSLeayIdentityException - could not set the identity of the user
Overrides:
createSocket in class SSLSocketFactory

createSocket

public java.net.Socket createSocket(java.net.InetAddress address,
                                    int port,
                                    java.net.InetAddress clientAddr,
                                    int clientPort)
                             throws java.io.IOException
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. *

By default, the class of the returned socket is SSLeaySocket. Subclasses can tune the type of socket they return using the setSocketPrototype method.

Parameters:
address - the remote address
port - the remote port
clientAddr - the local address the socket is bound to
clientPort - the local port the socket is bound to
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLException - could not create the session context for this factory
SSLeayIdentityException - could not set the identity of the user
Overrides:
createSocket in class SSLSocketFactory

setSSLPolicy

protected void setSSLPolicy(SSLSocket s)
                     throws java.io.IOException
This is a template method called in the createSocket methods after creating and connecting a SSLeaySocket. Connecting a SSLeaySocket does not necessarily imply a SSL handshake. Without a Handshake, no communication with the peer is possible. The handshake can be initiated either explicitly by calling the startHandshake method, or implicitly by the time either of the getInputStream or getOutputStream are called.

By default, this template method performs no configuration of the created sockets. The created SSLeaySockets have the same characteristics as if they would have been created using their constructors.

Subclasses of SSLeaySocketFactory can redefine this method to specify alternative SSL configuration policies. SSL policies can be spefified using methods of SSLSocket i.e.

If you decide to initiate the handshake as part of the policy configuration, make sure this is the last action of your setSSLSocketPolicy method.

The default action of this method is to start a handshake.

Throws:
java.io.IOException - couldn't set the SSL Policy

setDefaultCipherSuites

public void setDefaultCipherSuites(java.lang.String[] ciphers)
Specify the list of cipher suites which are enabled by default. 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.
Parameters:
ciphers - String array consisting of the new default ciphers, in order of their preference

getSupportedCipherSuites

public java.lang.String[] getSupportedCipherSuites()
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.
Returns:
a String representing the supported ciphers
Overrides:
getSupportedCipherSuites in class SSLSocketFactory

getDefaultCipherSuites

public java.lang.String[] getDefaultCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection created by this factory. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites are useful in specialized applications.
Returns:
a String array representing the default ciphers, in order of their preference
Overrides:
getDefaultCipherSuites in class SSLSocketFactory

setSocketPrototype

protected void setSocketPrototype(SSLeaySocket proto)
Specify the type of sockets (class) returned by the createSocket methods. The constructors for proto's class have to be a superset of the SSLeaySocket's constructors.
Parameters:
proto - a prototype for the sockets created by the createSocket methods
Throws:
java.lang.IllegalArgumentException - proto is null

getSocketPrototypeClass

public java.lang.Class getSocketPrototypeClass()
Return the type of sockets created by this factory. The returned Class object will be a subclass of SSLeaySocket.
Returns:
the class of the objects returned by createSocket