SslHandler (Netty API Reference (4.1.11.Final))

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

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler, ChannelOutboundHandler
```
public class SslHandler
extends ByteToMessageDecoder
implements 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 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:
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
  ByteToMessageDecoder.Cumulator
- Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler
  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(ChannelHandlerContext ctx, SocketAddress localAddress, ChannelPromise promise)` Called once a bind operation is made.
`void`	`channelActive(ChannelHandlerContext ctx)` Issues an initial TLS handshake once connected when used in client-mode
`void`	`channelInactive(ChannelHandlerContext ctx)` Calls `ChannelHandlerContext.fireChannelInactive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`void`	`channelReadComplete(ChannelHandlerContext ctx)` Calls `ChannelHandlerContext.fireChannelReadComplete()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`ChannelFuture`	`close()` Deprecated. use `ChannelOutboundInvoker.close()` or `ChannelOutboundInvoker.close()`
`void`	`close(ChannelHandlerContext ctx, ChannelPromise promise)` Called once a close operation is made.
`ChannelFuture`	`close(ChannelPromise promise)` Deprecated. use `ChannelOutboundInvoker.close()` or `ChannelOutboundInvoker.close()`
`void`	`connect(ChannelHandlerContext ctx, SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise)` Called once a connect operation is made.
`protected void`	`decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out)` Decode the from one `ByteBuf` to an other.
`void`	`deregister(ChannelHandlerContext ctx, ChannelPromise promise)` Called once a deregister operation is made from the current registered `EventLoop`.
`void`	`disconnect(ChannelHandlerContext ctx, ChannelPromise promise)` Called once a disconnect operation is made.
`SSLEngine`	`engine()` Returns the `SSLEngine` which is used by this handler.
`void`	`exceptionCaught(ChannelHandlerContext ctx, Throwable cause)` Calls `ChannelHandlerContext.fireExceptionCaught(Throwable)` to forward to the next `ChannelHandler` in the `ChannelPipeline`.
`void`	`flush(ChannelHandlerContext ctx)` Called once a flush operation is made.
`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(ChannelHandlerContext ctx)` Do nothing by default, sub-classes may override this method.
`void`	`handlerRemoved0(ChannelHandlerContext ctx)` Gets called after the `ByteToMessageDecoder` was removed from the actual context and it doesn't handle events anymore.
`Future<Channel>`	`handshakeFuture()` Returns a `Future` that will get notified once the current TLS handshake completes.
`static boolean`	`isEncrypted(ByteBuf buffer)` Returns `true` if the given `ByteBuf` is encrypted.
`void`	`read(ChannelHandlerContext ctx)` Intercepts `ChannelHandlerContext.read()`.
`Future<Channel>`	`renegotiate()` Performs TLS renegotiation.
`Future<Channel>`	`renegotiate(Promise<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)`
`Future<Channel>`	`sslCloseFuture()` Return the `Future` that will get notified if the inbound of the `SSLEngine` is closed.
`void`	`write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise)` Called once a write operation is made.

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)
```
  - 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 Future<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 ChannelFuture close()
```
    Deprecated. use ChannelOutboundInvoker.close() or ChannelOutboundInvoker.close()
    
    Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine.
  - close
```
@Deprecated
public ChannelFuture close(ChannelPromise promise)
```
    Deprecated. use ChannelOutboundInvoker.close() or ChannelOutboundInvoker.close()
    
    See close()
  - sslCloseFuture
```
public Future<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(ChannelHandlerContext ctx)
                     throws Exception
```
    Description copied from class: ByteToMessageDecoder
    
    Gets called after the ByteToMessageDecoder was removed from the actual context and it doesn't handle events anymore.
    
    Overrides:
    
    handlerRemoved0 in class ByteToMessageDecoder
    
    Throws:
    
    Exception
  - bind
```
public void bind(ChannelHandlerContext ctx,
                 SocketAddress localAddress,
                 ChannelPromise promise)
          throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a bind operation is made.
    
    Specified by:
    
    bind in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the bind operation is made
    
    localAddress - the SocketAddress to which it should bound
    
    promise - the ChannelPromise to notify once the operation completes
    
    Throws:
    
    Exception - thrown if an error occurs
  - connect
```
public void connect(ChannelHandlerContext ctx,
                    SocketAddress remoteAddress,
                    SocketAddress localAddress,
                    ChannelPromise promise)
             throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a connect operation is made.
    
    Specified by:
    
    connect in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the connect operation is made
    
    remoteAddress - the SocketAddress to which it should connect
    
    localAddress - the SocketAddress which is used as source on connect
    
    promise - the ChannelPromise to notify once the operation completes
    
    Throws:
    
    Exception - thrown if an error occurs
  - deregister
```
public void deregister(ChannelHandlerContext ctx,
                       ChannelPromise promise)
                throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a deregister operation is made from the current registered EventLoop.
    
    Specified by:
    
    deregister in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the close operation is made
    
    promise - the ChannelPromise to notify once the operation completes
    
    Throws:
    
    Exception - thrown if an error occurs
  - disconnect
```
public void disconnect(ChannelHandlerContext ctx,
                       ChannelPromise promise)
                throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a disconnect operation is made.
    
    Specified by:
    
    disconnect in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the disconnect operation is made
    
    promise - the ChannelPromise to notify once the operation completes
    
    Throws:
    
    Exception - thrown if an error occurs
  - close
```
public void close(ChannelHandlerContext ctx,
                  ChannelPromise promise)
           throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a close operation is made.
    
    Specified by:
    
    close in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the close operation is made
    
    promise - the ChannelPromise to notify once the operation completes
    
    Throws:
    
    Exception - thrown if an error occurs
  - read
```
public void read(ChannelHandlerContext ctx)
          throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Intercepts ChannelHandlerContext.read().
    
    Specified by:
    
    read in interface ChannelOutboundHandler
    
    Throws:
    
    Exception
  - write
```
public void write(ChannelHandlerContext ctx,
                  Object msg,
                  ChannelPromise promise)
           throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a write operation is made. The write operation will write the messages through the ChannelPipeline. Those are then ready to be flushed to the actual Channel once Channel.flush() is called
    
    Specified by:
    
    write in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the write operation is made
    
    msg - the message to write
    
    promise - the ChannelPromise to notify once the operation completes
    
    Throws:
    
    Exception - thrown if an error occurs
  - flush
```
public void flush(ChannelHandlerContext ctx)
           throws Exception
```
    Description copied from interface: ChannelOutboundHandler
    
    Called once a flush operation is made. The flush operation will try to flush out all previous written messages that are pending.
    
    Specified by:
    
    flush in interface ChannelOutboundHandler
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the flush operation is made
    
    Throws:
    
    Exception - thrown if an error occurs
  - channelInactive
```
public void channelInactive(ChannelHandlerContext ctx)
                     throws Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireChannelInactive() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    channelInactive in interface ChannelInboundHandler
    
    Overrides:
    
    channelInactive in class ByteToMessageDecoder
    
    Throws:
    
    Exception
  - exceptionCaught
```
public void exceptionCaught(ChannelHandlerContext ctx,
                            Throwable cause)
                     throws Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireExceptionCaught(Throwable) to forward to the next ChannelHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    exceptionCaught in interface ChannelHandler
    
    Specified by:
    
    exceptionCaught in interface ChannelInboundHandler
    
    Overrides:
    
    exceptionCaught in class ChannelInboundHandlerAdapter
    
    Throws:
    
    Exception
  - isEncrypted
```
public static boolean isEncrypted(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(ChannelHandlerContext ctx,
                      ByteBuf in,
                      List<Object> out)
               throws SSLException
```
    Description copied from class: ByteToMessageDecoder
    
    Decode the from one ByteBuf 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.
    
    Specified by:
    
    decode in class ByteToMessageDecoder
    
    Parameters:
    
    ctx - the ChannelHandlerContext which this ByteToMessageDecoder belongs to
    
    in - the ByteBuf from which to read data
    
    out - the List to which decoded messages should be added
    
    Throws:
    
    SSLException
  - channelReadComplete
```
public void channelReadComplete(ChannelHandlerContext ctx)
                         throws Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    channelReadComplete in interface ChannelInboundHandler
    
    Overrides:
    
    channelReadComplete in class ByteToMessageDecoder
    
    Throws:
    
    Exception
  - handlerAdded
```
public void handlerAdded(ChannelHandlerContext ctx)
                  throws Exception
```
    Description copied from class: ChannelHandlerAdapter
    
    Do nothing by default, sub-classes may override this method.
    
    Specified by:
    
    handlerAdded in interface ChannelHandler
    
    Overrides:
    
    handlerAdded in class ChannelHandlerAdapter
    
    Throws:
    
    Exception
  - renegotiate
```
public Future<Channel> renegotiate()
```
    Performs TLS renegotiation.
  - renegotiate
```
public Future<Channel> renegotiate(Promise<Channel> promise)
```
    Performs TLS renegotiation.
  - channelActive
```
public void channelActive(ChannelHandlerContext ctx)
                   throws Exception
```
    Issues an initial TLS handshake once connected when used in client-mode
    
    Specified by:
    
    channelActive in interface ChannelInboundHandler
    
    Overrides:
    
    channelActive in class 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

getCloseNotifyTimeoutMillis

setCloseNotifyTimeout

setCloseNotifyTimeoutMillis

getCloseNotifyFlushTimeoutMillis

setCloseNotifyFlushTimeout

setCloseNotifyFlushTimeoutMillis

getCloseNotifyReadTimeoutMillis

setCloseNotifyReadTimeout

setCloseNotifyReadTimeoutMillis

engine

applicationProtocol

handshakeFuture

close

close

sslCloseFuture

handlerRemoved0

bind

connect

deregister

disconnect

close

read

write

flush

channelInactive

exceptionCaught

isEncrypted

decode

channelReadComplete

handlerAdded

renegotiate

renegotiate

channelActive