public class SslHandler extends FrameDecoder implements ChannelDownstreamHandler
Channel
. Please refer
to the "SecureChat" example in the distribution or the web
site for the detailed usage.
You must make sure not to write a message while the
handshake is in progress unless you are
renegotiating. You will be notified by the ChannelFuture
which is
returned by the handshake(Channel)
method when the handshake
process succeeds or fails.
Once the initial handshake is done successfully. You can always call
handshake(Channel)
again to renegotiate the SSL session parameters.
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.
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.
StartTLS is the communication pattern that secures the wire in the middle of the plaintext connection. Please note that it is different from SSL · TLS, that secures the wire from the beginning of the connection. Typically, StartTLS is composed of three steps:
SslHandler
instance with startTls
flag set
to true
,SslHandler
to the ChannelPipeline
, andSslHandler
before sending
the StartTLS response. Otherwise the client can send begin SSL handshake
before SslHandler
is inserted to the ChannelPipeline
, causing
data corruption.
The client-side implementation is much simpler.
SslHandler
instance with startTls
flag set
to false
,SslHandler
to the ChannelPipeline
, andhandshake(Channel)
.Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
void |
exceptionCaught(ChannelHandlerContext ctx,
ExceptionEvent e)
Invoked when an exception was raised by an I/O thread or a
ChannelHandler . |
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.
|
channelClosed, decodeLast, messageReceived
channelBound, channelConnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete
public SslHandler(SSLEngine engine)
engine
- the SSLEngine
this handler will usepublic SslHandler(SSLEngine engine, SslBufferPool bufferPool)
engine
- the SSLEngine
this handler will usebufferPool
- the SslBufferPool
where this handler will
acquire the buffers required by the SSLEngine
public SslHandler(SSLEngine engine, boolean startTls)
public SslHandler(SSLEngine engine, SslBufferPool bufferPool, boolean startTls)
engine
- the SSLEngine
this handler will usebufferPool
- 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
public SslHandler(SSLEngine engine, Executor delegatedTaskExecutor)
engine
- the SSLEngine
this handler will usedelegatedTaskExecutor
- the Executor
which will execute the delegated task
that SSLEngine.getDelegatedTask()
will returnpublic SslHandler(SSLEngine engine, SslBufferPool bufferPool, Executor delegatedTaskExecutor)
engine
- the SSLEngine
this handler will usebufferPool
- 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 returnpublic SslHandler(SSLEngine engine, boolean startTls, Executor delegatedTaskExecutor)
engine
- the SSLEngine
this handler will usestartTls
- 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 returnpublic SslHandler(SSLEngine engine, SslBufferPool bufferPool, boolean startTls, Executor delegatedTaskExecutor)
engine
- the SSLEngine
this handler will usebufferPool
- 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 returnpublic static SslBufferPool getDefaultBufferPool()
SslBufferPool
used when no pool is
specified in the constructor.public ChannelFuture handshake(Channel channel) throws SSLException
ChannelFuture
which is notified when the handshake
succeeds or fails.SSLException
public ChannelFuture close(Channel channel) throws SSLException
close_notify
message to the specified channel and
destroys the underlying SSLEngine
.SSLException
public void handleDownstream(ChannelHandlerContext context, ChannelEvent evt) throws Exception
ChannelDownstreamHandler
handleDownstream
in interface ChannelDownstreamHandler
context
- the context object for this handlerevt
- the downstream event to process or interceptException
public void channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
SimpleChannelUpstreamHandler
Channel
was disconnected from its remote peer.channelDisconnected
in class FrameDecoder
Exception
public void exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) throws Exception
SimpleChannelUpstreamHandler
ChannelHandler
.exceptionCaught
in class FrameDecoder
Exception
protected Object decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer) throws Exception
FrameDecoder
decode
in class FrameDecoder
ctx
- the context of this handlerchannel
- the current channelbuffer
- the cumulative buffer of received packets so far.
Note that the buffer might be empty, which means you
should not make an assumption that the buffer contains
at least one byte in your decoder implementation.null
if there's not enough data in the buffer to decode a frame.Exception
Copyright © 2008-2013 JBoss, by Red Hat. All Rights Reserved.