Class SslFilter

java.lang.Object
org.apache.mina.core.filterchain.IoFilterAdapter
org.apache.mina.filter.ssl.SslFilter
All Implemented Interfaces:
IoFilter
public class SslFilter extends IoFilterAdapter
An SSL filter that encrypts and decrypts the data exchanged in the session. Adding this filter triggers SSL handshake procedure immediately by sending a SSL 'hello' message, so you don't need to call startSsl(IoSession) manually unless you are implementing StartTLS (see below). If you don't want the handshake procedure to start immediately, please specify false as autoStart parameter in the constructor.

This filter uses an SSLEngine which was introduced in Java 5, so Java version 5 or above is mandatory to use this filter. And please note that this filter only works for TCP/IP connections.

Implementing StartTLS

You can use DISABLE_ENCRYPTION_ONCE attribute to implement StartTLS: 

public void messageReceived(IoSession session, Object message) {
   if (message instanceof MyStartTLSRequest) {
       // Insert SSLFilter to get ready for handshaking
       session.getFilterChain().addFirst(sslFilter);

       // Disable encryption temporarily.
       // This attribute will be removed by SSLFilter
       // inside the Session.write() call below.
       session.setAttribute(SSLFilter.DISABLE_ENCRYPTION_ONCE, Boolean.TRUE);

       // Write StartTLSResponse which won't be encrypted.
       session.write(new MyStartTLSResponse(OK));

       // Now DISABLE_ENCRYPTION_ONCE attribute is cleared.
       assert session.getAttribute(SSLFilter.DISABLE_ENCRYPTION_ONCE) == null;
   }
}

  • Field Details

    • LOGGER

      private static final org.slf4j.Logger LOGGER
      The logger

    • SSL_SESSION

      public static final AttributeKey SSL_SESSION
      A session attribute key that stores underlying SSLSession for each session.

    • DISABLE_ENCRYPTION_ONCE

      public static final AttributeKey DISABLE_ENCRYPTION_ONCE
      A session attribute key that makes next one write request bypass this filter (not encrypting the data). This is a marker attribute, which means that you can put whatever as its value. (Boolean.TRUE is preferred.) The attribute is automatically removed from the session attribute map as soon as IoSession.write(Object) is invoked, and therefore should be put again if you want to make more messages bypass this filter. This is especially useful when you implement StartTLS.

    • USE_NOTIFICATION

      public static final AttributeKey USE_NOTIFICATION
      A session attribute key that makes this filter to emit a IoHandler.messageReceived(IoSession, Object) event with a special message (SslEvent.SECURED or SslEvent.UNSECURED). This is a marker attribute, which means that you can put whatever as its value. (Boolean.TRUE is preferred.) By default, this filter doesn't emit any events related with SSL session flow control.

    • PEER_ADDRESS

      public static final AttributeKey PEER_ADDRESS
      A session attribute key that should be set to an InetSocketAddress. Setting this attribute causes SSLContext.createSSLEngine(String, int) to be called passing the hostname and port of the InetSocketAddress to get an SSLEngine instance. If not set SSLContext.createSSLEngine() will be called.
      Using this feature SSLSession objects may be cached and reused when in client mode.
      See Also:

    • NEXT_FILTER

      private static final AttributeKey NEXT_FILTER
      An attribute containing the next filter

    • SSL_HANDLER

      private static final AttributeKey SSL_HANDLER

    • sslContext

      final SSLContext sslContext
      The SslContext used

    • autoStart

      private final boolean autoStart
      A flag used to tell the filter to start the handshake immediately

    • START_HANDSHAKE

      public static final boolean START_HANDSHAKE
      A flag used to determinate if the handshake should start immediately
      See Also:

    • CLIENT_HANDSHAKE

      public static final boolean CLIENT_HANDSHAKE
      A flag used to determinate if the handshake should wait for the client to initiate the handshake
      See Also:

    • client

      private boolean client

    • needClientAuth

      private boolean needClientAuth

    • wantClientAuth

      private boolean wantClientAuth

    • identificationAlgorithm

      private String identificationAlgorithm

    • enabledCipherSuites

      private String[] enabledCipherSuites

    • enabledProtocols

      private String[] enabledProtocols

  • Constructor Details

    • SslFilter

      public SslFilter(SSLContext sslContext)
      Creates a new SSL filter using the specified SSLContext. The handshake will start immediately after the filter has been added to the chain.
      Parameters:
      sslContext - The SSLContext to use

    • SslFilter

      public SslFilter(SSLContext sslContext, boolean autoStart)
      Creates a new SSL filter using the specified SSLContext. If the autostart flag is set to true, the handshake will start immediately after the filter has been added to the chain.
      Parameters:
      sslContext - The SSLContext to use
      autoStart - The flag used to tell the filter to start the handshake immediately

  • Method Details

    • getSslSession

      public SSLSession getSslSession(IoSession session)
      Returns the underlying SSLSession for the specified session.
      Parameters:
      session - The current session
      Returns:
      null if no SSLSession is initialized yet.

    • startSsl

      public boolean startSsl(IoSession session) throws SSLException
      (Re)starts SSL session for the specified session if not started yet. Please note that SSL session is automatically started by default, and therefore you don't need to call this method unless you've used TLS closure.
      Parameters:
      session - The session that will be switched to SSL mode
      Returns:
      true if the SSL session has been started, false if already started.
      Throws:
      SSLException - if failed to start the SSL session

    • getSessionInfo

      String getSessionInfo(IoSession session)
      An extended toString() method for sessions. If the SSL handshake is not yet completed, we will print (ssl) in small caps. Once it's completed, we will use SSL capitalized.

    • isSslStarted

      public boolean isSslStarted(IoSession session)
      Parameters:
      session - the session we want to check
      Returns:
      true if and only if the specified session is encrypted/decrypted over SSL/TLS currently. This method will start to return false after TLS close_notify message is sent and any messages written after then is not going to get encrypted.

    • isSecured

      public boolean isSecured(IoSession session)
      Parameters:
      session - the session we want to check
      Returns:
      true if and only if the conditions for isSslStarted(IoSession) are met, and the handhake has completed.

    • stopSsl

      public WriteFuture stopSsl(IoSession session) throws SSLException
      Stops the SSL session by sending TLS close_notify message to initiate TLS closure.
      Parameters:
      session - the IoSession to initiate TLS closure
      Returns:
      The Future for the initiated closure
      Throws:
      SSLException - if failed to initiate TLS closure

    • isUseClientMode

      public boolean isUseClientMode()
      Returns:
      true if the engine is set to use client mode when handshaking.

    • setUseClientMode

      public void setUseClientMode(boolean clientMode)
      Configures the engine to use client (or server) mode when handshaking.
      Parameters:
      clientMode - true when we are in client mode, false when in server mode

    • isNeedClientAuth

      public boolean isNeedClientAuth()
      Returns:
      true if the engine will require client authentication. This option is only useful to engines in the server mode.

    • setNeedClientAuth

      public void setNeedClientAuth(boolean needClientAuth)
      Configures the engine to require client authentication. This option is only useful for engines in the server mode.
      Parameters:
      needClientAuth - A flag set when we need to authenticate the client

    • isWantClientAuth

      public boolean isWantClientAuth()
      Returns:
      true if the engine will request client authentication. This option is only useful to engines in the server mode.

    • setWantClientAuth

      public void setWantClientAuth(boolean wantClientAuth)
      Configures the engine to request client authentication. This option is only useful for engines in the server mode.
      Parameters:
      wantClientAuth - A flag set when we want to check the client authentication

    • getEndpointIdentificationAlgorithm

      public String getEndpointIdentificationAlgorithm()
      Returns:
      the endpoint identification algorithm to be used when SSLEngine is initialized. null means 'use SSLEngine's default.'

    • setEndpointIdentificationAlgorithm

      public void setEndpointIdentificationAlgorithm(String identificationAlgorithm)
      Sets the endpoint identification algorithm to be used when SSLEngine is initialized.
      Parameters:
      identificationAlgorithm - null means 'use SSLEngine's default.'

    • getEnabledCipherSuites

      public String[] getEnabledCipherSuites()
      Returns:
      the list of cipher suites to be enabled when SSLEngine is initialized. null means 'use SSLEngine's default.'

    • setEnabledCipherSuites

      public void setEnabledCipherSuites(String[] cipherSuites)
      Sets the list of cipher suites to be enabled when SSLEngine is initialized.
      Parameters:
      cipherSuites - null means 'use SSLEngine's default.'

    • getEnabledProtocols

      public String[] getEnabledProtocols()
      Returns:
      the list of protocols to be enabled when SSLEngine is initialized. null means 'use SSLEngine's default.'

    • setEnabledProtocols

      public void setEnabledProtocols(String[] protocols)
      Sets the list of protocols to be enabled when SSLEngine is initialized.
      Parameters:
      protocols - null means 'use SSLEngine's default.'

    • onPreAdd

      public void onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter) throws SSLException
      Executed just before the filter is added into the chain, we do :
      • check that we don't have a SSL filter already present
      • we update the next filter
      • we create the SSL handler helper class
      • and we store it into the session's Attributes
      Specified by:
      onPreAdd in interface IoFilter
      Overrides:
      onPreAdd in class IoFilterAdapter
      Parameters:
      parent - the parent who called this method
      name - the name assigned to this filter
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      Throws:
      SSLException

    • onPostAdd

      public void onPostAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter) throws SSLException
      Description copied from class: IoFilterAdapter
      Invoked after this filter is added to the specified parent. Please note that this method can be invoked more than once if this filter is added to more than one parents. This method is not invoked before IoFilter.init() is invoked.
      Specified by:
      onPostAdd in interface IoFilter
      Overrides:
      onPostAdd in class IoFilterAdapter
      Parameters:
      parent - the parent who called this method
      name - the name assigned to this filter
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      Throws:
      SSLException

    • onPreRemove

      public void onPreRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter) throws SSLException
      Description copied from class: IoFilterAdapter
      Invoked before this filter is removed from the specified parent. Please note that this method can be invoked more than once if this filter is removed from more than one parents. This method is always invoked before IoFilter.destroy() is invoked.
      Specified by:
      onPreRemove in interface IoFilter
      Overrides:
      onPreRemove in class IoFilterAdapter
      Parameters:
      parent - the parent who called this method
      name - the name assigned to this filter
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      Throws:
      SSLException

    • sessionClosed

      public void sessionClosed(IoFilter.NextFilter nextFilter, IoSession session) throws SSLException
      Description copied from class: IoFilterAdapter
      Filters IoHandler.sessionClosed(IoSession) event.
      Specified by:
      sessionClosed in interface IoFilter
      Overrides:
      sessionClosed in class IoFilterAdapter
      Parameters:
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      session - The IoSession which has received this event
      Throws:
      SSLException

    • messageReceived

      public void messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message) throws SSLException
      Description copied from class: IoFilterAdapter
      Filters IoHandler.messageReceived(IoSession,Object) event.
      Specified by:
      messageReceived in interface IoFilter
      Overrides:
      messageReceived in class IoFilterAdapter
      Parameters:
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      session - The IoSession which has received this event
      message - The received message
      Throws:
      SSLException

    • messageSent

      public void messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
      Description copied from class: IoFilterAdapter
      Filters IoHandler.messageSent(IoSession,Object) event.
      Specified by:
      messageSent in interface IoFilter
      Overrides:
      messageSent in class IoFilterAdapter
      Parameters:
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      session - The IoSession which has received this event
      writeRequest - The WriteRequest that contains the sent message

    • exceptionCaught

      public void exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause) throws Exception
      Description copied from class: IoFilterAdapter
      Filters IoHandler.exceptionCaught(IoSession,Throwable) event.
      Specified by:
      exceptionCaught in interface IoFilter
      Overrides:
      exceptionCaught in class IoFilterAdapter
      Parameters:
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      session - The IoSession which has received this event
      cause - The exception that cause this event to be received
      Throws:
      Exception - If an error occurred while processing the event

    • isCloseNotify

      private boolean isCloseNotify(Object message)

    • filterWrite

      public void filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws SSLException
      Description copied from class: IoFilterAdapter
      Filters IoSession.write(Object) method invocation.
      Specified by:
      filterWrite in interface IoFilter
      Overrides:
      filterWrite in class IoFilterAdapter
      Parameters:
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      session - The IoSession which has to process this invocation
      writeRequest - The WriteRequest to process
      Throws:
      SSLException

    • filterClose

      public void filterClose(IoFilter.NextFilter nextFilter, IoSession session) throws SSLException
      Description copied from class: IoFilterAdapter
      Filters IoSession.closeNow() or a IoSession.closeOnFlush() method invocations.
      Specified by:
      filterClose in interface IoFilter
      Overrides:
      filterClose in class IoFilterAdapter
      Parameters:
      nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
      session - The IoSession which has to process this method invocation
      Throws:
      SSLException

    • initiateHandshake

      public void initiateHandshake(IoSession session) throws SSLException
      Initiate the SSL handshake. This can be invoked if you have set the 'autoStart' to false when creating the SslFilter instance.
      Parameters:
      session - The session for which the SSL handshake should be done
      Throws:
      SSLException - If the handshake failed

    • initiateHandshake

      private void initiateHandshake(IoFilter.NextFilter nextFilter, IoSession session) throws SSLException
      Throws:
      SSLException

    • initiateClosure

      private WriteFuture initiateClosure(IoFilter.NextFilter nextFilter, IoSession session) throws SSLException
      Throws:
      SSLException

    • handleSslData

      private void handleSslData(IoFilter.NextFilter nextFilter, SslHandler sslHandler) throws SSLException
      Throws:
      SSLException

    • handleAppDataRead

      private void handleAppDataRead(IoFilter.NextFilter nextFilter, SslHandler sslHandler)

    • getSslSessionHandler

      private SslHandler getSslSessionHandler(IoSession session)