iaik.security.ssl
Interface SSLCommunication

All Known Implementing Classes:
SSLSocket, SSLTransport

public interface SSLCommunication

SSLCommunication is an interface that defines all SSL relevant public methods. It exists solely to offer a common interface to SSLTransport and SSLSocket.

See Also:
SSLSocket, SSLTransport

Method Summary
 void close()
          Close this SSL socket.
 CipherSuite getActiveCipherSuite()
          Returns the active cipher suite.
 CompressionMethod getActiveCompressionMethod()
          Returns the active compression method.
 int getActiveProtocolVersion()
          Return the active SSL protocol version.
 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.
 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.
 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 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.
 

Method Detail

getContext

SSLContext getContext()
Returns the SSLContext of this SSLSocket.

Returns:
the SSLContext

setAutoHandshake

void setAutoHandshake(boolean on)
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.

Parameters:
on - true if handshake should start automatically, false otherwise
See Also:
startHandshake()

getPeerCertificateChain

java.security.cert.X509Certificate[] getPeerCertificateChain()
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.

Returns:
the certificate chain sent by the peer

getActiveProtocolVersion

int getActiveProtocolVersion()
Return the active SSL protocol version. The value will be one of those defined in SSLContext.

Returns:
the active protocol version
See Also:
SSLContext

getActiveCipherSuite

CipherSuite getActiveCipherSuite()
Returns the active cipher suite.

Returns:
the active cipher suite
See Also:
CipherSuite

getActiveCompressionMethod

CompressionMethod getActiveCompressionMethod()
Returns the active compression method.

Returns:
the active compression method
See Also:
CompressionMethod

getPeerSupportedCipherSuiteList

CipherSuiteList getPeerSupportedCipherSuiteList()
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:

See Also:
CipherSuite, getActiveCipherSuite()

getPeerSupportedCompressionMethods

CompressionMethod[] getPeerSupportedCompressionMethods()
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.

See Also:
CompressionMethod, getActiveCompressionMethod()

getSession

Session getSession()
Returns the currently active Session for this SSLSocket.

Returns:
the active Session

renegotiate

void renegotiate()
                 throws java.io.IOException
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.

Throws:
java.io.IOException - if an error occurs during the handshake procedure

startHandshake

void startHandshake()
                    throws java.io.IOException
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.

Throws:
java.io.IOException - if an error occurs during the handshake procedure
See Also:
setAutoHandshake(boolean)

setUseClientMode

void setUseClientMode(boolean mode)
                      throws java.io.IOException
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.

Throws:
java.io.IOException

getUseClientMode

boolean getUseClientMode()
Returns whether or not this socket resides on the client side of the connection.


getOutputStream

java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
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.

Returns:
an output stream for writing bytes to this socket
Throws:
java.io.IOException - if an error occurs when creating the output stream

getInputStream

java.io.InputStream getInputStream()
                                   throws java.io.IOException
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.

Returns:
an input stream for reading bytes from this socket.
Throws:
java.io.IOException - if an error occurs when creating the input stream.

setDebugStream

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

Parameters:
writer - the Writer to which debug information shall be written

setDebugStream

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

Parameters:
os - the OutputStream to which debug information shall be written

shutdown

void shutdown()
              throws java.io.IOException
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.

Throws:
java.io.IOException - if an I/O error occurs when closing this SSLSocket

close

void close()
           throws java.io.IOException
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.

Throws:
java.io.IOException

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