SslHandler (Netty/Handler 4.1.33.Final API)

java.lang.Object
- io.netty.channel.ChannelHandlerAdapter
- - io.netty.channel.ChannelInboundHandlerAdapter
  - - io.netty.handler.codec.ByteToMessageDecoder
    - - io.netty.handler.ssl.SslHandler

All Implemented Interfaces:

io.netty.channel.ChannelHandler, io.netty.channel.ChannelInboundHandler, io.netty.channel.ChannelOutboundHandler
```
public class SslHandler
extends io.netty.handler.codec.ByteToMessageDecoder
implements io.netty.channel.ChannelOutboundHandler
```
Adds SSL · TLS and StartTLS support to a Channel. Please refer to the "SecureChat" example in the distribution or the web site for the detailed usage.
Beginning the handshake

Beside using the handshake ChannelFuture to get notified about the completion of the handshake it's also possible to detect it by implement the ChannelInboundHandler.userEventTriggered(ChannelHandlerContext, Object) method and check for a SslHandshakeCompletionEvent.
Handshake

The handshake will be automatically issued for you once the Channel is active and SSLEngine.getUseClientMode() returns true. So no need to bother with it by your self.
Closing the session

To close the SSL session, the closeOutbound() 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:
1. Client sends a StartTLS request to server.
2. Server sends a StartTLS response to client.
3. Client begins SSL handshake.
If you implement a server, you need to:
1. create a new SslHandler instance with startTls flag set to true,
2. insert the SslHandler to the ChannelPipeline, and
3. write a StartTLS response.
Please note that you must insert 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.
1. Write a StartTLS request,
2. wait for the StartTLS response,
3. create a new SslHandler instance with startTls flag set to false,
4. insert the SslHandler to the ChannelPipeline, and
5. Initiate SSL 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 class io.netty.handler.codec.ByteToMessageDecoder
  io.netty.handler.codec.ByteToMessageDecoder.Cumulator
- Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler
  io.netty.channel.ChannelHandler.Sharable

Field Summary
- Fields inherited from class io.netty.handler.codec.ByteToMessageDecoder
  COMPOSITE_CUMULATOR, MERGE_CUMULATOR

Constructor Summary

Constructors
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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
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()` Deprecated.
`void`	`close(io.netty.channel.ChannelHandlerContext ctx, io.netty.channel.ChannelPromise promise)`
`io.netty.channel.ChannelFuture`	`close(io.netty.channel.ChannelPromise promise)` Deprecated.
`io.netty.channel.ChannelFuture`	`closeOutbound()` Sends an SSL `close_notify` message to the specified channel and destroys the underlying `SSLEngine`.
`io.netty.channel.ChannelFuture`	`closeOutbound(io.netty.channel.ChannelPromise promise)` Sends an SSL `close_notify` message to the specified channel and destroys the underlying `SSLEngine`.
`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`	`getCloseNotifyFlushTimeoutMillis()` Gets the timeout for flushing the close_notify that was triggered by closing the `Channel`.
`long`	`getCloseNotifyReadTimeoutMillis()` Gets the timeout (in ms) for receiving the response for the close_notify that was triggered by closing the `Channel`.
`long`	`getCloseNotifyTimeoutMillis()` Deprecated. use `getCloseNotifyFlushTimeoutMillis()`
`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`	`setCloseNotifyFlushTimeout(long closeNotifyFlushTimeout, TimeUnit unit)` Sets the timeout for flushing the close_notify that was triggered by closing the `Channel`.
`void`	`setCloseNotifyFlushTimeoutMillis(long closeNotifyFlushTimeoutMillis)` See `setCloseNotifyFlushTimeout(long, TimeUnit)`.
`void`	`setCloseNotifyReadTimeout(long closeNotifyReadTimeout, TimeUnit unit)` Sets the timeout for receiving the response for the close_notify that was triggered by closing the `Channel`.
`void`	`setCloseNotifyReadTimeoutMillis(long closeNotifyReadTimeoutMillis)` See `setCloseNotifyReadTimeout(long, TimeUnit)`.
`void`	`setCloseNotifyTimeout(long closeNotifyTimeout, TimeUnit unit)` Deprecated. use `setCloseNotifyFlushTimeout(long, TimeUnit)`
`void`	`setCloseNotifyTimeoutMillis(long closeNotifyFlushTimeoutMillis)` Deprecated. use `setCloseNotifyFlushTimeoutMillis(long)`
`void`	`setHandshakeTimeout(long handshakeTimeout, TimeUnit unit)`
`void`	`setHandshakeTimeoutMillis(long handshakeTimeoutMillis)`
`void`	`setWrapDataSize(int wrapDataSize)` Sets the number of bytes to pass to each `SSLEngine.wrap(ByteBuffer[], int, int, ByteBuffer)` call.
`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)`

Methods inherited from class io.netty.handler.codec.ByteToMessageDecoder
actualReadableBytes, callDecode, channelRead, decodeLast, discardSomeReadBytes, handlerRemoved, internalBuffer, isSingleDecode, setCumulator, setDiscardAfterReads, setSingleDecode, userEventTriggered

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter
channelRegistered, channelUnregistered, channelWritabilityChanged

Methods inherited from class io.netty.channel.ChannelHandlerAdapter
ensureNotSharable, isSharable

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.netty.channel.ChannelHandler
handlerRemoved

- Constructor Detail
  - SslHandler
```
public SslHandler(SSLEngine engine)
```
    Creates a new instance.
    
    Parameters:
    
    engine - the SSLEngine this handler will use
  - SslHandler
```
public SslHandler(SSLEngine engine,
                  boolean startTls)
```
    Creates a new instance.
    
    Parameters:
    
    engine - the SSLEngine this handler will use
    
    startTls - true if the first write request shouldn't be encrypted by the SSLEngine
  - SslHandler
```
@Deprecated
public SslHandler(SSLEngine engine,
                              Executor delegatedTaskExecutor)
```
    Deprecated. Use SslHandler(SSLEngine) instead.
  - SslHandler
```
@Deprecated
public SslHandler(SSLEngine engine,
                              boolean startTls,
                              Executor delegatedTaskExecutor)
```
    Deprecated. Use SslHandler(SSLEngine, boolean) instead.
- Method Detail
  - getHandshakeTimeoutMillis
```
public long getHandshakeTimeoutMillis()
```
  - setHandshakeTimeout
```
public void setHandshakeTimeout(long handshakeTimeout,
                                TimeUnit unit)
```
  - setHandshakeTimeoutMillis
```
public void setHandshakeTimeoutMillis(long handshakeTimeoutMillis)
```
  - setWrapDataSize
```
@UnstableApi
public final void setWrapDataSize(int wrapDataSize)
```
    Sets the number of bytes to pass to each SSLEngine.wrap(ByteBuffer[], int, int, ByteBuffer) call.
    This value will partition data which is passed to write write(ChannelHandlerContext, Object, ChannelPromise). The partitioning will work as follows:
    - If wrapDataSize <= 0 then we will write each data chunk as is.
    - If wrapDataSize > data size then we will attempt to aggregate multiple data chunks together.
    - If wrapDataSize > data size Else if wrapDataSize <= data size then we will divide the data into chunks of wrapDataSize when writing.
    If the SSLEngine doesn't support a gather wrap operation (e.g. SslProvider.OPENSSL) then aggregating data before wrapping can help reduce the ratio between TLS overhead vs data payload which will lead to better goodput. Writing fixed chunks of data can also help target the underlying transport's (e.g. TCP) frame size. Under lossy/congested network conditions this may help the peer get full TLS packets earlier and be able to do work sooner, as opposed to waiting for the all the pieces of the TLS packet to arrive.
    Parameters:
    
    wrapDataSize - the number of bytes which will be passed to each SSLEngine.wrap(ByteBuffer[], int, int, ByteBuffer) call.
  - getCloseNotifyTimeoutMillis
```
@Deprecated
public long getCloseNotifyTimeoutMillis()
```
    Deprecated. use getCloseNotifyFlushTimeoutMillis()
  - setCloseNotifyTimeout
```
@Deprecated
public void setCloseNotifyTimeout(long closeNotifyTimeout,
                                              TimeUnit unit)
```
    Deprecated. use setCloseNotifyFlushTimeout(long, TimeUnit)
  - setCloseNotifyTimeoutMillis
```
@Deprecated
public void setCloseNotifyTimeoutMillis(long closeNotifyFlushTimeoutMillis)
```
    Deprecated. use setCloseNotifyFlushTimeoutMillis(long)
  - getCloseNotifyFlushTimeoutMillis
```
public final long getCloseNotifyFlushTimeoutMillis()
```
    Gets the timeout for flushing the close_notify that was triggered by closing the Channel. If the close_notify was not flushed in the given timeout the Channel will be closed forcibly.
  - setCloseNotifyFlushTimeout
```
public final void setCloseNotifyFlushTimeout(long closeNotifyFlushTimeout,
                                             TimeUnit unit)
```
    Sets the timeout for flushing the close_notify that was triggered by closing the Channel. If the close_notify was not flushed in the given timeout the Channel will be closed forcibly.
  - setCloseNotifyFlushTimeoutMillis
```
public final void setCloseNotifyFlushTimeoutMillis(long closeNotifyFlushTimeoutMillis)
```
    See setCloseNotifyFlushTimeout(long, TimeUnit).
  - getCloseNotifyReadTimeoutMillis
```
public final long getCloseNotifyReadTimeoutMillis()
```
    Gets the timeout (in ms) for receiving the response for the close_notify that was triggered by closing the Channel. This timeout starts after the close_notify message was successfully written to the remote peer. Use 0 to directly close the Channel and not wait for the response.
  - setCloseNotifyReadTimeout
```
public final void setCloseNotifyReadTimeout(long closeNotifyReadTimeout,
                                            TimeUnit unit)
```
    Sets the timeout for receiving the response for the close_notify that was triggered by closing the Channel. This timeout starts after the close_notify message was successfully written to the remote peer. Use 0 to directly close the Channel and not wait for the response.
  - setCloseNotifyReadTimeoutMillis
```
public final void setCloseNotifyReadTimeoutMillis(long closeNotifyReadTimeoutMillis)
```
    See setCloseNotifyReadTimeout(long, TimeUnit).
  - engine
```
public SSLEngine engine()
```
    Returns the SSLEngine which is used by this handler.
  - applicationProtocol
```
public String applicationProtocol()
```
    Returns the name of the current application-level protocol.
    
    Returns:
    
    the protocol name or null if application-level protocol has not been negotiated
  - handshakeFuture
```
public io.netty.util.concurrent.Future<io.netty.channel.Channel> handshakeFuture()
```
    Returns a Future that will get notified once the current TLS handshake completes.
    
    Returns:
    
    the Future for the initial TLS handshake if renegotiate() was not invoked. The Future for the most recent TLS renegotiation otherwise.
  - close
```
@Deprecated
public io.netty.channel.ChannelFuture close()
```
    Deprecated.
    
    Use closeOutbound()
  - close
```
@Deprecated
public io.netty.channel.ChannelFuture close(io.netty.channel.ChannelPromise promise)
```
    Deprecated.
    
    Use closeOutbound(ChannelPromise)
  - closeOutbound
```
public io.netty.channel.ChannelFuture closeOutbound()
```
    Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine. This will not close the underlying Channel. If you want to also close the Channel use ChannelOutboundInvoker.close() or ChannelOutboundInvoker.close()
  - closeOutbound
```
public io.netty.channel.ChannelFuture closeOutbound(io.netty.channel.ChannelPromise promise)
```
    Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine. This will not close the underlying Channel. If you want to also close the Channel use ChannelOutboundInvoker.close() or ChannelOutboundInvoker.close()
  - sslCloseFuture
```
public 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. This method will return the same Future all the time.
    
    See Also:
    
    SSLEngine
  - handlerRemoved0
```
public void handlerRemoved0(io.netty.channel.ChannelHandlerContext ctx)
                     throws Exception
```
    Overrides:
    
    handlerRemoved0 in class io.netty.handler.codec.ByteToMessageDecoder
    
    Throws:
    
    Exception
  - bind
```
public void bind(io.netty.channel.ChannelHandlerContext ctx,
                 SocketAddress localAddress,
                 io.netty.channel.ChannelPromise promise)
          throws Exception
```
    Specified by:
    
    bind in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - connect
```
public void connect(io.netty.channel.ChannelHandlerContext ctx,
                    SocketAddress remoteAddress,
                    SocketAddress localAddress,
                    io.netty.channel.ChannelPromise promise)
             throws Exception
```
    Specified by:
    
    connect in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - deregister
```
public void deregister(io.netty.channel.ChannelHandlerContext ctx,
                       io.netty.channel.ChannelPromise promise)
                throws Exception
```
    Specified by:
    
    deregister in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - disconnect
```
public void disconnect(io.netty.channel.ChannelHandlerContext ctx,
                       io.netty.channel.ChannelPromise promise)
                throws Exception
```
    Specified by:
    
    disconnect in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - close
```
public void close(io.netty.channel.ChannelHandlerContext ctx,
                  io.netty.channel.ChannelPromise promise)
           throws Exception
```
    Specified by:
    
    close in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - read
```
public void read(io.netty.channel.ChannelHandlerContext ctx)
          throws Exception
```
    Specified by:
    
    read in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - write
```
public void write(io.netty.channel.ChannelHandlerContext ctx,
                  Object msg,
                  io.netty.channel.ChannelPromise promise)
           throws Exception
```
    Specified by:
    
    write in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - flush
```
public void flush(io.netty.channel.ChannelHandlerContext ctx)
           throws Exception
```
    Specified by:
    
    flush in interface io.netty.channel.ChannelOutboundHandler
    
    Throws:
    
    Exception
  - channelInactive
```
public void channelInactive(io.netty.channel.ChannelHandlerContext ctx)
                     throws Exception
```
    Specified by:
    
    channelInactive in interface io.netty.channel.ChannelInboundHandler
    
    Overrides:
    
    channelInactive in class io.netty.handler.codec.ByteToMessageDecoder
    
    Throws:
    
    Exception
  - exceptionCaught
```
public void exceptionCaught(io.netty.channel.ChannelHandlerContext ctx,
                            Throwable cause)
                     throws Exception
```
    Specified by:
    
    exceptionCaught in interface io.netty.channel.ChannelHandler
    
    Specified by:
    
    exceptionCaught in interface io.netty.channel.ChannelInboundHandler
    
    Overrides:
    
    exceptionCaught in class io.netty.channel.ChannelInboundHandlerAdapter
    
    Throws:
    
    Exception
  - isEncrypted
```
public static boolean isEncrypted(io.netty.buffer.ByteBuf buffer)
```
    Returns true if the given ByteBuf is encrypted. Be aware that this method will not increase the readerIndex of the given ByteBuf.
    
    Parameters:
    
    buffer - The ByteBuf to read from. Be aware that it must have at least 5 bytes to read, otherwise it will throw an IllegalArgumentException.
    
    Returns:
    
    encrypted true if the ByteBuf is encrypted, false otherwise.
    
    Throws:
    
    IllegalArgumentException - Is thrown if the given ByteBuf has not at least 5 bytes to read.
  - decode
```
protected void decode(io.netty.channel.ChannelHandlerContext ctx,
                      io.netty.buffer.ByteBuf in,
                      List<Object> out)
               throws SSLException
```
    Specified by:
    
    decode in class io.netty.handler.codec.ByteToMessageDecoder
    
    Throws:
    
    SSLException
  - channelReadComplete
```
public void channelReadComplete(io.netty.channel.ChannelHandlerContext ctx)
                         throws Exception
```
    Specified by:
    
    channelReadComplete in interface io.netty.channel.ChannelInboundHandler
    
    Overrides:
    
    channelReadComplete in class io.netty.handler.codec.ByteToMessageDecoder
    
    Throws:
    
    Exception
  - handlerAdded
```
public void handlerAdded(io.netty.channel.ChannelHandlerContext ctx)
                  throws Exception
```
    Specified by:
    
    handlerAdded in interface io.netty.channel.ChannelHandler
    
    Overrides:
    
    handlerAdded in class io.netty.channel.ChannelHandlerAdapter
    
    Throws:
    
    Exception
  - renegotiate
```
public io.netty.util.concurrent.Future<io.netty.channel.Channel> renegotiate()
```
    Performs TLS renegotiation.
  - renegotiate
```
public io.netty.util.concurrent.Future<io.netty.channel.Channel> renegotiate(io.netty.util.concurrent.Promise<io.netty.channel.Channel> promise)
```
    Performs TLS renegotiation.
  - channelActive
```
public void channelActive(io.netty.channel.ChannelHandlerContext ctx)
                   throws Exception
```
    Issues an initial TLS handshake once connected when used in client-mode
    
    Specified by:
    
    channelActive in interface io.netty.channel.ChannelInboundHandler
    
    Overrides:
    
    channelActive in class io.netty.channel.ChannelInboundHandlerAdapter
    
    Throws:
    
    Exception

Class SslHandler

Beginning the handshake

Handshake

Closing the session

Restarting the session

Implementing StartTLS

Known issues

Nested Class Summary

Nested classes/interfaces inherited from class io.netty.handler.codec.ByteToMessageDecoder

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

Field Summary

Fields inherited from class io.netty.handler.codec.ByteToMessageDecoder

Constructor Summary

Method Summary

Methods inherited from class io.netty.handler.codec.ByteToMessageDecoder

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

Methods inherited from class java.lang.Object

Methods inherited from interface io.netty.channel.ChannelHandler

Constructor Detail

SslHandler

SslHandler

SslHandler

SslHandler

Method Detail

getHandshakeTimeoutMillis

setHandshakeTimeout

setHandshakeTimeoutMillis

setWrapDataSize

getCloseNotifyTimeoutMillis

setCloseNotifyTimeout

setCloseNotifyTimeoutMillis

getCloseNotifyFlushTimeoutMillis

setCloseNotifyFlushTimeout

setCloseNotifyFlushTimeoutMillis

getCloseNotifyReadTimeoutMillis

setCloseNotifyReadTimeout

setCloseNotifyReadTimeoutMillis

engine

applicationProtocol

handshakeFuture

close

close

closeOutbound

closeOutbound

sslCloseFuture

handlerRemoved0

bind

connect

deregister

disconnect

close

read

write

flush

channelInactive

exceptionCaught

isEncrypted

decode

channelReadComplete

handlerAdded

renegotiate

renegotiate

channelActive