iaik.security.ssl
Class SSLSocket

java.lang.Object
  extended by java.net.Socket
      extended by iaik.security.ssl.SSLSocket
All Implemented Interfaces:
SSLCommunication

public class SSLSocket
extends java.net.Socket
implements SSLCommunication

This class implements the SSL/TLS transport over Java sockets. It extends java.net.Socket and therefore can be used anywhere in its place making it very easy to secure existing applications. The actual TLS functionality is located in the SSLTransport class, see there for more general documentation.

Note that by default the TLS handshake is automatically started when you call getInputStream() or getOutputStream(). This will be the desired behaviour in most cases, but not when connecting through proxies. In that case you have three options:

See Also:
SSLTransport, Utils.proxyConnect(java.net.InetAddress, int, iaik.security.ssl.SSLContext)

Constructor Summary
SSLSocket(java.net.InetAddress address, int port, java.net.InetAddress localAddr, int localPort, SSLContext context)
          Creates a SSL socket and connects it to the specified remote address on the specified remote port.
SSLSocket(java.net.InetAddress address, int port, SSLContext context)
          Creates a SSL socket and connects it to the specified port number at the specified IP address.
SSLSocket(java.net.InetAddress address, java.lang.String host, int port, java.net.InetAddress localAddr, int localPort, SSLContext context)
          Creates a SSL socket and connects it to the specified remote address on the specified remote port.
SSLSocket(java.net.InetAddress address, java.lang.String host, int port, SSLContext context)
          Creates a SSL socket and connects it to the specified port number at the specified IP address.
SSLSocket(java.net.Socket socket, SSLContext context)
          Creates a SSLSocket from an existing socket.
SSLSocket(java.net.Socket proxySocket, SSLContext context, java.lang.String host, int port)
          Creates a socket layered over an existing socket to a ServerSocket on the named host, at the given port.
SSLSocket(java.lang.String host, int port, java.net.InetAddress localAddr, int localPort, SSLContext context)
          Creates a SSL socket and connects it to the specified remote host on the specified remote port.
SSLSocket(java.lang.String host, int port, SSLContext context)
          Creates a SSL socket and connects it to the specified port number on the named host.
 
Method Summary
 void close()
          Close this SSL socket.
 CipherSuite getActiveCipherSuite()
          Returns the active cipher suite.
 CompressionMethod getActiveCompressionMethod()
          Returns the active compression method.
 ExtensionList getActiveExtensions()
          Gets the active TLS extensions of the current TLS session.
 int getActiveProtocolVersion()
          Return the active SSL protocol version.
 CipherSuite[] getClientSupportedCipherSuites()
          Deprecated. use getPeerSupportedCipherSuiteList()
 CompressionMethod[] getClientSupportedCompressionMethods()
          Deprecated. use getPeerSupportedCompressionMethods()
 SSLContext getContext()
          Returns the SSLContext of this SSLSocket.
 java.net.InetAddress getInetAddress()
          See JDK documentation of java.net.Socket for a description of this method.
 java.io.InputStream getInputStream()
          Returns an input stream for this socket.
 java.net.InetAddress getLocalAddress()
          See JDK documentation of java.net.Socket for a description of this method.
 int getLocalPort()
          See JDK documentation of java.net.Socket for a description of this method.
 java.io.OutputStream getOutputStream()
          Returns an output stream for this socket.
 java.security.cert.X509Certificate[] getPeerCertificateChain()
          Returns the certificate chain sent by the peer or null if the peer has no certificate.
 ExtensionList getPeerExtensions()
          Gets the TLS extension received from the peer.
 CipherSuiteList getPeerSupportedCipherSuiteList()
          Return the list of cipher suites known to be supported by the remote peer.
 CompressionMethod[] getPeerSupportedCompressionMethods()
          Return the compression methods supported by the remote peer.
 int getPort()
          See JDK documentation of java.net.Socket for a description of this method.
 java.lang.String getPSKIdentity()
          Returns the PSK identity used for identifying the pre-shared key or null if no PSK cipher suite is used for the communication.
 Session getSession()
          Returns the currently active Session for this SSLSocket.
 int getSoLinger()
          See JDK documentation of java.net.Socket for a description of this method.
 int getSoTimeout()
          See JDK documentation of java.net.Socket for a description of this method.
 boolean getTcpNoDelay()
          See JDK documentation of java.net.Socket for a description of this method.
 SSLTransport getTransport()
          Get the SSLTransport this socket is talking over.
 boolean getUseClientMode()
          Returns whether or not this socket resides on the client side of the connection.
 void init(java.net.Socket s, SSLContext context, boolean useClientMode)
          Initialize the SSLSocket.
 boolean isServer()
          Deprecated. use getUseClientMode()
 void renegotiate()
          Start a renegotiating SSL handshake.
 void setAutoHandshake(boolean on)
          Can be used to switch off the automatic start of the handshake procedure.
 void setDebugStream(java.io.OutputStream os)
          Enables debugging mode.
 void setDebugStream(java.io.Writer writer)
          Enables debugging mode.
 void setSoLinger(boolean on, int val)
          See JDK documentation of java.net.Socket for a description of this method.
 void setSoTimeout(int timeout)
          See JDK documentation of java.net.Socket for a description of this method.
 void setTcpNoDelay(boolean on)
          See JDK documentation of java.net.Socket for a description of this method.
 void setUseClientMode(boolean mode)
          Select client or server mode for this socket.
 void shutdown()
          Shuts the SSL layer down.
 void startHandshake()
          Start the SSL handshake process.
 
Methods inherited from class java.net.Socket
bind, connect, connect, getChannel, getKeepAlive, getLocalSocketAddress, getOOBInline, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setTrafficClass, shutdownInput, shutdownOutput, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SSLSocket

public SSLSocket(java.net.Socket socket,
                 SSLContext context)
          throws java.io.IOException
Creates a SSLSocket from an existing socket.

Throws:
java.io.IOException

SSLSocket

public SSLSocket(java.lang.String host,
                 int port,
                 SSLContext context)
          throws java.io.IOException,
                 java.net.UnknownHostException
Creates a SSL socket and connects it to the specified port number on the named host.

All properties of this SSLSocket are defined in the SSLContext.

Parameters:
host - the host name.
port - the port number.
context - the SSLContext for the new socket
Throws:
java.io.IOException - if an error occurs when creating the socket
java.net.UnknownHostException

SSLSocket

public SSLSocket(java.net.InetAddress address,
                 int port,
                 SSLContext context)
          throws java.io.IOException
Creates a SSL socket and connects it to the specified port number at the specified IP address.

All properties of this SSLSocket are defined in the SSLContext.

Parameters:
address - the IP address.
port - the port number.
context - the SSLContext for the new socket
Throws:
java.io.IOException - if an error occurs when creating the socket

SSLSocket

public SSLSocket(java.net.InetAddress address,
                 java.lang.String host,
                 int port,
                 SSLContext context)
          throws java.io.IOException
Creates a SSL socket and connects it to the specified port number at the specified IP address.

All properties of this SSLSocket are defined in the SSLContext.

Parameters:
address - the IP address.
host - the host name
port - the port number.
context - the SSLContext for the new socket
Throws:
java.io.IOException - if an error occurs when creating the socket

SSLSocket

public SSLSocket(java.lang.String host,
                 int port,
                 java.net.InetAddress localAddr,
                 int localPort,
                 SSLContext context)
          throws java.io.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.

All properties of this SSLSocket are defined in the SSLContext.

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
context - the SSLContext for the new socket
Throws:
java.io.IOException - if an error occurs when creating the socket

SSLSocket

public SSLSocket(java.net.InetAddress address,
                 int port,
                 java.net.InetAddress localAddr,
                 int localPort,
                 SSLContext context)
          throws java.io.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.

All properties of this SSLSocket are defined in the SSLContext.

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
context - the SSLContext for the new socket
Throws:
java.io.IOException - if an error occurs when creating the socket

SSLSocket

public SSLSocket(java.net.InetAddress address,
                 java.lang.String host,
                 int port,
                 java.net.InetAddress localAddr,
                 int localPort,
                 SSLContext context)
          throws java.io.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.

All properties of this SSLSocket are defined in the SSLContext.

Parameters:
address - the remote address
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
context - the SSLContext for the new socket
Throws:
java.io.IOException - if an error occurs when creating the socket

SSLSocket

public SSLSocket(java.net.Socket proxySocket,
                 SSLContext context,
                 java.lang.String host,
                 int port)
          throws java.io.IOException
Creates 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 information are needed for session caching.

Parameters:
proxySocket - the socket connected to the proxy server
context - the SSLContext for the new socket
host - the name of the logical destination server
port - the port of the logical destination server
Throws:
java.io.IOException
Method Detail

getTransport

public SSLTransport getTransport()
Get the SSLTransport this socket is talking over. May be usefull for application who prefer to use the SSLTransport API.


init

public void init(java.net.Socket s,
                 SSLContext context,
                 boolean useClientMode)
          throws java.io.IOException
Initialize the SSLSocket.

Parameters:
s - the socket to be initialized
context - the SSLContext of this socket
useClientMode - true if client mode should be used
Throws:
java.io.IOException

setUseClientMode

public void setUseClientMode(boolean mode)
                      throws java.io.IOException
Description copied from interface: SSLCommunication
Select client or server mode for this socket. This method can be used to manually select whether we are in the SSL client or server role for this connection. Note that there must be always one client and one server in a connection, the client is the one to send the first handshake message, and the server must have certificates necessary for the ciphersuite used.

This selection can only be made prior to the initial SSL handshake. If the method is called made afterwards an SSLException is thrown.

Specified by:
setUseClientMode in interface SSLCommunication
Throws:
java.io.IOException

getUseClientMode

public boolean getUseClientMode()
Description copied from interface: SSLCommunication
Returns whether or not this socket resides on the client side of the connection.

Specified by:
getUseClientMode in interface SSLCommunication

getContext

public SSLContext getContext()
Description copied from interface: SSLCommunication
Returns the SSLContext of this SSLSocket.

Specified by:
getContext in interface SSLCommunication
Returns:
the SSLContext

setAutoHandshake

public void setAutoHandshake(boolean on)
Description copied from interface: SSLCommunication
Can be used to switch off the automatic start of the handshake procedure.

If auto handshake is switched off the application has to start the handshaking process manually using the method startHandshake(). This kind of operation is used when connecting over a proxy or firewall.

Specified by:
setAutoHandshake in interface SSLCommunication
Parameters:
on - true if handshake should start automatically, false otherwise
See Also:
SSLCommunication.startHandshake()

getPeerCertificateChain

public java.security.cert.X509Certificate[] getPeerCertificateChain()
Description copied from interface: SSLCommunication
Returns the certificate chain sent by the peer or null if the peer has no certificate. X509Certificate[0] contains the peers certificate. X509Certificate[len-1] contains the top CA certificate.

In SSLv2 this will always just return the server's certificate (protocol limitation). Note that some SSLv3/TLS server do not include self signed certificates as those will have to be obtained and verified using a different method anyway.

Specified by:
getPeerCertificateChain in interface SSLCommunication
Returns:
the certificate chain sent by the peer

getPSKIdentity

public java.lang.String getPSKIdentity()
Returns the PSK identity used for identifying the pre-shared key or null if no PSK cipher suite is used for the communication.

Returns:
the PSK identity, or null if no PSK cipher suite is used for the communication

getActiveProtocolVersion

public int getActiveProtocolVersion()
Description copied from interface: SSLCommunication
Return the active SSL protocol version. The value will be one of those defined in SSLContext.

Specified by:
getActiveProtocolVersion in interface SSLCommunication
Returns:
the active protocol version
See Also:
SSLContext

getActiveCipherSuite

public CipherSuite getActiveCipherSuite()
Description copied from interface: SSLCommunication
Returns the active cipher suite.

Specified by:
getActiveCipherSuite in interface SSLCommunication
Returns:
the active cipher suite
See Also:
CipherSuite

getActiveCompressionMethod

public CompressionMethod getActiveCompressionMethod()
Description copied from interface: SSLCommunication
Returns the active compression method.

Specified by:
getActiveCompressionMethod in interface SSLCommunication
Returns:
the active compression method
See Also:
CompressionMethod

getPeerSupportedCipherSuiteList

public CipherSuiteList getPeerSupportedCipherSuiteList()
Description copied from interface: SSLCommunication
Return the list of cipher suites known to be supported by the remote peer. This list will have different contents depending on the active protocol version and whether we are client or server, i.e. there may be some ciphersuites missing:

Specified by:
getPeerSupportedCipherSuiteList in interface SSLCommunication
See Also:
CipherSuite, SSLCommunication.getActiveCipherSuite()

getPeerSupportedCompressionMethods

public CompressionMethod[] getPeerSupportedCompressionMethods()
Description copied from interface: SSLCommunication
Return the compression methods supported by the remote peer. For the contents returned the same rules apply as with getPeerSupportedCipherSuiteList(), see there with the exception of the SSLv2 case. As there are no compression in SSLv2 the empty array is returned.

Specified by:
getPeerSupportedCompressionMethods in interface SSLCommunication
See Also:
CompressionMethod, SSLCommunication.getActiveCompressionMethod()

getPeerExtensions

public ExtensionList getPeerExtensions()
Gets the TLS extension received from the peer.

Note that the extensions are cloned before returned by this method. Since cloning may be an expensive operation, you may call this method only if required.

Returns:
the ExtensionList received from the peer, or null if the peer did not sent any extensions

getActiveExtensions

public ExtensionList getActiveExtensions()
Gets the active TLS extensions of the current TLS session. Active extensions are a sub-set of peer extensions.

Note that the extensions are cloned before returned by this method. Since cloning may be an expensive operation, you may call this method only if required.

Returns:
the active ExtensionList, or null if no extensions are used

getSession

public Session getSession()
Description copied from interface: SSLCommunication
Returns the currently active Session for this SSLSocket.

Specified by:
getSession in interface SSLCommunication
Returns:
the active Session

renegotiate

public void renegotiate()
                 throws java.io.IOException
Description copied from interface: SSLCommunication
Start a renegotiating SSL handshake. This is essentially the same as starting a new connection and a new handshake, only that it is done on the current connection. This renegotiating handshake will use session caching if possible. If you do not want that, invalidate the current session using getSession().invalidate() before calling renegotiate, see below for more information.

Basically there are two reasons you might want to initiate renegotiation:

If this method is called when the SSL connection has not yet been established it behaves as if startHandshake() had been called. Note that in versions prior to iSaSiLk 3.0beta2 renegotiation would always perform a full handshake. Also note that renegotiation is not available for SSLv2 (limitation of the protocol).

This method locks the InputStream and the OutputStream for exclusive access before proceeding with the handshake. That means that for the duration of the handshake procedure no communication is possible and more importantly that the handshake can not begin until possible blocking read() and write() calls by other threads have completed.

Specified by:
renegotiate in interface SSLCommunication
Throws:
java.io.IOException - if an error occurs during the handshake procedure

startHandshake

public void startHandshake()
                    throws java.io.IOException
Description copied from interface: SSLCommunication
Start the SSL handshake process. The SSL handshake is the initial phase of the protocol that performs authentication, key exchange, and security parameter selection. An application will usually not need to call this method because it is automatically invoked by getInputStream() and getOutputStream() unless setAutoHandshake() is set to false. If this method is called when the handshake has already been completed it does nothing.

This method locks the InputStream and the OutputStream for exclusive access before proceeding with the handshake. That means that for the duration of the handshake procedure no communication is possible and more importantly that the handshake can not begin until possible blocking read() and write() calls by other threads have completed.

Specified by:
startHandshake in interface SSLCommunication
Throws:
java.io.IOException - if an error occurs during the handshake procedure
See Also:
SSLCommunication.setAutoHandshake(boolean)

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
Description copied from interface: SSLCommunication
Returns an output stream for this socket. Invoking this method starts the SSL handshake if setAutoHandshake() is true and it has not been started already.

Specified by:
getOutputStream in interface SSLCommunication
Overrides:
getOutputStream in class java.net.Socket
Returns:
an output stream for writing bytes to this socket
Throws:
java.io.IOException - if an error occurs when creating the output stream

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Description copied from interface: SSLCommunication
Returns an input stream for this socket. Invoking this method starts the SSL handshake if setAutoHandshake() is true and it has not been started already.

Specified by:
getInputStream in interface SSLCommunication
Overrides:
getInputStream in class java.net.Socket
Returns:
an input stream for reading bytes from this socket.
Throws:
java.io.IOException - if an error occurs when creating the input stream.

setDebugStream

public void setDebugStream(java.io.Writer writer)
Description copied from interface: SSLCommunication
Enables debugging mode. In debugging mode status information is printed during the handshake procedure. To disable debugging again set the output to null.

Specified by:
setDebugStream in interface SSLCommunication
Parameters:
writer - the Writer to which debug information shall be written

setDebugStream

public void setDebugStream(java.io.OutputStream os)
Description copied from interface: SSLCommunication
Enables debugging mode. In debugging mode status information is printed during the handshake procedure. To disable debugging again set the output to null.

Specified by:
setDebugStream in interface SSLCommunication
Parameters:
os - the OutputStream to which debug information shall be written

shutdown

public void shutdown()
              throws java.io.IOException
Description copied from interface: SSLCommunication
Shuts the SSL layer down. Once this has been done this socket can no longer be used, i.e. read() calls return EOF and write() calls are ignored.

A SSL layer shutdown occurs in the following cases:

If the shutdown occurs due to an error the current session is automatically marked non reusable.

Specified by:
shutdown in interface SSLCommunication
Throws:
java.io.IOException - if an I/O error occurs when closing this SSLSocket

close

public void close()
           throws java.io.IOException
Description copied from interface: SSLCommunication
Close this SSL socket. This method first invokes shutdown() and then close the underlying transport.

This method will never be called by the library itself, it will always just call shutdown(). It is the responsibility of the application to always close the socket when communication has been completed. Once the socket has been closed read() and write() calls will throw SocketExceptions. The behaviour described here is compatible with the original Java sockets.

Specified by:
close in interface SSLCommunication
Overrides:
close in class java.net.Socket
Throws:
java.io.IOException

getClientSupportedCipherSuites

public CipherSuite[] getClientSupportedCipherSuites()
Deprecated. use getPeerSupportedCipherSuiteList()


getClientSupportedCompressionMethods

public CompressionMethod[] getClientSupportedCompressionMethods()
Deprecated. use getPeerSupportedCompressionMethods()


isServer

public boolean isServer()
Deprecated. use getUseClientMode()


getInetAddress

public java.net.InetAddress getInetAddress()
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getInetAddress in class java.net.Socket

getLocalAddress

public java.net.InetAddress getLocalAddress()
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getLocalAddress in class java.net.Socket

getPort

public int getPort()
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getPort in class java.net.Socket

getLocalPort

public int getLocalPort()
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getLocalPort in class java.net.Socket

setTcpNoDelay

public void setTcpNoDelay(boolean on)
                   throws java.net.SocketException
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
setTcpNoDelay in class java.net.Socket
Throws:
java.net.SocketException

getTcpNoDelay

public boolean getTcpNoDelay()
                      throws java.net.SocketException
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getTcpNoDelay in class java.net.Socket
Throws:
java.net.SocketException

setSoLinger

public void setSoLinger(boolean on,
                        int val)
                 throws java.net.SocketException
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
setSoLinger in class java.net.Socket
Throws:
java.net.SocketException

getSoLinger

public int getSoLinger()
                throws java.net.SocketException
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getSoLinger in class java.net.Socket
Throws:
java.net.SocketException

setSoTimeout

public void setSoTimeout(int timeout)
                  throws java.net.SocketException
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
setSoTimeout in class java.net.Socket
Throws:
java.net.SocketException

getSoTimeout

public int getSoTimeout()
                 throws java.net.SocketException
See JDK documentation of java.net.Socket for a description of this method.

Overrides:
getSoTimeout in class java.net.Socket
Throws:
java.net.SocketException

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

iSaSiLk 5.104, (c) 2002 IAIK, (c) 2003 - 2015 SIC