public class SslHandler
extends io.netty.handler.codec.ByteToMessageDecoder
implements io.netty.channel.ChannelOutboundHandler
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
ChannelInboundHandler.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.
| 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)
Deprecated.
Use
SslHandler(SSLEngine, boolean) instead. |
SslHandler(SSLEngine engine,
Executor delegatedTaskExecutor)
Deprecated.
Use
SslHandler(SSLEngine) instead. |
| Modifier and Type | Method and Description |
|---|---|
String |
applicationProtocol()
Returns the name of the current application-level protocol.
|
void |
bind(io.netty.channel.ChannelHandlerContext ctx,
SocketAddress localAddress,
io.netty.channel.ChannelPromise promise) |
void |
channelActive(io.netty.channel.ChannelHandlerContext ctx)
Issues an initial TLS handshake once connected when used in client-mode
|
void |
channelInactive(io.netty.channel.ChannelHandlerContext ctx) |
void |
channelReadComplete(io.netty.channel.ChannelHandlerContext ctx) |
io.netty.channel.ChannelFuture |
close()
Sends an SSL
close_notify message to the specified channel and
destroys the underlying SSLEngine. |
void |
close(io.netty.channel.ChannelHandlerContext ctx,
io.netty.channel.ChannelPromise promise) |
io.netty.channel.ChannelFuture |
close(io.netty.channel.ChannelPromise future)
See
close() |
void |
connect(io.netty.channel.ChannelHandlerContext ctx,
SocketAddress remoteAddress,
SocketAddress localAddress,
io.netty.channel.ChannelPromise promise) |
protected void |
decode(io.netty.channel.ChannelHandlerContext ctx,
io.netty.buffer.ByteBuf in,
List<Object> out) |
void |
deregister(io.netty.channel.ChannelHandlerContext ctx,
io.netty.channel.ChannelPromise promise) |
void |
disconnect(io.netty.channel.ChannelHandlerContext ctx,
io.netty.channel.ChannelPromise promise) |
SSLEngine |
engine()
Returns the
SSLEngine which is used by this handler. |
void |
exceptionCaught(io.netty.channel.ChannelHandlerContext ctx,
Throwable cause) |
void |
flush(io.netty.channel.ChannelHandlerContext ctx) |
long |
getCloseNotifyTimeoutMillis() |
long |
getHandshakeTimeoutMillis() |
void |
handlerAdded(io.netty.channel.ChannelHandlerContext ctx) |
void |
handlerRemoved0(io.netty.channel.ChannelHandlerContext ctx) |
io.netty.util.concurrent.Future<io.netty.channel.Channel> |
handshakeFuture()
Returns a
Future that will get notified once the current TLS handshake completes. |
static boolean |
isEncrypted(io.netty.buffer.ByteBuf buffer)
Returns
true if the given ByteBuf is encrypted. |
void |
read(io.netty.channel.ChannelHandlerContext ctx) |
io.netty.util.concurrent.Future<io.netty.channel.Channel> |
renegotiate()
Performs TLS renegotiation.
|
io.netty.util.concurrent.Future<io.netty.channel.Channel> |
renegotiate(io.netty.util.concurrent.Promise<io.netty.channel.Channel> promise)
Performs TLS renegotiation.
|
void |
setCloseNotifyTimeout(long closeNotifyTimeout,
TimeUnit unit) |
void |
setCloseNotifyTimeoutMillis(long closeNotifyTimeoutMillis) |
void |
setHandshakeTimeout(long handshakeTimeout,
TimeUnit unit) |
void |
setHandshakeTimeoutMillis(long handshakeTimeoutMillis) |
io.netty.util.concurrent.Future<io.netty.channel.Channel> |
sslCloseFuture()
Return the
Future that will get notified if the inbound of the SSLEngine is closed. |
void |
write(io.netty.channel.ChannelHandlerContext ctx,
Object msg,
io.netty.channel.ChannelPromise promise) |
actualReadableBytes, callDecode, channelRead, decodeLast, discardSomeReadBytes, handlerRemoved, internalBuffer, isSingleDecode, setCumulator, setDiscardAfterReads, setSingleDecode, userEventTriggeredchannelRegistered, channelUnregistered, channelWritabilityChangedpublic SslHandler(SSLEngine engine)
engine - the SSLEngine this handler will usepublic SslHandler(SSLEngine engine, boolean startTls)
@Deprecated public SslHandler(SSLEngine engine, Executor delegatedTaskExecutor)
SslHandler(SSLEngine) instead.@Deprecated public SslHandler(SSLEngine engine, boolean startTls, Executor delegatedTaskExecutor)
SslHandler(SSLEngine, boolean) instead.public 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 String applicationProtocol()
null if application-level protocol has not been negotiatedpublic io.netty.util.concurrent.Future<io.netty.channel.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 io.netty.channel.ChannelFuture close()
close_notify message to the specified channel and
destroys the underlying SSLEngine.public io.netty.channel.ChannelFuture close(io.netty.channel.ChannelPromise future)
close()public io.netty.util.concurrent.Future<io.netty.channel.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(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
handlerRemoved0 in class io.netty.handler.codec.ByteToMessageDecoderExceptionpublic void bind(io.netty.channel.ChannelHandlerContext ctx,
SocketAddress localAddress,
io.netty.channel.ChannelPromise promise)
throws Exception
bind in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void connect(io.netty.channel.ChannelHandlerContext ctx,
SocketAddress remoteAddress,
SocketAddress localAddress,
io.netty.channel.ChannelPromise promise)
throws Exception
connect in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void deregister(io.netty.channel.ChannelHandlerContext ctx,
io.netty.channel.ChannelPromise promise)
throws Exception
deregister in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void disconnect(io.netty.channel.ChannelHandlerContext ctx,
io.netty.channel.ChannelPromise promise)
throws Exception
disconnect in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void close(io.netty.channel.ChannelHandlerContext ctx,
io.netty.channel.ChannelPromise promise)
throws Exception
close in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void read(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
read in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void write(io.netty.channel.ChannelHandlerContext ctx,
Object msg,
io.netty.channel.ChannelPromise promise)
throws Exception
write in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void flush(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
flush in interface io.netty.channel.ChannelOutboundHandlerExceptionpublic void channelInactive(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
channelInactive in interface io.netty.channel.ChannelInboundHandlerchannelInactive in class io.netty.handler.codec.ByteToMessageDecoderExceptionpublic void exceptionCaught(io.netty.channel.ChannelHandlerContext ctx,
Throwable cause)
throws Exception
exceptionCaught in interface io.netty.channel.ChannelHandlerexceptionCaught in interface io.netty.channel.ChannelInboundHandlerexceptionCaught in class io.netty.channel.ChannelInboundHandlerAdapterExceptionpublic static boolean isEncrypted(io.netty.buffer.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(io.netty.channel.ChannelHandlerContext ctx,
io.netty.buffer.ByteBuf in,
List<Object> out)
throws SSLException
decode in class io.netty.handler.codec.ByteToMessageDecoderSSLExceptionpublic void channelReadComplete(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
channelReadComplete in interface io.netty.channel.ChannelInboundHandlerchannelReadComplete in class io.netty.handler.codec.ByteToMessageDecoderExceptionpublic void handlerAdded(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
handlerAdded in interface io.netty.channel.ChannelHandlerhandlerAdded in class io.netty.channel.ChannelHandlerAdapterExceptionpublic io.netty.util.concurrent.Future<io.netty.channel.Channel> renegotiate()
public io.netty.util.concurrent.Future<io.netty.channel.Channel> renegotiate(io.netty.util.concurrent.Promise<io.netty.channel.Channel> promise)
public void channelActive(io.netty.channel.ChannelHandlerContext ctx)
throws Exception
channelActive in interface io.netty.channel.ChannelInboundHandlerchannelActive in class io.netty.channel.ChannelInboundHandlerAdapterExceptionCopyright © 2008–2016 The Netty Project. All rights reserved.