Class SslHandler
- java.lang.Object
-
- org.jboss.netty.channel.SimpleChannelUpstreamHandler
-
- org.jboss.netty.handler.codec.frame.FrameDecoder
-
- org.jboss.netty.handler.ssl.SslHandler
-
- All Implemented Interfaces:
ChannelDownstreamHandler
,ChannelHandler
,ChannelUpstreamHandler
,LifeCycleAwareChannelHandler
public class SslHandler extends FrameDecoder implements ChannelDownstreamHandler
Adds SSL · TLS and StartTLS support to aChannel
. Please refer to the "SecureChat" example in the distribution or the web site for the detailed usage.Beginning the handshake
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 thehandshake()
method when the handshake process succeeds or fails.Handshake
If
isIssueHandshake()
isfalse
(default) you will need to take care of callinghandshake()
by your own. In most situations wereSslHandler
is used in 'client mode' you want to issue a handshake once the connection was established. ifsetIssueHandshake(boolean)
is set totrue
you don't need to worry about this as theSslHandler
will take care of it.Renegotiation
If
enableRenegotiation
istrue
(default) and the initial handshake has been done successfully, you can callhandshake()
to trigger the renegotiation.If
enableRenegotiation
isfalse
, an attempt to trigger renegotiation will result in the connection closure.Please note that TLS renegotiation had a security issue before. If your runtime environment did not fix it, please make sure to disable TLS renegotiation by calling
setEnableRenegotiation(boolean)
withfalse
. For more information, please refer to the following documents:Closing the session
To close the SSL session, the
close()
method should be called to send theclose_notify
message to the remote peer. One exception is when you close theChannel
-SslHandler
intercepts the close request and send theclose_notify
message before the channel closure automatically. Once the SSL session is closed, it is not reusable, and consequently you should create a newSslHandler
with a newSSLEngine
as explained in the following section.Restarting the session
To restart the SSL session, you must remove the existing closed
SslHandler
from theChannelPipeline
, insert a newSslHandler
with a newSSLEngine
into the pipeline, and start the handshake process as described in the first section.Implementing StartTLS
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:
- Client sends a StartTLS request to server.
- Server sends a StartTLS response to client.
- Client begins SSL handshake.
- create a new
SslHandler
instance withstartTls
flag set totrue
, - insert the
SslHandler
to theChannelPipeline
, and - write a StartTLS response.
SslHandler
before sending the StartTLS response. Otherwise the client can send begin SSL handshake beforeSslHandler
is inserted to theChannelPipeline
, causing data corruption.The client-side implementation is much simpler.
- Write a StartTLS request,
- wait for the StartTLS response,
- create a new
SslHandler
instance withstartTls
flag set tofalse
, - insert the
SslHandler
to theChannelPipeline
, and - Initiate SSL handshake by calling
handshake()
.
Known issues
Because of a known issue with the current implementation of the SslEngine that comes with Java it may be possible that you see blocked IO-Threads while a full GC is done.
So if you are affected you can workaround this problem by adjust the cache settings like shown below:
SslContext context = ...; context.getServerSessionContext().setSessionCacheSize(someSaneSize); context.getServerSessionContext().setSessionTime(someSameTimeout);
What values to use here depends on the nature of your application and should be set based on monitoring and debugging of it. For more details see #832 in our issue tracker.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler
ChannelHandler.Sharable
-
-
Field Summary
-
Fields inherited from class org.jboss.netty.handler.codec.frame.FrameDecoder
cumulation, DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
-
-
Constructor Summary
Constructors Constructor Description SslHandler(SSLEngine engine)
Creates a new instance.SslHandler(SSLEngine engine, boolean startTls)
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, Timer timer, long handshakeTimeoutInMillis)
Creates a new instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
afterRemove(ChannelHandlerContext ctx)
Fail all pending writes which we were not able to flush outvoid
beforeAdd(ChannelHandlerContext ctx)
void
channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e)
Loop over all the pending writes and fail them.void
channelConnected(ChannelHandlerContext ctx, ChannelStateEvent e)
Callshandshake()
once theChannel
is connectedvoid
channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e)
Invoked when aChannel
was disconnected from its remote peer.ChannelFuture
close()
Sends an SSLclose_notify
message to the specified channel and destroys the underlyingSSLEngine
.protected Object
decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer in)
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 aChannelHandler
.boolean
getCloseOnSSLException()
static SslBufferPool
getDefaultBufferPool()
Returns the defaultSslBufferPool
used when no pool is specified in the constructor.SSLEngine
getEngine()
Returns theSSLEngine
which is used by this handler.long
getHandshakeTimeout()
Return the timeout (in ms) after which theChannelFuture
ofhandshake()
will be failed, while a handshake is in progressChannelFuture
getSSLEngineInboundCloseFuture()
Return theChannelFuture
that will get notified if the inbound of theSSLEngine
will get closed.void
handleDownstream(ChannelHandlerContext context, ChannelEvent evt)
Handles the specified downstream event.ChannelFuture
handshake()
Starts an SSL / TLS handshake for the specified channel.boolean
isEnableRenegotiation()
Returnstrue
if and only if TLS renegotiation is enabled.static boolean
isEncrypted(ChannelBuffer buffer)
Returnstrue
if the givenChannelBuffer
is encrypted.boolean
isIssueHandshake()
Returnstrue
if the automatic handshake is enabledvoid
setCloseOnSSLException(boolean closeOnSslException)
void
setEnableRenegotiation(boolean enableRenegotiation)
Enables or disables TLS renegotiation.void
setIssueHandshake(boolean issueHandshake)
Enables or disables the automatic handshake once theChannel
is connected.-
Methods inherited from class org.jboss.netty.handler.codec.frame.FrameDecoder
actualReadableBytes, afterAdd, appendToCumulation, beforeRemove, cleanup, decodeLast, extractFrame, getMaxCumulationBufferCapacity, getMaxCumulationBufferComponents, internalBuffer, isUnfold, messageReceived, newCumulationBuffer, replace, setMaxCumulationBufferCapacity, setMaxCumulationBufferComponents, setUnfold, unfoldAndFireMessageReceived, updateCumulation
-
Methods inherited from class org.jboss.netty.channel.SimpleChannelUpstreamHandler
channelBound, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete
-
-
-
-
Constructor Detail
-
SslHandler
public SslHandler(SSLEngine engine)
Creates a new instance.- Parameters:
engine
- theSSLEngine
this handler will use
-
SslHandler
public SslHandler(SSLEngine engine, SslBufferPool bufferPool)
Creates a new instance.- Parameters:
engine
- theSSLEngine
this handler will usebufferPool
- theSslBufferPool
where this handler will acquire the buffers required by theSSLEngine
-
SslHandler
public SslHandler(SSLEngine engine, boolean startTls)
Creates a new instance.
-
SslHandler
public SslHandler(SSLEngine engine, SslBufferPool bufferPool, boolean startTls)
Creates a new instance.- Parameters:
engine
- theSSLEngine
this handler will usebufferPool
- theSslBufferPool
where this handler will acquire the buffers required by theSSLEngine
startTls
-true
if the first write request shouldn't be encrypted by theSSLEngine
-
SslHandler
public SslHandler(SSLEngine engine, SslBufferPool bufferPool, boolean startTls, Timer timer, long handshakeTimeoutInMillis)
Creates a new instance.- Parameters:
engine
- theSSLEngine
this handler will usebufferPool
- theSslBufferPool
where this handler will acquire the buffers required by theSSLEngine
startTls
-true
if the first write request shouldn't be encrypted by theSSLEngine
timer
- theTimer
which will be used to process the timeout of thehandshake()
. Be aware that the givenTimer
will not get stopped automaticly, so it is up to you to cleanup once you not need it anymorehandshakeTimeoutInMillis
- the time in milliseconds after whic thehandshake()
will be failed, and so the future notified
-
-
Method Detail
-
getDefaultBufferPool
public static SslBufferPool getDefaultBufferPool()
Returns the defaultSslBufferPool
used when no pool is specified in the constructor.
-
handshake
public ChannelFuture handshake()
Starts an SSL / TLS handshake for the specified channel.- Returns:
- a
ChannelFuture
which is notified when the handshake succeeds or fails.
-
close
public ChannelFuture close()
Sends an SSLclose_notify
message to the specified channel and destroys the underlyingSSLEngine
.
-
isEnableRenegotiation
public boolean isEnableRenegotiation()
Returnstrue
if and only if TLS renegotiation is enabled.
-
setEnableRenegotiation
public void setEnableRenegotiation(boolean enableRenegotiation)
Enables or disables TLS renegotiation.
-
setIssueHandshake
public void setIssueHandshake(boolean issueHandshake)
-
isIssueHandshake
public boolean isIssueHandshake()
Returnstrue
if the automatic handshake is enabled
-
getSSLEngineInboundCloseFuture
public ChannelFuture getSSLEngineInboundCloseFuture()
Return theChannelFuture
that will get notified if the inbound of theSSLEngine
will get closed. This method will return the sameChannelFuture
all the time. For more informations see the apidocs ofSSLEngine
-
getHandshakeTimeout
public long getHandshakeTimeout()
Return the timeout (in ms) after which theChannelFuture
ofhandshake()
will be failed, while a handshake is in progress
-
setCloseOnSSLException
public void setCloseOnSSLException(boolean closeOnSslException)
If set totrue
, theChannel
will automatically get closed one aSSLException
was caught. This is most times what you want, as after this its almost impossible to recover. Anyway the default isfalse
to not break compatibility with older releases. This will be changed totrue
in the next major release.
-
getCloseOnSSLException
public boolean getCloseOnSSLException()
-
handleDownstream
public void handleDownstream(ChannelHandlerContext context, ChannelEvent evt) throws Exception
Description copied from interface:ChannelDownstreamHandler
Handles the specified downstream event.- Specified by:
handleDownstream
in interfaceChannelDownstreamHandler
- Parameters:
context
- the context object for this handlerevt
- the downstream event to process or intercept- Throws:
Exception
-
channelDisconnected
public void channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
Description copied from class:SimpleChannelUpstreamHandler
Invoked when aChannel
was disconnected from its remote peer.- Overrides:
channelDisconnected
in classFrameDecoder
- Throws:
Exception
-
exceptionCaught
public void exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) throws Exception
Description copied from class:SimpleChannelUpstreamHandler
Invoked when an exception was raised by an I/O thread or aChannelHandler
.- Overrides:
exceptionCaught
in classFrameDecoder
- Throws:
Exception
-
isEncrypted
public static boolean isEncrypted(ChannelBuffer buffer)
Returnstrue
if the givenChannelBuffer
is encrypted. Be aware that this method will not increase the readerIndex of the givenChannelBuffer
.- Parameters:
buffer
- TheChannelBuffer
to read from. Be aware that it must have at least 5 bytes to read, otherwise it will throw anIllegalArgumentException
.- Returns:
- encrypted
true
if theChannelBuffer
is encrypted,false
otherwise. - Throws:
IllegalArgumentException
- Is thrown if the givenChannelBuffer
has not at least 5 bytes to read.
-
decode
protected Object decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer in) throws Exception
Description copied from class:FrameDecoder
Decodes the received packets so far into a frame. If an sub-class wants to extract a frame out of the buffer it should use theFrameDecoder.extractFrame(ChannelBuffer, int, int)
method, to make optimizations easier later.- Specified by:
decode
in classFrameDecoder
- Parameters:
ctx
- the context of this handlerchannel
- the current channelin
- 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.- 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
-
beforeAdd
public void beforeAdd(ChannelHandlerContext ctx) throws Exception
- Specified by:
beforeAdd
in interfaceLifeCycleAwareChannelHandler
- Overrides:
beforeAdd
in classFrameDecoder
- Throws:
Exception
-
afterRemove
public void afterRemove(ChannelHandlerContext ctx) throws Exception
Fail all pending writes which we were not able to flush out- Specified by:
afterRemove
in interfaceLifeCycleAwareChannelHandler
- Overrides:
afterRemove
in classFrameDecoder
- Throws:
Exception
-
channelConnected
public void channelConnected(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
Callshandshake()
once theChannel
is connected- Overrides:
channelConnected
in classSimpleChannelUpstreamHandler
- Throws:
Exception
-
channelClosed
public void channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception
Loop over all the pending writes and fail them. See #305 for more details.- Overrides:
channelClosed
in classFrameDecoder
- Throws:
Exception
-
-