public class SslHandler extends ByteToMessageDecoder
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 Future which is
returned by the handshakeFuture() method when the handshake
process succeeds or fails.
Beside using the handshake ChannelFuture to get notified about the completation of the handshake it's
also possible to detect it by implement the
ChannelHandler.userEventTriggered(ChannelHandlerContext, Object)
method and check for a SslHandshakeCompletionEvent.
The handshake will be automaticly issued for you once the Channel is active and
SSLEngine.getUseClientMode() returns true.
So no need to bother with it by your self.
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.
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, andBecause 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.
ByteToMessageDecoder.CumulatorChannelHandler.Sharable, ChannelHandler.SkipCOMPOSITE_CUMULATOR, MERGE_CUMULATOR| Constructor and Description |
|---|
SslHandler(SSLEngine engine)
Creates a new instance.
|
SslHandler(SSLEngine engine,
boolean startTls)
Creates a new instance.
|
actualReadableBytes, callDecode, channelRead, decodeLast, handlerRemoved, internalBuffer, isSingleDecode, setCumulator, setSingleDecodebind, channelRegistered, channelUnregistered, channelWritabilityChanged, connect, deregister, isSharable, userEventTriggeredpublic SslHandler(SSLEngine engine)
engine - the SSLEngine this handler will usepublic long getHandshakeTimeoutMillis()
public void setHandshakeTimeout(long handshakeTimeout,
TimeUnit unit)
public void setHandshakeTimeoutMillis(long handshakeTimeoutMillis)
public long getCloseNotifyTimeoutMillis()
public void setCloseNotifyTimeout(long closeNotifyTimeout,
TimeUnit unit)
public void setCloseNotifyTimeoutMillis(long closeNotifyTimeoutMillis)
public Future<Channel> handshakeFuture()
Future that will get notified once the current TLS handshake completes.Future for the iniital TLS handshake if renegotiate() was not invoked.
The Future for the most recent TLS renegotiation otherwise.public ChannelFuture close()
close_notify message to the specified channel and
destroys the underlying SSLEngine.public ChannelFuture close(ChannelPromise future)
close()public Future<Channel> sslCloseFuture()
Future that will get notified if the inbound of the SSLEngine is closed.
This method will return the same Future all the time.SSLEnginepublic void handlerRemoved0(ChannelHandlerContext ctx) throws Exception
ByteToMessageDecoderByteToMessageDecoder was removed from the actual context and it doesn't handle
events anymore.handlerRemoved0 in class ByteToMessageDecoderExceptionpublic void disconnect(ChannelHandlerContext ctx, ChannelPromise promise) throws Exception
ChannelHandlerAdapterChannelHandlerContext.disconnect(ChannelPromise) to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.disconnect in interface ChannelHandlerdisconnect in class ChannelHandlerAdapterctx - the ChannelHandlerContext for which the disconnect operation is madepromise - the ChannelPromise to notify once the operation completesException - thrown if an error accourpublic void close(ChannelHandlerContext ctx, ChannelPromise promise) throws Exception
ChannelHandlerAdapterChannelHandlerContext.close(ChannelPromise) to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.close in interface ChannelHandlerclose in class ChannelHandlerAdapterctx - the ChannelHandlerContext for which the close operation is madepromise - the ChannelPromise to notify once the operation completesException - thrown if an error accourpublic void read(ChannelHandlerContext ctx) throws Exception
ChannelHandlerAdapterChannelHandlerContext.read() to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.read in interface ChannelHandlerread in class ChannelHandlerAdapterExceptionpublic void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) throws Exception
ChannelHandlerAdapterChannelHandlerContext.write(Object) to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.write in interface ChannelHandlerwrite in class ChannelHandlerAdapterctx - the ChannelHandlerContext for which the write operation is mademsg - the message to writepromise - the ChannelPromise to notify once the operation completesException - thrown if an error accourpublic void flush(ChannelHandlerContext ctx) throws Exception
ChannelHandlerAdapterChannelHandlerContext.flush() to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.flush in interface ChannelHandlerflush in class ChannelHandlerAdapterctx - the ChannelHandlerContext for which the flush operation is madeException - thrown if an error accourpublic void channelInactive(ChannelHandlerContext ctx) throws Exception
ChannelHandlerAdapterChannelHandlerContext.fireChannelInactive() to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.channelInactive in interface ChannelHandlerchannelInactive in class ByteToMessageDecoderExceptionpublic void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) throws Exception
ChannelHandlerAdapterChannelHandlerContext.fireExceptionCaught(Throwable) to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.exceptionCaught in interface ChannelHandlerexceptionCaught in class ChannelHandlerAdapterExceptionpublic static boolean isEncrypted(ByteBuf buffer)
true if the given ByteBuf is encrypted. Be aware that this method
will not increase the readerIndex of the given ByteBuf.buffer - The ByteBuf to read from. Be aware that it must have at least 5 bytes to read,
otherwise it will throw an IllegalArgumentException.true if the ByteBuf is encrypted, false otherwise.IllegalArgumentException - Is thrown if the given ByteBuf has not at least 5 bytes to read.protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws SSLException
ByteToMessageDecoderByteBuf to an other. This method will be called till either the input
ByteBuf has nothing to read when return from this method or till nothing was read from the input
ByteBuf.decode in class ByteToMessageDecoderctx - the ChannelHandlerContext which this ByteToMessageDecoder belongs toin - the ByteBuf from which to read dataout - the List to which decoded messages should be addedSSLExceptionpublic void channelReadComplete(ChannelHandlerContext ctx) throws Exception
ChannelHandlerAdapterChannelHandlerContext.fireChannelReadComplete() to forward
to the next ChannelHandler in the ChannelPipeline.
Sub-classes may override this method to change behavior.channelReadComplete in interface ChannelHandlerchannelReadComplete in class ByteToMessageDecoderExceptionpublic void handlerAdded(ChannelHandlerContext ctx) throws Exception
ChannelHandlerAdapterhandlerAdded in interface ChannelHandlerhandlerAdded in class ChannelHandlerAdapterExceptionpublic Future<Channel> renegotiate(Promise<Channel> promise)
public void channelActive(ChannelHandlerContext ctx) throws Exception
channelActive in interface ChannelHandlerchannelActive in class ChannelHandlerAdapterExceptionCopyright © 2008–2015 The Netty Project. All rights reserved.