Class SslHandler
- All Implemented Interfaces:
ChannelDownstreamHandler
,ChannelHandler
,ChannelUpstreamHandler
,LifeCycleAwareChannelHandler
Channel
. 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 the handshake()
method when the handshake
process succeeds or fails.
Handshake
If isIssueHandshake()
is false
(default) you will need to take care of calling handshake()
by your own. In most
situations were SslHandler
is used in 'client mode' you want to issue a handshake once
the connection was established. if setIssueHandshake(boolean)
is set to true
you don't need to worry about this as the SslHandler
will take care of it.
Renegotiation
If enableRenegotiation
is true
(default) and the initial handshake has been done successfully, you can call
handshake()
to trigger the renegotiation.
If enableRenegotiation
is false
,
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)
with
false
. 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 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.
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
before SslHandler
is inserted to the ChannelPipeline
, 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 ClassesModifier and TypeClassDescriptionprivate static final class
private static final class
private final class
Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler
ChannelHandler.Sharable
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final SslBufferPool
private static final AtomicIntegerFieldUpdater
<SslHandler> private int
private boolean
private ChannelHandlerContext
private static SslBufferPool
private static final ByteBuffer
private boolean
private final SSLEngine
private ChannelFuture
(package private) final Object
private boolean
private Timeout
private final long
private boolean
private static final Pattern
private static final Pattern
(package private) int
(package private) final Object
private boolean
private static final InternalLogger
private int
private final Queue
<MessageEvent> private final NonReentrantLock
private final Queue
<SslHandler.PendingWrite> private final NonReentrantLock
private static final AtomicIntegerFieldUpdater
<SslHandler> private static final AtomicIntegerFieldUpdater
<SslHandler> private int
private int
private final SslHandler.SSLEngineInboundCloseFuture
private final boolean
private final Timer
private boolean
Fields inherited from class org.jboss.netty.handler.codec.frame.FrameDecoder
cumulation, DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS
-
Constructor Summary
ConstructorsConstructorDescriptionSslHandler
(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
Modifier and TypeMethodDescriptionvoid
Fail all pending writes which we were not able to flush outvoid
private void
void
Loop over all the pending writes and fail them.void
Callshandshake()
once theChannel
is connectedvoid
Invoked when aChannel
was disconnected from its remote peer.close()
Sends an SSLclose_notify
message to the specified channel and destroys the underlyingSSLEngine
.private void
private void
protected Object
decode
(ChannelHandlerContext ctx, Channel channel, ChannelBuffer in) Decodes the received packets so far into a frame.void
Invoked when an exception was raised by an I/O thread or aChannelHandler
.private void
boolean
static SslBufferPool
Returns the defaultSslBufferPool
used when no pool is specified in the constructor.private static int
getEncryptedPacketLength
(ChannelBuffer buffer, int offset) Return how much bytes can be read out of the encrypted data.Returns theSSLEngine
which is used by this handler.long
Return the timeout (in ms) after which theChannelFuture
ofhandshake()
will be failed, while a handshake is in progressprivate static short
getShort
(ChannelBuffer buf, int offset) Reads a big-endian short integer from the buffer.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.private void
handleRenegotiation
(SSLEngineResult.HandshakeStatus handshakeStatus) Starts an SSL / TLS handshake for the specified channel.private boolean
Checks if the givenThrowable
can be ignore and just "swallowed" When an ssl connection is closed a close_notify message is sent.boolean
Returnstrue
if and only if TLS renegotiation is enabled.static boolean
isEncrypted
(ChannelBuffer buffer) Returnstrue
if the givenChannelBuffer
is encrypted.boolean
Returnstrue
if the automatic handshake is enabledprivate void
offerEncryptedWriteRequest
(MessageEvent encryptedWrite) private void
Fetches all delegated tasks from theSSLEngine
and runs them immediately.void
setCloseOnSSLException
(boolean closeOnSslException) void
setEnableRenegotiation
(boolean enableRenegotiation) Enables or disables TLS renegotiation.private void
setHandshakeFailure
(Channel channel, SSLException cause) private void
setHandshakeSuccess
(Channel channel) private boolean
Works around some AndroidSSLEngine
implementations that skipSSLEngineResult.HandshakeStatus.FINISHED
and go straight intoSSLEngineResult.HandshakeStatus.NOT_HANDSHAKING
when handshake is finished.void
setIssueHandshake
(boolean issueHandshake) Enables or disables the automatic handshake once theChannel
is connected.private ChannelBuffer
unwrap
(ChannelHandlerContext ctx, Channel channel, ByteBuffer nioInNetBuf, int initialNettyOutAppBufCapacity, boolean mightNeedHandshake) Unwraps inbound SSL records.private void
unwrapNonAppData
(ChannelHandlerContext ctx, Channel channel, boolean mightNeedHandshake) CallsSSLEngine.unwrap(ByteBuffer, ByteBuffer)
with an empty buffer to handle handshakes, etc.private void
wrap
(ChannelHandlerContext context, Channel channel) private ChannelFuture
wrapNonAppData
(ChannelHandlerContext ctx, Channel channel) 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
-
Field Details
-
logger
-
EMPTY_BUFFER
-
IGNORABLE_CLASS_IN_STACK
-
IGNORABLE_ERROR_MESSAGE
-
defaultBufferPool
-
ctx
-
engine
-
bufferPool
-
startTls
private final boolean startTls -
enableRenegotiation
private volatile boolean enableRenegotiation -
handshakeLock
-
handshaking
private boolean handshaking -
handshaken
private volatile boolean handshaken -
handshakeFuture
-
sentFirstMessage
private volatile int sentFirstMessage -
sentCloseNotify
private volatile int sentCloseNotify -
closedOutboundAndChannel
private volatile int closedOutboundAndChannel -
SENT_FIRST_MESSAGE_UPDATER
-
SENT_CLOSE_NOTIFY_UPDATER
-
CLOSED_OUTBOUND_AND_CHANNEL_UPDATER
-
ignoreClosedChannelException
int ignoreClosedChannelException -
ignoreClosedChannelExceptionLock
-
pendingUnencryptedWrites
-
pendingUnencryptedWritesLock
-
pendingEncryptedWrites
-
pendingEncryptedWritesLock
-
issueHandshake
private volatile boolean issueHandshake -
writeBeforeHandshakeDone
private volatile boolean writeBeforeHandshakeDone -
sslEngineCloseFuture
-
closeOnSslException
private boolean closeOnSslException -
packetLength
private int packetLength -
timer
-
handshakeTimeoutInMillis
private final long handshakeTimeoutInMillis -
handshakeTimeout
-
-
Constructor Details
-
SslHandler
Creates a new instance.- Parameters:
engine
- theSSLEngine
this handler will use
-
SslHandler
Creates a new instance.- Parameters:
engine
- theSSLEngine
this handler will usebufferPool
- theSslBufferPool
where this handler will acquire the buffers required by theSSLEngine
-
SslHandler
Creates a new instance. -
SslHandler
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 Details
-
getDefaultBufferPool
Returns the defaultSslBufferPool
used when no pool is specified in the constructor. -
getEngine
Returns theSSLEngine
which is used by this handler. -
handshake
Starts an SSL / TLS handshake for the specified channel.- Returns:
- a
ChannelFuture
which is notified when the handshake succeeds or fails.
-
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
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
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
-
cancelHandshakeTimeout
private void cancelHandshakeTimeout() -
channelDisconnected
Description copied from class:SimpleChannelUpstreamHandler
Invoked when aChannel
was disconnected from its remote peer.- Overrides:
channelDisconnected
in classFrameDecoder
- Throws:
Exception
-
closeEngine
private void closeEngine() -
exceptionCaught
Description copied from class:SimpleChannelUpstreamHandler
Invoked when an exception was raised by an I/O thread or aChannelHandler
.- Overrides:
exceptionCaught
in classFrameDecoder
- Throws:
Exception
-
ignoreException
Checks if the givenThrowable
can be ignore and just "swallowed" When an ssl connection is closed a close_notify message is sent. After that the peer also sends close_notify however, it's not mandatory to receive the close_notify. The party who sent the initial close_notify can close the connection immediately then the peer will get connection reset error. -
isEncrypted
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.
-
getEncryptedPacketLength
Return how much bytes can be read out of the encrypted data. 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:
- length
The length of the encrypted packet that is included in the buffer. This will
return
-1
if the givenChannelBuffer
is not encrypted at all. - 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
-
getShort
Reads a big-endian short integer from the buffer. Please note that we do not useChannelBuffer.getShort(int)
because it might be a little-endian buffer. -
wrap
- Throws:
SSLException
-
offerEncryptedWriteRequest
-
flushPendingEncryptedWrites
-
wrapNonAppData
private ChannelFuture wrapNonAppData(ChannelHandlerContext ctx, Channel channel) throws SSLException - Throws:
SSLException
-
unwrapNonAppData
private void unwrapNonAppData(ChannelHandlerContext ctx, Channel channel, boolean mightNeedHandshake) throws SSLException CallsSSLEngine.unwrap(ByteBuffer, ByteBuffer)
with an empty buffer to handle handshakes, etc.- Throws:
SSLException
-
unwrap
private ChannelBuffer unwrap(ChannelHandlerContext ctx, Channel channel, ByteBuffer nioInNetBuf, int initialNettyOutAppBufCapacity, boolean mightNeedHandshake) throws SSLException Unwraps inbound SSL records.- Throws:
SSLException
-
handleRenegotiation
-
runDelegatedTasks
private void runDelegatedTasks()Fetches all delegated tasks from theSSLEngine
and runs them immediately. -
setHandshakeSuccessIfStillHandshaking
Works around some AndroidSSLEngine
implementations that skipSSLEngineResult.HandshakeStatus.FINISHED
and go straight intoSSLEngineResult.HandshakeStatus.NOT_HANDSHAKING
when handshake is finished.- Returns:
true
if and only if the workaround has been applied and thushandshakeFuture
has been marked as success by this method
-
setHandshakeSuccess
-
setHandshakeFailure
-
closeOutboundAndChannel
-
beforeAdd
- Specified by:
beforeAdd
in interfaceLifeCycleAwareChannelHandler
- Overrides:
beforeAdd
in classFrameDecoder
- Throws:
Exception
-
afterRemove
Fail all pending writes which we were not able to flush out- Specified by:
afterRemove
in interfaceLifeCycleAwareChannelHandler
- Overrides:
afterRemove
in classFrameDecoder
- Throws:
Exception
-
channelConnected
Callshandshake()
once theChannel
is connected- Overrides:
channelConnected
in classSimpleChannelUpstreamHandler
- Throws:
Exception
-
channelClosed
Loop over all the pending writes and fail them. See #305 for more details.- Overrides:
channelClosed
in classFrameDecoder
- Throws:
Exception
-