iaik.security.ssl
Class SSLTransport

java.lang.Object
  iaik.security.ssl.SSLTransport

All Implemented Interfaces:

SSLCommunication, TLS13Communication, TLSCommunication

public class SSLTransport
extends java.lang.Object
implements TLS13Communication

This class implements a secure transport using the SSL/TLS protocol suite. It supports the following protocol versions:

• SSL 2.0. Client side only, otherwise complete. See specification.
• SSL 3.0. Client and server side, complete except for the Fortezza ciphersuites. See specification from Netscape.
• TLS 1.0 (aka SSL 3.1). Client and server side, complete implementation of all features. See RFC 2246.

SSL/TLS can be implemented on any transport using the SSLTransportSpi class or typically on sockets using the Java socket using SSLSocket. For more information see the documentation in your installation directory.

Note that the SSL/TLS handshake is not started immediately when the transport object is created but only when one of the following methods is called:

• startHandshake()
• getInputStream()
• getOutputStream()

See Also:

SSLContext, SSLSocket, SSLTransportSpi

Constructor Summary

SSLTransport(SSLTransportSpi transportSpi)
Creates a SSLTransport with the given spi implementation.

Method Summary

void	close() Close this SSL socket.
void	debug(java.lang.String msg) Writes debug information to a debug stream.
void	debug(java.lang.Throwable e)
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.
ChannelBindings	getChannelBindings() Gets any ChannelBindings associated with this Handshaker.
SSLContext	getContext() Returns the SSLContext of this SSLSocket.
java.io.InputStream	getInputStream() Returns an input stream for this socket.
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 extensions 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.
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.
java.net.InetAddress	getRemoteInetAddress() Returns the peer's InetAddress.
java.lang.Object	getRemotePeerId() Get an object uniquely identifying the remote peer for the session manager.
java.lang.String	getRemotePeerName()
Session	getSession() Returns the currently active Session for this SSLSocket.
boolean	getUseClientMode() Returns whether or not this socket resides on the client side of the connection.
void	postHandshake(TLS13PostHandshakeConfig postHandshakeConfig) Performs a TLS 1.3 post handshake.
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	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.lang.Object

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

Constructor Detail

SSLTransport

public SSLTransport(SSLTransportSpi transportSpi)
             throws java.io.IOException

Creates a SSLTransport with the given spi implementation.

Parameters:

transportSpi - the underlying transport protocol implementation

Throws:

if - an I/O problem occurs when initializing this SSLTransport

java.io.IOException

Method Detail

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

getRemotePeerName

public java.lang.String getRemotePeerName()

getRemoteInetAddress

public java.net.InetAddress getRemoteInetAddress()

Returns the peer's InetAddress.

getRemotePeerId

public java.lang.Object getRemotePeerId()

Get an object uniquely identifying the remote peer for the session manager. This identifier is used for session caching, it may return null if session caching is not supported for this transport.

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.

Specified by:

getPSKIdentity in interface TLSCommunication

Returns:

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

getActiveExtensions

public ExtensionList getActiveExtensions()

Gets the active TLS extensions of the current TLS session. Active extensions are a sub-set of peer extensions.

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

Specified by:

getActiveExtensions in interface TLSCommunication

Returns:

the active ExtensionList, or null if no extensions are used

getPeerExtensions

public ExtensionList getPeerExtensions()

Gets the TLS extensions received from the peer.

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

Specified by:

getPeerExtensions in interface TLSCommunication

Returns:

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

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:

• For SSLv3/TLS servers this method returns all ciphersuites supported by the client (those sent in its ClientHello message).
• For SSLv3/TLS clients this method returns the list containing the active ciphersuite as its only element.
• For SSLv2 clients this method returns the ciphersuites shared with the server (those returned in its ServerHello message).
• If the handshake has not yet been completed the empty list is returned.

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

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

getChannelBindings

public ChannelBindings getChannelBindings()

Gets any ChannelBindings associated with this Handshaker.

Specified by:

getChannelBindings in interface TLSCommunication

Returns:

the ChannelBindings associated with this Handshaker; maybe null if no channel bindings are available (e.g. if the application does not have announced interest in channel bindings.

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:

• You want to negotiate new session parameters, e.g. use a different ciphersuite or a different client certificate. In other words, you want to do a full handshake without session caching.
• The current connection has been established for a very long time and a lot of data has been sent, making the connection possibly vulnerable to known ciphertext attacks. In this case you will just want to change the encryption keys used, which can be achieved by using a short handshake using session caching. It will refresh all keys and IVs based on the random numbers exchanged in the hello messages.

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)

postHandshake

public void postHandshake(TLS13PostHandshakeConfig postHandshakeConfig)
                   throws java.io.IOException

Performs a TLS 1.3 post handshake.

This method may be called by an application to trigger some post handshake action. The given post handshake configuration specifies the type of post handshake to be performed (either NEW_SESSION_TICKET to send a new session ticket to the client, POST_HANDSHAKE_AUTH to request post client authentication, or KEY_UPDATE to perform a key update) and may provide some configuration options. Sending a new session ticket or requesting post client authentication may be only triggered on the server side, a key update may be done on both, client or server side.

Specified by:

postHandshake in interface TLS13Communication

Parameters:

postHandshakeConfig - the post handshake configuration

Throws:

java.io.IOException - if the requested post handshake action is not suitable for the local connection end, handshake state or protocol version, or some error occurs when performing the post handshake

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

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

Returns:

an input stream for reading bytes from this socket.

Throws:

java.io.IOException - if an error occurs when creating the input stream.

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

Throws:

java.io.IOException

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:

• An application calls this method.
• An IOException occurs trying to read from or write to this socket.
• The SSL connection is closed normally by the remote peer by sending an SSL closure alert warning.
• Some error occurs in the SSL processing. This includes MAC verification errors, errors due to configuration errors (certificates or keys missing), and alerts sent by the remote peer.

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

debug

public void debug(java.lang.String msg)

Writes debug information to a debug stream.

Parameters:

msg - the debug message

debug

public void debug(java.lang.Throwable e)

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