org.jboss.netty.handler.ssl
Class SslHandler

java.lang.Object
  org.jboss.netty.channel.SimpleChannelHandler
      org.jboss.netty.handler.codec.frame.FrameDecoder
          org.jboss.netty.handler.ssl.SslHandler

All Implemented Interfaces:

ChannelDownstreamHandler, ChannelHandler, ChannelUpstreamHandler

public class SslHandler
extends FrameDecoder

Adds SSL · TLS and StartTLS support to a Channel. Please refer to the "SecureChat" example in the distribution or the web site for the detailed usage.

Beginning the handshake

A user should make sure not to write a message while the handshake is in progress unless it is a renegotiation. You will be notified by the ChannelFuture which is returned by the handshake(Channel) method when the handshake process succeeds or fails.

Renegotiation

Once the initial handshake is done successfully. You can always call handshake(Channel) again to renegotiate the SSL session parameters.

Closing the session

To close the SSL session, the close(Channel) method should be called to send the close_notify message to the remote peer. One exception is when you close the Channel - SslHandler intercepts the close request and send the close_notify message before the channel closure automatically. Once the SSL session is closed, it is not reusable, and consequently you should create a new SslHandler with a new SSLEngine as explained in the following section.

Restarting the session

To restart the SSL session, you must remove the existing closed SslHandler from the ChannelPipeline, insert a new SslHandler with a new SSLEngine into the pipeline, and start the handshake process as described in the first section.

Version:

$Rev: 496 $, $Date: 2008-11-17 05:34:07 +0900 (Mon, 17 Nov 2008) $

Author:

The Netty Project (netty-dev@lists.jboss.org), Trustin Lee (tlee@redhat.com)

Constructor Summary

SslHandler(SSLEngine engine)
Creates a new instance.

SslHandler(SSLEngine engine, boolean startTls)
Creates a new instance.

SslHandler(SSLEngine engine, boolean startTls, Executor delegatedTaskExecutor)
Creates a new instance.

SslHandler(SSLEngine engine, Executor delegatedTaskExecutor)
Creates a new instance.

SslHandler(SSLEngine engine, SslBufferPool bufferPool)
Creates a new instance.

SslHandler(SSLEngine engine, SslBufferPool bufferPool, boolean startTls)
Creates a new instance.

SslHandler(SSLEngine engine, SslBufferPool bufferPool, boolean startTls, Executor delegatedTaskExecutor)
Creates a new instance.

SslHandler(SSLEngine engine, SslBufferPool bufferPool, Executor delegatedTaskExecutor)
Creates a new instance.

Method Summary

void	channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e) Invoked when a Channel was disconnected from its remote peer.
ChannelFuture	close(Channel channel) Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine.
protected Object	decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer) Decodes the received packets so far into a frame.
static SslBufferPool	getDefaultBufferPool() Returns the default SslBufferPool used when no pool is specified in the constructor.
SSLEngine	getEngine() Returns the SSLEngine which is used by this handler.
void	handleDownstream(ChannelHandlerContext context, ChannelEvent evt) Handles the specified downstream event.
ChannelFuture	handshake(Channel channel) Starts an SSL / TLS handshake for the specified channel.

Methods inherited from class org.jboss.netty.handler.codec.frame.FrameDecoder

channelClosed, decodeLast, exceptionCaught, messageReceived

Methods inherited from class org.jboss.netty.channel.SimpleChannelHandler

bindRequested, channelBound, channelConnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, closeRequested, connectRequested, disconnectRequested, handleUpstream, setInterestOpsRequested, unbindRequested, writeRequested

Methods inherited from class java.lang.Object

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

Constructor Detail

SslHandler

public SslHandler(SSLEngine engine)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

SslHandler

public SslHandler(SSLEngine engine,
                  SslBufferPool bufferPool)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

SslHandler

public SslHandler(SSLEngine engine,
                  boolean startTls)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

SslHandler

public SslHandler(SSLEngine engine,
                  SslBufferPool bufferPool,
                  boolean startTls)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

SslHandler

public SslHandler(SSLEngine engine,
                  Executor delegatedTaskExecutor)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

delegatedTaskExecutor - the Executor which will execute the delegated task that SSLEngine.getDelegatedTask() will return

SslHandler

public SslHandler(SSLEngine engine,
                  SslBufferPool bufferPool,
                  Executor delegatedTaskExecutor)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

delegatedTaskExecutor - the Executor which will execute the delegated task that SSLEngine.getDelegatedTask() will return

SslHandler

public SslHandler(SSLEngine engine,
                  boolean startTls,
                  Executor delegatedTaskExecutor)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

delegatedTaskExecutor - the Executor which will execute the delegated task that SSLEngine.getDelegatedTask() will return

SslHandler

public SslHandler(SSLEngine engine,
                  SslBufferPool bufferPool,
                  boolean startTls,
                  Executor delegatedTaskExecutor)

Creates a new instance.

Parameters:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

delegatedTaskExecutor - the Executor which will execute the delegated task that SSLEngine.getDelegatedTask() will return

Method Detail

getDefaultBufferPool

public static SslBufferPool getDefaultBufferPool()

Returns the default SslBufferPool used when no pool is specified in the constructor.

getEngine

public SSLEngine getEngine()

Returns the SSLEngine which is used by this handler.

handshake

public ChannelFuture handshake(Channel channel)
                        throws SSLException

Starts an SSL / TLS handshake for the specified channel.

Returns:

a ChannelFuture which is notified when the handshake succeeds or fails.

Throws:

SSLException

close

public ChannelFuture close(Channel channel)
                    throws SSLException

Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine.

Throws:

SSLException

handleDownstream

public void handleDownstream(ChannelHandlerContext context,
                             ChannelEvent evt)
                      throws Exception

Description copied from class: SimpleChannelHandler

Handles the specified downstream event. Down-casts the received downstream event into more meaningful sub-type event and calls an appropriate handler method with the down-casted event.

Specified by:

handleDownstream in interface ChannelDownstreamHandler

Overrides:

handleDownstream in class SimpleChannelHandler

Parameters:

context - the context object for this handler

evt - the downstream event to process or intercept

Throws:

Exception

channelDisconnected

public void channelDisconnected(ChannelHandlerContext ctx,
                                ChannelStateEvent e)
                         throws Exception

Description copied from class: SimpleChannelHandler

Invoked when a Channel was disconnected from its remote peer.

Overrides:

channelDisconnected in class FrameDecoder

Throws:

Exception

decode

protected Object decode(ChannelHandlerContext ctx,
                        Channel channel,
                        ChannelBuffer buffer)
                 throws Exception

Description copied from class: FrameDecoder

Decodes the received packets so far into a frame.

Specified by:

decode in class FrameDecoder

Parameters:

ctx - the context of this handler

channel - the current channel

buffer - the cumulative buffer of received packets so far

Returns:

the decoded frame if a full frame was received and decoded. null if there's not enough data in the buffer to decode a frame.

Throws:

Exception