Package io.netty.handler.ssl

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

    • Constructor Detail

      • SslHandler

        public SslHandler​(javax.net.ssl.SSLEngine engine)
        Creates a new instance which runs all delegated tasks directly on the EventExecutor.
        Parameters:
        engine - the SSLEngine this handler will use

      • SslHandler

        public SslHandler​(javax.net.ssl.SSLEngine engine,
                  boolean startTls)
        Creates a new instance which runs all delegated tasks directly on the EventExecutor.
        Parameters:
        engine - the SSLEngine this handler will use
        startTls - true if the first write request shouldn't be encrypted by the SSLEngine

      • SslHandler

        public SslHandler​(javax.net.ssl.SSLEngine engine,
                  java.util.concurrent.Executor delegatedTaskExecutor)
        Creates a new instance.
        Parameters:
        engine - the SSLEngine this handler will use
        delegatedTaskExecutor - the Executor that will be used to execute tasks that are returned by SSLEngine.getDelegatedTask().

      • SslHandler

        public SslHandler​(javax.net.ssl.SSLEngine engine,
                  boolean startTls,
                  java.util.concurrent.Executor delegatedTaskExecutor)
        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
        delegatedTaskExecutor - the Executor that will be used to execute tasks that are returned by SSLEngine.getDelegatedTask().