getContext

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.

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.

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:

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.

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.

getSession

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:

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.

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

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:

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.

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.