de.tu_darmstadt.sp.ssl
Class SSLeaySocket

java.lang.Object
  |
  +--java.net.Socket
        |
        +--javax.net.ssl.SSLSocket
              |
              +--de.tu_darmstadt.sp.ssl.SSLeaySocket
Direct Known Subclasses:
RMISSLSocket

public class SSLeaySocket
extends SSLSocket

Class SSLeaySocket implements Sun's abstract SSLSocket definition using the SSLeay package. SSLeaySockets can be created either connected or unconnected. connected means that there exists a connection on the transport layer.

After creation (connected or unconnected) SSLeaySocket objects have an own SSLeayHandle object. The handle will actually perform the SSL protocol for this object. The SSL protocol can be initiated or restarted using the startHandshake method. For the startHandshake method to succeed, a socket has to be connected. Therefore, the initiation of transport layer connection is mandatory before handshake start for unconnected sockets.

The handshake start is supposed to be performed in the factory which creates a socket. If this is not the case, the connection will be initiated when the communication starts, this is, by the first use of the getInputStream or getOutputStream methods.

SSLeaySocket require by default peer authentication and use the client mode.

Version:
$Revision: 1.6 $
Author:
Andrei Popovici

Field Summary
protected  SSLeaySessionContext context
           
protected  SSLeayHandle handle
           
 
Constructor Summary
protected SSLeaySocket(java.net.InetAddress address, int port, java.net.InetAddress clientAddr, int clientPort, SSLeaySessionContext ctx)
          Returns a socket connected to a ServerSocket on the named host, at the given port.
  SSLeaySocket(java.net.InetAddress address, int port, SSLeaySessionContext ctx)
          Constructs a TCP connection to a server at a specified address and port.This (usually) acts as the SSL client, but SSL policy is usually controlled by the corresponding factory.
  SSLeaySocket(SSLeaySessionContext ctx)
          Create an unconnected socket using the client mode.
  SSLeaySocket(java.lang.String host, int port, java.net.InetAddress clientAddr, int clientPort, SSLeaySessionContext ctx)
          Constructs an SSL connection to a named host at a specified port, binding the client side of the connection a given address and port.
  SSLeaySocket(java.lang.String host, int port, SSLeaySessionContext ctx)
          Constructs a TCP connection to a named host at a specified port.
 
Method Summary
 void addHandshakeCompletedListener(HandshakeCompletedListener listener)
           
 void close()
          Close the SSL connection and this socket .
 java.lang.String[] getEnabledCipherSuites()
          Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
 boolean getEnableSessionCreation()
          Returns true if new SSL sessions may be established by this socket.
 java.io.InputStream getInputStream()
          Returns an input stream for this socket.
 boolean getNeedClientAuth()
          Returns true if the socket will require client authentication.
 java.io.OutputStream getOutputStream()
          Returns an output stream for this socket.
 java.lang.String getPeerName()
          Return peer Distinguished name.
 SSLSession getSession()
          Returns the the SSL Session in use by this connection.
 java.lang.String[] getSupportedCipherSuites()
          Returns the names of the cipher suites which could be enabled for use on an SSL connection.
 boolean getUseClientMode()
          Returns true if the socket is set to use client mode in its first handshake.
 void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
          Removes a previously registered handshake completion listener.
 void setEnabledCipherSuites(java.lang.String[] ciphers)
          Controls which particular cipher suites are enabled for use on this connection.
 void setEnableSessionCreation(boolean flag)
          Controls whether new SSL sessions may be established by this socket.
 void setNeedClientAuth(boolean flag)
          Configures the socket to require client authentication.
 void setUseClientMode(boolean mode)
          Configures the socket to use client (or server) mode in its first handshake.
 void startHandshake()
          Starts an SSL handshake on this connection.
 java.lang.String toString()
          Return all information about this SSL socket in string Format:
 
Methods inherited from class java.net.Socket
getInetAddress, getLocalAddress, getLocalPort, getPort, getReceiveBufferSize, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, setReceiveBufferSize, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

handle

protected SSLeayHandle handle

context

protected SSLeaySessionContext context
Constructor Detail

SSLeaySocket

public SSLeaySocket(SSLeaySessionContext ctx)
Create an unconnected socket using the client mode. Though unconnected, SSL options like preferred ciphers a.o. can be specified. If the ctx parameter is null, the socket cannot be used for communication. A SSLeaySocket created with a null ctx parameter can be used to specify the prototype socket a factory should produce.
Parameters:
ctx - the SSLeaySessionContext for the session(s) used by this connection. A null value yields a prototype socket, unable to communicate.
Throws:
SSLeayRuntimeException - if no SSLeayHandle could be created

SSLeaySocket

public SSLeaySocket(java.lang.String host,
                    int port,
                    SSLeaySessionContext ctx)
             throws java.net.UnknownHostException,
                    java.io.IOException
Constructs a TCP connection to a named host at a specified port. This (tipically) acts as the SSL client, but SSL policy is usually controlled by the corresponding factory. The constructor does not start the handshake.
Parameters:
host - the host name.
port - the port number.
ctx - the SSLeaySessionContext for the session(s) used by this connection.
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLeayRuntimeException - if no SSLeayHandle could be created
java.lang.IllegalArgumentException - ctx is null

SSLeaySocket

public SSLeaySocket(java.net.InetAddress address,
                    int port,
                    SSLeaySessionContext ctx)
             throws java.io.IOException
Constructs a TCP connection to a server at a specified address and port.This (usually) acts as the SSL client, but SSL policy is usually controlled by the corresponding factory. The constructor does not start the handshake.
Parameters:
address - the IP address.
port - the port number.
ctx - the SSLeaySessionContext for the session(s) used by this connection.
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLeayRuntimeException - if no SSLeayHandle could be created
java.lang.IllegalArgumentException - ctx is null

SSLeaySocket

public SSLeaySocket(java.lang.String host,
                    int port,
                    java.net.InetAddress clientAddr,
                    int clientPort,
                    SSLeaySessionContext ctx)
             throws java.io.IOException
Constructs an SSL connection to a named host at a specified port, binding the client side of the connection a given address and port. This typically acts as the SSL client, but SSL policy is usually controlled by the corresponding factory. The constructor does not start the handshake.
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
ctx - the SSLeaySessionContext for the session(s) used by this connection.
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLeayRuntimeException - if no SSLeayHandle could be created
java.lang.IllegalArgumentException - ctx is null

SSLeaySocket

protected SSLeaySocket(java.net.InetAddress address,
                       int port,
                       java.net.InetAddress clientAddr,
                       int clientPort,
                       SSLeaySessionContext ctx)
                throws java.io.IOException
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.
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
ctx - the SSLeaySessionContext for the session(s) used by this connection.
Throws:
java.io.IOException - if an I/O error occurs when creating the socket.
SSLeayRuntimeException - if no SSLeayHandle could be created.
java.lang.IllegalArgumentException - ctx is null
Method Detail

getSession

public SSLSession getSession()
Returns the the SSL Session in use by this connection. These can be long lived, and frequently correspond to an entire login session for some user. The session specifies a particular cipher suite which is being actively used by all connections in that session, as well as the identities of the session's client and server.
Overrides:
getSession in class SSLSocket

close

public void close()
           throws java.io.IOException
Close the SSL connection and this socket .
Throws:
java.io.IOException - if an I/O error occurs when closing this socket.
Overrides:
close in class java.net.Socket

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Returns an input stream for this socket. The input stream uses the underlying SSL session. If there is no SSL session, a startHandshake will be performed.
Returns:
an input stream for reading bytes from this socket
Throws:
java.io.IOException - if an I/O error occurs when creating the input stream or the underlying SSLHandle is not properly initialized and connected.
Overrides:
getInputStream in class java.net.Socket

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
Returns an output stream for this socket. The output stream uses the underlying SSL session. If there is no SSL session, a startHandshake will be performed.
Returns:
an output stream for writing bytes to this socket
Throws:
java.io.IOException - if an I/O error occurs when creating the output stream or the underlying SSLHandle is not properly initialized and connected.
Overrides:
getOutputStream in class java.net.Socket

setUseClientMode

public void setUseClientMode(boolean mode)
Configures the socket to use client (or server) mode in its first handshake. Calling this method makes sense only if the socket was created with the SSLSocket() constructor.
Parameters:
mode - if true connect -- client mode, else accept connection
Overrides:
setUseClientMode in class SSLSocket

getUseClientMode

public boolean getUseClientMode()
Returns true if the socket is set to use client mode in its first handshake.
Returns:
true if the socket should start its first handshake in "client" mode
Overrides:
getUseClientMode in class SSLSocket

startHandshake

public void startHandshake()
                    throws java.io.IOException,
                           SSLException
Starts an SSL handshake on this connection. The current implementation does not support this operation except for the first handshake. This means the initial handshake will be performed according to the current useClientMode mode. For further calls to this method the behavior is not specified. (for the moment)
Overrides:
startHandshake in class SSLSocket

getNeedClientAuth

public boolean getNeedClientAuth()
Returns true if the socket will require client authentication. The socket must not necessarily be a server socket. This method returns the peer verification policy,
Returns:
true if the socket will require client authentication
Overrides:
getNeedClientAuth in class SSLSocket

setNeedClientAuth

public void setNeedClientAuth(boolean flag)
Configures the socket to require client authentication. The socket must not necessarily be a server mode socket. This method sets the peer verification policy.
Parameters:
flag - if true authenticate peer during handshake
Overrides:
setNeedClientAuth in class SSLSocket

addHandshakeCompletedListener

public void addHandshakeCompletedListener(HandshakeCompletedListener listener)
Overrides:
addHandshakeCompletedListener in class SSLSocket

removeHandshakeCompletedListener

public void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener.
Parameters:
listener - the listener to be removed
Overrides:
removeHandshakeCompletedListener in class SSLSocket

getSupportedCipherSuites

public java.lang.String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection. 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 suported ciphers
Overrides:
getSupportedCipherSuites in class SSLSocket

getEnabledCipherSuites

public java.lang.String[] getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this connection. When an SSL socket is first created, all enabled cipher suites support a minium quality of service. Thus, in some environments this value might be empty.
Returns:
a String array representing the suported ciphers
Overrides:
getEnabledCipherSuites in class SSLSocket

setEnabledCipherSuites

public void setEnabledCipherSuites(java.lang.String[] ciphers)
                            throws java.lang.IllegalArgumentException
Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by getSupportedCipherSuites() as being supported. Even if a suite has been enabled, it might never be used if no peer supports it, or the requisite certificates (and private keys) are not available.
Parameters:
ciphers - the cipher list to be enabled. If null, use the default ciphers
Throws:
java.lang.IllegalArgumentException - if one of the cipher suites is not supported
Overrides:
setEnabledCipherSuites in class SSLSocket

getPeerName

public java.lang.String getPeerName()
                             throws SSLException
Return peer Distinguished name. If no handshake yet, throw SSLException.
Throws:
SSLException - no handshake yet

setEnableSessionCreation

public void setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this socket. Not implemented yet.
Parameters:
flag - if true,new SSL sessions may be established by this socket
Overrides:
setEnableSessionCreation in class SSLSocket

getEnableSessionCreation

public boolean getEnableSessionCreation()
Returns true if new SSL sessions may be established by this socket. Not implemented yet.
Returns:
true if new SSL sessions may be established by this socket.
Overrides:
getEnableSessionCreation in class SSLSocket

toString

public java.lang.String toString()
Return all information about this SSL socket in string Format:
Overrides:
toString in class java.net.Socket