ice.ssl
Class SSLSocket

java.lang.Object
  java.net.Socket
      ice.ssl.SSLSocket

public final class SSLSocket

extends Socket

This class implements client SSL sockets.

This class implements the following protocols:

• SSL v2 as described in The SSL Protocol
• SSL v3 as described in internet draft 302

It is advised to run the static method init() in the begining of the client application so that the time-consuming initialization can be done before to use this class in a low-priority thread.

Note: This implementation uses the algorithms IC2 and IC4. These algorithms are fully compatible with RC2(TM) and RC4(TM) respectively. The names RC2 and RC4 are trademarks of RSA Data Security, Inc.

Author:

Alexey Goloshubin, Jerome Bugnet

Field Summary

static int	ALL_CERTIFICATES Triggers an event for each received certificate
static int	ERROR_CERTIFICATES Triggers an event for certificates with errors
static int	NO_CERTIFICATES Never triggers an event
static int	SSL_2_0 SSL V2.0 mask
static int	SSL_3_0 SSL V3.0 mask
static int	SSL2_DES_192_EDE3_CBC_WITH_MD5
static int	SSL2_DES_64_CBC_WITH_MD5
static int	SSL2_IC2_128_CBC_EXPORT40_WITH_MD5
static int	SSL2_IC2_128_CBC_WITH_MD5
static int	SSL2_IC4_128_EXPORT40_WITH_MD5
static int	SSL2_IC4_128_WITH_MD5
static int	SSL3_NULL_WITH_NULL_NULL
static int	SSL3_RSA_EXPORT_WITH_DES40_CBC_SHA
static int	SSL3_RSA_EXPORT_WITH_IC2_CBC_40_MD5
static int	SSL3_RSA_EXPORT_WITH_IC4_40_MD5
static int	SSL3_RSA_WITH_3DES_EDE_CBC_SHA
static int	SSL3_RSA_WITH_DES_CBC_SHA
static int	SSL3_RSA_WITH_IC4_128_MD5
static int	SSL3_RSA_WITH_IC4_128_SHA
static int	SSL3_RSA_WITH_NULL_MD5
static int	SSL3_RSA_WITH_NULL_SHA
static DataStorage	storage Set the data storage used to load and store per-user data
static String	VERSION

Constructor Summary

SSLSocket(InetAddress address, int port)
Creates a stream SSL socket and connects it to the specified port number at the specified IP address.

SSLSocket(InetAddress address, int port, InetAddress localAddr, int localPort)
Creates a SSL socket and connects it to the specified remote address on the specified remote port.

SSLSocket(Socket s, String target)
Creates a stream SSL socket from the provided plain socket.

SSLSocket(String host, int port)
Creates a stream SSL socket and connects it to the specified port number on the named host.

SSLSocket(String host, int port, InetAddress localAddr, int localPort)
Creates a SSL socket and connects it to the specified remote host on the specified remote port.

Method Summary

void	close() Closes this socket.
static CertificateListener	getBlockingCertificateListener() Deprecated.
static int	getCertEvents() Returns which event family will trigger a CertificateEvent and block the socket flow.
protected static CertificateCallback	getCertificateCallback() Returns the current certificate callback
CertificateManager	getCertificateManager() Return the certificate manager for this SSLSocket connection.
static int[]	getCipherSuiteList() Retrieve the current cipher suite list for SSL version 3.
static int[]	getCipherSuiteListV2() Retrieve the current cipher suite list for SSL version 2.
static int[]	getCompressionMethodList() Gets the compression method list.
InetAddress	getInetAddress()
InputStream	getInputStream() Returns an input stream for this socket.
OutputStream	getOutputStream() Returns an output stream for this socket.
static int	getProtocols() Returns which protocols are supported by all SSLSocket objects.
static int[]	getSupportedCipherSuiteList() Retrieve the list of cipher suites supported in this implementation for SSL version 3.
static int[]	getSupportedCipherSuiteListV2() Retrieve the list of cipher suites supported in this implementation for SSL version 2.
String	getTargetHostName() Get the name of the host this socket is connected to.
static ServerCertificateList	getTrustedCACertList() Gets the current trusted CA's certificate list.
static ServerCertificateList	getTrustedSiteCertList() Gets the current trusted web site certificate list.
static boolean	getUseSecureRandom() Returns wether or not a secure random is currently used.
static void	init() Does some general initialization that are time consuming.
static void	removeBlockingCertificateListener(CertificateListener cl) Deprecated.
static void	removeCertificateCallback(CertificateCallback ccb) Removes the current certificate certificate callback.
static void	setBlockingCertificateListener(CertificateListener cl) Deprecated.
static void	setCertEvents(int whenEvents) Deprecated.
static void	setCertificateCallback(CertificateCallback ccb) Installs a certificate callback implementing the CertificateCallback interface
void	setCertificateManager(CertificateManager cm) Set a sertificate manager for this socket connection
static void	setCipherSuiteList(int[] cipherSuites) Sets the acceptable cipher suite for SSL 3.0.
static void	setCipherSuiteListV2(int[] cipherSuites) Sets the acceptable cipher suite for SSL 2.0.
static void	setCompressionMethodList(int[] compressionMethods) Sets the compression method list.
static void	setDataStorage(DataStorage datastore)
static void	setProtocols(int protocols) Defines which protocols are supported by all SSLSocket objects.
static void	setTrustedCACertList(ServerCertificateList scl) Sets the trusted CA's certificate list and dicards the previous list.
static void	setTrustedSiteCertList(ServerCertificateList scl) Sets the trusted web site certificate list and dicards the previous list.
static void	setUseSecureRandom(boolean secure) Set wether to use or not a secure random.

Methods inherited from class java.net.Socket

bind, connect, connect, getChannel, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERSION

public static final String VERSION

See Also:

Constant Field Values

SSL_2_0

public static final int SSL_2_0

SSL V2.0 mask

See Also:

Constant Field Values

SSL_3_0

public static final int SSL_3_0

SSL V3.0 mask

See Also:

Constant Field Values

ALL_CERTIFICATES

public static final int ALL_CERTIFICATES

Triggers an event for each received certificate

See Also:

Constant Field Values

ERROR_CERTIFICATES

public static final int ERROR_CERTIFICATES

Triggers an event for certificates with errors

See Also:

Constant Field Values

NO_CERTIFICATES

public static final int NO_CERTIFICATES

Never triggers an event

See Also:

Constant Field Values

SSL3_NULL_WITH_NULL_NULL

public static final int SSL3_NULL_WITH_NULL_NULL

See Also:

Constant Field Values

SSL3_RSA_WITH_NULL_MD5

public static final int SSL3_RSA_WITH_NULL_MD5

See Also:

Constant Field Values

SSL3_RSA_WITH_NULL_SHA

public static final int SSL3_RSA_WITH_NULL_SHA

See Also:

Constant Field Values

SSL3_RSA_EXPORT_WITH_IC4_40_MD5

public static final int SSL3_RSA_EXPORT_WITH_IC4_40_MD5

See Also:

Constant Field Values

SSL3_RSA_WITH_IC4_128_MD5

public static final int SSL3_RSA_WITH_IC4_128_MD5

See Also:

Constant Field Values

SSL3_RSA_WITH_IC4_128_SHA

public static final int SSL3_RSA_WITH_IC4_128_SHA

See Also:

Constant Field Values

SSL3_RSA_EXPORT_WITH_IC2_CBC_40_MD5

public static final int SSL3_RSA_EXPORT_WITH_IC2_CBC_40_MD5

See Also:

Constant Field Values

SSL3_RSA_EXPORT_WITH_DES40_CBC_SHA

public static final int SSL3_RSA_EXPORT_WITH_DES40_CBC_SHA

See Also:

Constant Field Values

SSL3_RSA_WITH_DES_CBC_SHA

public static final int SSL3_RSA_WITH_DES_CBC_SHA

See Also:

Constant Field Values

SSL3_RSA_WITH_3DES_EDE_CBC_SHA

public static final int SSL3_RSA_WITH_3DES_EDE_CBC_SHA

See Also:

Constant Field Values

SSL2_IC4_128_WITH_MD5

public static final int SSL2_IC4_128_WITH_MD5

See Also:

Constant Field Values

SSL2_IC4_128_EXPORT40_WITH_MD5

public static final int SSL2_IC4_128_EXPORT40_WITH_MD5

See Also:

Constant Field Values

SSL2_IC2_128_CBC_WITH_MD5

public static final int SSL2_IC2_128_CBC_WITH_MD5

See Also:

Constant Field Values

SSL2_IC2_128_CBC_EXPORT40_WITH_MD5

public static final int SSL2_IC2_128_CBC_EXPORT40_WITH_MD5

See Also:

Constant Field Values

SSL2_DES_64_CBC_WITH_MD5

public static final int SSL2_DES_64_CBC_WITH_MD5

See Also:

Constant Field Values

SSL2_DES_192_EDE3_CBC_WITH_MD5

public static final int SSL2_DES_192_EDE3_CBC_WITH_MD5

See Also:

Constant Field Values

storage

public static DataStorage storage

Set the data storage used to load and store per-user data

Constructor Detail

SSLSocket

public SSLSocket(String host,
                 int port)
          throws UnknownHostException,
                 IOException

Creates a stream SSL socket and connects it to the specified port number on the named host.

If the application has specified a server socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

host - the host name.

port - the port number.

Throws:

IOException - if an I/O error occurs when creating the socket.

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

UnknownHostException

See Also:

init()

SSLSocket

public SSLSocket(InetAddress address,
                 int port)
          throws IOException

Creates a stream SSL socket and connects it to the specified port number at the specified IP address.

If the application has specified a socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

address - the IP address.

port - the port number.

Throws:

IOException - if an I/O error occurs when creating the socket.

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

See Also:

init()

SSLSocket

public SSLSocket(String host,
                 int port,
                 InetAddress localAddr,
                 int localPort)
          throws IOException

Creates a SSL socket and connects it to the specified remote host on the specified remote port. The Socket will also bind() to the local address and port supplied.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

host - the name of the remote host

port - the remote port

localAddr - the local address the socket is bound to

localPort - the local port the socket is bound to

Throws:

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

IOException

See Also:

init()

SSLSocket

public SSLSocket(InetAddress address,
                 int port,
                 InetAddress localAddr,
                 int localPort)
          throws IOException

Creates a SSL socket and connects it to the specified remote address on the specified remote port. The Socket will also bind() to the local address and port supplied.

If there is a security manager, its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

Parameters:

address - the remote address

port - the remote port

localAddr - the local address the socket is bound to

localPort - the local port the socket is bound to

Throws:

SecurityException - if a security manager exists and its checkConnect method doesn't allow the operation.

IOException

See Also:

init()

SSLSocket

public SSLSocket(Socket s,
                 String target)
          throws IOException

Creates a stream SSL socket from the provided plain socket. The provided socket MUST be connected to a remote server. If used for tunneling proxies you can also provide the hostname of the target host which will be used to certificate verification.

Parameters:

s - The socket SSLsocket should use.

target - name of the target host or null.

See Also:

init()

Method Detail

init

public static void init()

Does some general initialization that are time consuming.

It is advised to run this method in the begining of the client application so that the initialization can be done before to use this class in a low-priority thread. This method is anyway called by the constructor and thus is not mandatory.

Among other things, the SecureRandom seeding is made by calling this method.

Since:

ICEsecure 1.1

See Also:

setUseSecureRandom(boolean)

getInetAddress

public InetAddress getInetAddress()

getTargetHostName

public String getTargetHostName()

Get the name of the host this socket is connected to. Note that in case of proxies this may not be the same name as getInetAddress().getHostName().

getInputStream

public InputStream getInputStream()
                           throws IOException

Returns an input stream for this socket.

Returns:

an input stream for reading bytes from this socket.

Throws:

IOException - if an I/O error occurs when creating the input stream.

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Returns an output stream for this socket.

Returns:

an output stream for writing bytes to this socket.

Throws:

IOException - if an I/O error occurs when creating the output stream.

close

public void close()
           throws IOException

Closes this socket. This method tries to notify the server before closing.

Throws:

IOException - if an I/O error occurs when closing this socket.

setCipherSuiteList

public static void setCipherSuiteList(int[] cipherSuites)
                               throws IllegalArgumentException

Sets the acceptable cipher suite for SSL 3.0. The parameter must be an array of one or several of the following values:

• SSL3_NULL_WITH_NULL_NULL
• SSL3_RSA_WITH_NULL_MD5
• SSL3_RSA_WITH_NULL_SHA
• SSL3_RSA_EXPORT_WITH_IC4_40_MD5
• SSL3_RSA_WITH_IC4_128_MD5
• SSL3_RSA_WITH_IC4_128_SHA
• SSL3_RSA_EXPORT_WITH_IC2_CBC_40_MD5
• SSL3_RSA_EXPORT_WITH_DES40_CBC_SHA
• SSL3_RSA_WITH_DES_CBC_SHA
• SSL3_RSA_WITH_3DES_EDE_CBC_SHA

This list is ordered, with the most prefered cipher suite first.
In chosing the cipher suites and their order please note the following facts:

• the suites containing the word NULL do not provide security of transaction. In normal application they are not adviced for use.
• always put the EXPORT suites at the end because they provide less security. They are necessary if you want to connect on a server situated outside Northern Amercia but that uses a SSL implementation developed in the US.
• MD5 is believed to be more secure than SHA. They both provide a good security anyway.

Throws:

IllegalArgumentException - if one of the suite of the list is not supported

Since:

ICEsecure 1.1

getCipherSuiteList

public static int[] getCipherSuiteList()

Retrieve the current cipher suite list for SSL version 3.

Since:

ICEsecure 1.1

getSupportedCipherSuiteList

public static int[] getSupportedCipherSuiteList()

Retrieve the list of cipher suites supported in this implementation for SSL version 3.

Since:

ICEsecure 1.1

setCipherSuiteListV2

public static void setCipherSuiteListV2(int[] cipherSuites)
                                 throws IllegalArgumentException

Sets the acceptable cipher suite for SSL 2.0. The parameter must be an array of one or several of the following values:

• SSL2_IC4_128_WITH_MD5
• SSL2_IC4_128_EXPORT40_WITH_MD5
• SSL2_IC2_128_CBC_WITH_MD5
• SSL2_IC2_128_CBC_EXPORT40_WITH_MD5
• SSL2_DES_64_CBC_WITH_MD5
• SSL2_DES_192_EDE3_CBC_WITH_MD5

This list is ordered, with the most prefered cipher suite first.
In chosing the cipher suites and their order please note the following fact:

• always put the EXPORT40 suites at the end because they provide less security. They are necessary if you want to connect on a server situated outside Northern Amercia but that uses a SSL implementation developed in the US.

Throws:

IllegalArgumentException - if one of the suite of the list is not supported

Since:

ICEsecure 1.1

See Also:

getSupportedCipherSuiteListV2()

getCipherSuiteListV2

public static int[] getCipherSuiteListV2()

Retrieve the current cipher suite list for SSL version 2.

Since:

ICEsecure 1.1

See Also:

setCipherSuiteListV2(int[])

getSupportedCipherSuiteListV2

public static int[] getSupportedCipherSuiteListV2()

Retrieve the list of cipher suites supported in this implementation for SSL version 2.

Since:

ICEsecure 1.1

setCompressionMethodList

public static void setCompressionMethodList(int[] compressionMethods)

Sets the compression method list. SSL standard currently does not specify any compression method. Because no compression method is specified for the SSL protocol, this method has currently no effect but is included for later protocol update.

Since:

ICEsecure 1.1

getCompressionMethodList

public static int[] getCompressionMethodList()

Gets the compression method list.

Since:

ICEsecure 1.1

See Also:

setCompressionMethodList(int[])

setProtocols

public static void setProtocols(int protocols)

Defines which protocols are supported by all SSLSocket objects. Possible arguments are:

• SSL_2_0
• SSL_3_0
• A combination of the above.

Default is all protocols: SSL_2_0 | SSL_3_0.

Since:

ICEsecure 1.1

getProtocols

public static int getProtocols()

Returns which protocols are supported by all SSLSocket objects.

Since:

ICEsecure 1.1

See Also:

setProtocols(int)

setUseSecureRandom

public static void setUseSecureRandom(boolean secure)

Set wether to use or not a secure random. Default is of course true. Use this method for testing prupose only, if you find that initialization delay of the secureRandom is too long.

Setting this method to false makes the connection unsecure.

Since:

ICEsecure 1.1

See Also:

init()

setDataStorage

public static void setDataStorage(DataStorage datastore)

getUseSecureRandom

public static boolean getUseSecureRandom()

Returns wether or not a secure random is currently used. Default is of course true.

Since:

ICEsecure 1.1

See Also:

setUseSecureRandom(boolean), init()

getTrustedCACertList

public static ServerCertificateList getTrustedCACertList()

Gets the current trusted CA's certificate list.

Since:

ICEsecure 1.1

setTrustedCACertList

public static void setTrustedCACertList(ServerCertificateList scl)

Sets the trusted CA's certificate list and dicards the previous list.
This change is valid for one Java session only. The default trusted CA's certificate list is loaded at each new session. Client applications should manage the trusted CA's certificate list with the methods save() and load() of ServerCertificateList.

Parameters:

scl - the server certificate list or null for removing the current list

Since:

ICEsecure 1.1

getTrustedSiteCertList

public static ServerCertificateList getTrustedSiteCertList()

Gets the current trusted web site certificate list. This represents certificates that will be trusted even if the Certificate Authority that certify them is not trusted. Other certificate errors such as overdue date or site not matching certificate's subject will still be generated.

Since:

ICEsecure 1.1

setTrustedSiteCertList

public static void setTrustedSiteCertList(ServerCertificateList scl)

Sets the trusted web site certificate list and dicards the previous list. The list represents certificates that will be trusted even if the Certificate Authority that certify them is not trusted. Other certificate errors such as overdue date or site not matching certificate's subject will still be generated.
This change is valid for one Java session only. An empty list is set at each new session. Client applications should manage the trusted web site certificate list with the methods save() and restoreList() of ServerCertificateList.

Parameters:

scl - the server certificate list or null for removing the current list

Since:

ICEsecure 1.1

setCertificateCallback

public static void setCertificateCallback(CertificateCallback ccb)

Installs a certificate callback implementing the CertificateCallback interface

getCertificateCallback

protected static CertificateCallback getCertificateCallback()

Returns the current certificate callback

removeCertificateCallback

public static void removeCertificateCallback(CertificateCallback ccb)

Removes the current certificate certificate callback.

setCertificateManager

public void setCertificateManager(CertificateManager cm)

Set a sertificate manager for this socket connection

getCertificateManager

public CertificateManager getCertificateManager()

Return the certificate manager for this SSLSocket connection. If the SSLSocket don't have a per-connection certificate manager, return the static certificate mamager in the CertificateManager class

setBlockingCertificateListener

public static void setBlockingCertificateListener(CertificateListener cl)

Deprecated.

Adds a unique certificateListener.

Throws:

IllegalArgumentException - if a listener is already set.

Since:

ICEsecure 1.1

removeBlockingCertificateListener

public static void removeBlockingCertificateListener(CertificateListener cl)

Deprecated.

Removes the unique certificateListener if it is set. The CertificateListener must be specified to avoid removing unknown listener.

Since:

ICEsecure 1.1

See Also:

getBlockingCertificateListener()

getBlockingCertificateListener

public static CertificateListener getBlockingCertificateListener()

Deprecated.

Gets the unique certificateListener.

Returns:

the unique listener set with setBlockingCertificateListener() or null if no one is set.

Since:

ICEsecure 1.1

setCertEvents

public static void setCertEvents(int whenEvents)

Deprecated.

Defines which event family will trigger a CertificateEvent and block the socket flow. Possible arguments are:

• ALL_CERTIFICATES triggers an event for all received certificates.
• ERROR_CERTIFICATES triggers an event only for certificates containing errors.
• NO_CERTIFICATES never triggers an event. An IOException is thrown when an erronous certificates is received.

Default is ERROR_CERTIFICATES. If no CertificateListener is set or if null is set, then an IOException is thrown when an erronous certificates is received.

Since:

ICEsecure 1.1

getCertEvents

public static int getCertEvents()

Returns which event family will trigger a CertificateEvent and block the socket flow. Possible arguments are:

• ALL_CERTIFICATES triggers an event for all received certificates.
• ERROR_CERTIFICATES triggers an event only for certificates containing errors.
• NO_CERTIFICATES never triggers an event.

Default is ERROR_CERTIFICATES. If no CertificateListener is set or if null is set, then an IOException is thrown and the connection is closed when an erronous certificates is received. If NO_CERTIFICATE is set, an IOException is thrown when an erronous certificates is received, but the connection is not closed and will continue normally. You should close it manually if you wish.

Since:

ICEsecure 1.1