ch.dermitza.securenio.socket.secure

Class SecureSocket

java.lang.Object

ch.dermitza.securenio.socket.secure.SecureSocket

All Implemented Interfaces:

SocketIF

public final class SecureSocket
extends java.lang.Object
implements SocketIF

A secure socket implementation of SocketIF. This class implements all logic required to process SSL/TLS handshaking and encrypt/decrypt data being sent and received through the underlying SocketChannel.

Note that this class is declared as final as it should NOT be extended.

Since:

0.18

Constructor Summary

Constructors

Constructor and Description
SecureSocket(java.nio.channels.SocketChannel channel, javax.net.ssl.SSLEngine engine, boolean singleThreaded, TaskWorker taskWorker, TimeoutWorker toWorker, HandshakeListener hsListener, TimeoutListener toListener) Create a new instance of a SecureSocket.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Pass-through implementation of AbstractInterruptibleChannel.close().
java.nio.channels.SelectableChannel	configureBlocking(boolean block) Pass-through implementation of AbstractSelectableChannel.configureBlocking(boolean block)
boolean	connect(java.net.SocketAddress remote) Pass-through implementation of SocketChannel.connect(SocketAddress remote)
boolean	finishConnect() Pass-through implementation of SocketChannel.finishConnect() In the SecureSocket implementation, once the connection of the underlying SocketChannel is finished, the SSL/TLS handshake is manually initiated here.
javax.net.ssl.SSLEngine	getEngine() Get the associated underlying SSLEngine.
java.nio.channels.SocketChannel	getSocket() Returns the underlying SocketChannel.
boolean	handshakePending() Used to identify whether the handshaking performed from the underlying SSLEngine is still pending.
void	initHandshake() Initialize SSL/TLS handshaking.
void	invalidateSession() Invalidate the current SSLSession.
void	processHandshake() Performs SSL/TLS handshaking.
int	read(java.nio.ByteBuffer buffer) Reads a sequence of bytes from this channel into the given buffer.
java.nio.channels.SelectionKey	register(java.nio.channels.Selector sel, int ops) Pass-through implementation of SelectableChannel.register(Selector sel, int ops)
void	setTaskPending(boolean taskPending) Sets whether or not there is an SSLEngine task pending, during an SSL/TLS handshake.
void	updateResult() Update the SSLEngineResult and setTaskPending(boolean) to false.
int	write(java.nio.ByteBuffer buffer) Pass-through implementation of SocketChannel.write(ByteBuffer buffer)

Methods inherited from class java.lang.Object

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

Constructor Detail

SecureSocket

public SecureSocket(java.nio.channels.SocketChannel channel,
            javax.net.ssl.SSLEngine engine,
            boolean singleThreaded,
            TaskWorker taskWorker,
            TimeoutWorker toWorker,
            HandshakeListener hsListener,
            TimeoutListener toListener)

Create a new instance of a SecureSocket. This instance has all the necessary logic to perform an SSL/TLS handshake and to encrypt and decrypt data being sent and received through the underlying SocketChannel.

Parameters:

channel - The underlying SocketChannel

engine - The underlying SSLEngine

singleThreaded - Whether or not this socket should perform the SSLEngineResult#HandshakeStatus NEED_TASK in the same thread (true) or in the TaskWorker thread (false). If set to true, null can be passed for the TaskWorker instance.

taskWorker - The TaskWorker instance associated with this SecureSocket. Can be null if this socket performs the SSLEngineResult#HandshakeStatus NEED_TASK in the same thread

toWorker - The TimeoutWorker instance associated with this SecureSocket.

hsListener - The HandshakeListener associated with this SecureSocket. Only one handshake listener is associated per socket, which is usually the AbstractSelector implementation.

toListener - The TimeoutListener associated with this SecureSocket. Only one timeout listener is associated per socket, which is usually the AbstractSelector implementation.

Method Detail

getEngine

public javax.net.ssl.SSLEngine getEngine()

Get the associated underlying SSLEngine. This method is called from the TaskWorker when there are pending SSLEngine tasks to be run.

Returns:

the underlying SSLEngine associated with this socket.

invalidateSession

public void invalidateSession()

Invalidate the current SSLSession. This method could be periodically used via a Timeout to perform SSL/TLS session rotation if needed.

Specified by:

invalidateSession in interface SocketIF

initHandshake

public void initHandshake()
                   throws java.io.IOException

Initialize SSL/TLS handshaking. This method is called from the AbstractSelector thread in two cases: (1) when finishConnect() is called or (2) when the SSLSession has been previously invalidated.

Specified by:

initHandshake in interface SocketIF

Throws:

java.io.IOException - propagated exceptions from processHandshake()

javax.net.ssl.SSLException - if there is an SSL/TLS problem with the call to the underlying SSLEngine.beginHandshake().

See Also:

initHandshake()

getSocket

public java.nio.channels.SocketChannel getSocket()

Returns the underlying SocketChannel. This is done in order to register the current socket with a Selector, as only the SocketChannel implementation is allowed to be associated with a Selector.

Specified by:

getSocket in interface SocketIF

Returns:

the underlying SocketChannel

connect

public boolean connect(java.net.SocketAddress remote)
                throws java.io.IOException

Pass-through implementation of SocketChannel.connect(SocketAddress remote)

Specified by:

connect in interface SocketIF

Parameters:

remote - The remote address to which this channel is to be connected

Returns:

true if a connection was established, false if this channel is in non-blocking mode and the connection operation is in progress

Throws:

java.io.IOException - Propagated exceptions from the underlying SocketChannel.connect(SocketAddress remote) implementation.

finishConnect

public boolean finishConnect()
                      throws java.io.IOException

Pass-through implementation of SocketChannel.finishConnect() In the SecureSocket implementation, once the connection of the underlying SocketChannel is finished, the SSL/TLS handshake is manually initiated here.

Note that this is not strictly necessary but rather a convenience, as subsequent handshakes can be initiated from the read(ByteBuffer buffer) and write(ByteBuffer buffer) methods.

Specified by:

finishConnect in interface SocketIF

Returns:

true if, and only if, this channel's socket is now connected

Throws:

java.io.IOException - Propagated exceptions from the underlying SocketChannel.finishConnect() implementation.

register

public java.nio.channels.SelectionKey register(java.nio.channels.Selector sel,
                                      int ops)
                                        throws java.nio.channels.ClosedChannelException

Pass-through implementation of SelectableChannel.register(Selector sel, int ops)

Specified by:

register in interface SocketIF

Parameters:

sel - The selector with which this channel is to be registered

ops - The interest set for the resulting key

Returns:

A key representing the registration of this channel with the given selector

Throws:

java.nio.channels.ClosedChannelException - Propagated exceptions from the underlying SelectableChannel.register(Selector sel, int ops) implementation.

configureBlocking

public java.nio.channels.SelectableChannel configureBlocking(boolean block)
                                                      throws java.io.IOException

Pass-through implementation of AbstractSelectableChannel.configureBlocking(boolean block)

Specified by:

configureBlocking in interface SocketIF

Parameters:

block - If true then this channel will be placed in blocking mode; if false then it will be placed in non-blocking mode

Returns:

This selectable channel

Throws:

java.io.IOException - Propagated exceptions from the underlying AbstractSelectableChannel.configureBlocking(boolean block) implementation.

processHandshake

public void processHandshake()
                      throws java.io.IOException

Performs SSL/TLS handshaking. Note that it can perform NEED_TASK either on the same thread or on the TaskWorker thread, based on how the SecureSocket has been initialized.

Specified by:

processHandshake in interface SocketIF

Throws:

java.io.IOException - If there is an underlying IOException while performing the handshake

javax.net.ssl.SSLException - If there is an exception thrown by the underlying SSLEngine while performing the handshake

See Also:

processHandshake()

updateResult

public void updateResult()

Update the SSLEngineResult and setTaskPending(boolean) to false.

This method is called once the SSLEngine has no more pending tasks. The updated result is fused from both the previous SSLEngineResult and the SSLEngine.getHandshakeStatus().

This is done such that we can receive the FINISHED SSLEngineResult.handshakeStatus that would otherwise not be available by just updating the existing SSLEngineResult.

We also setTaskPending(boolean) to false as there are no more tasks needed to be completed for the underlying SSLEngine.

Specified by:

updateResult in interface SocketIF

See Also:

updateResult()

read

public int read(java.nio.ByteBuffer buffer)
         throws java.io.IOException

Reads a sequence of bytes from this channel into the given buffer. This is a pass-through implementation of the underlying read(ByteBuffer buffer), with additional logic to handle the SSL/TLS encrypted stream.

An attempt is made to read up to r bytes from the encrypted channel, where r is the number of bytes remaining in the buffer. If handshaking has not been previously completed, handshaking also occurs at this stage. This method will also respond appropriately with returning -1 (EOF) when the underlying SSLEngine.isInboundDone(), or when reading from the encrypted channel returns -1 (EOF);

Specified by:

read in interface SocketIF

Parameters:

buffer - The buffer into which bytes are to be transferred

Returns:

The number of bytes read, possibly zero, or -1 if the channel has reached end-of-stream

Throws:

java.io.IOException - Propagated exceptions from the underlying SocketChannel.read(ByteBuffer buffer) implementation.

java.nio.BufferOverflowException - If the underlying SSLEngineResult has a status of BUFFER_OVERFLOW. As this should not happen in this implementation, it can be considered serious and should be handled

java.nio.BufferUnderflowException - If the underlying SSLEngineResult has a status of BUFFER_UNDERFLOW. As this should not happen in this implementation, it can be considered serious and should be handled

write

public int write(java.nio.ByteBuffer buffer)
          throws java.io.IOException

Description copied from interface: SocketIF

Pass-through implementation of SocketChannel.write(ByteBuffer buffer)

Specified by:

write in interface SocketIF

Returns:

The number of bytes written, possibly zero

Throws:

java.io.IOException - Propagated exceptions from the underlying SocketChannel.write(ByteBuffer buffer) implementation.

close

public void close()
           throws java.io.IOException

Pass-through implementation of AbstractInterruptibleChannel.close().

Before closing the underlying SocketChannel, attempts are made to flush() any encrypted data remaining in the encrypted buffer and cleanly close the associated SSLEngine.

Finally, we process what we can via processHandshake() before closing the underlying SocketChannel.

Specified by:

close in interface SocketIF

Throws:

java.io.IOException - Propagated exceptions from the underlying SocketChannel.close() implementation.

javax.net.ssl.SSLException - If we have not received a close_notify when SSLEngine.closeInbound() is invoked.

handshakePending

public boolean handshakePending()

Used to identify whether the handshaking performed from the underlying SSLEngine is still pending.

This is called from the application layer that invokes AbstractSelector.send(SocketIF, ByteBuffer) to correctly queue data to be written.

Specified by:

handshakePending in interface SocketIF

Returns:

whether the SSL/TLS handshaking is still pending

See Also:

handshakePending()

setTaskPending

public void setTaskPending(boolean taskPending)

Sets whether or not there is an SSLEngine task pending, during an SSL/TLS handshake.

If the current socket implementation is processing the pending tasks in the same thread, this method has no effect. Otherwise in a multi-threaded implementation, this allows the AbstractSelector thread to know the status of the task, and subsequently correctly process incoming requests (e.g. queueing data to be written).

Specified by:

setTaskPending in interface SocketIF

Parameters:

taskPending - Set whether or not there is a SSLEngine task pending for the SSLEngine associated with the underlying SocketChannel. Has no effect in a single threaded implementation.

See Also:

setTaskPending(boolean)