Package org.apache.mina.filter

Class SSLFilter

java.lang.Object
org.apache.mina.common.IoFilterAdapter
org.apache.mina.filter.SSLFilter
All Implemented Interfaces:
org.apache.mina.common.IoFilter
public class SSLFilter extends org.apache.mina.common.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).

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.

This filter logs debug information using SessionLog.

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 temporarilly.
        // 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;
    }
 }

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    SSLFilter.SSLFilterMessage
    A message that is sent from SSLFilter when the connection became secure or is not secure anymore.

    Nested classes/interfaces inherited from interface org.apache.mina.common.IoFilter

    org.apache.mina.common.IoFilter.NextFilter, org.apache.mina.common.IoFilter.WriteRequest

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DISABLE_ENCRYPTION_ONCE
    A session attribute key that makes next one write request bypass this filter (not encrypting the data).
    static final SSLFilter.SSLFilterMessage
    SESSION_SECURED
    A special message object which is emitted with a IoHandler.messageReceived(IoSession, Object) event when the session is secured and its USE_NOTIFICATION attribute is set.
    static final SSLFilter.SSLFilterMessage
    SESSION_UNSECURED
    A special message object which is emitted with a IoHandler.messageReceived(IoSession, Object) event when the session is not secure anymore and its USE_NOTIFICATION attribute is set.
    static final String
    SSL_SESSION
    A session attribute key that stores underlying SSLSession for each session.
    static final String
    USE_NOTIFICATION
    A session attribute key that makes this filter to emit a IoHandler.messageReceived(IoSession, Object) event with a special message (SESSION_SECURED or SESSION_UNSECURED).

  • Constructor Summary

    Constructors
    Constructor
    Description
    SSLFilter(SSLContext sslContext)
    Creates a new SSL filter using the specified SSLContext.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    filterClose(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session)
     
    void
    filterWrite(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, org.apache.mina.common.IoFilter.WriteRequest writeRequest)
     
    String[]
    getEnabledCipherSuites()
    Returns the list of cipher suites to be enabled when SSLEngine is initialized.
    String[]
    getEnabledProtocols()
    Returns the list of protocols to be enabled when SSLEngine is initialized.
    SSLSession
    getSSLSession(org.apache.mina.common.IoSession session)
    Returns the underlying SSLSession for the specified session.
    boolean
    isNeedClientAuth()
    Returns true if the engine will require client authentication.
    boolean
    isSSLStarted(org.apache.mina.common.IoSession session)
    Returns true if and only if the specified session is encrypted/decrypted over SSL/TLS currently.
    boolean
    isUseClientMode()
    Returns true if the engine is set to use client mode when handshaking.
    boolean
    isWantClientAuth()
    Returns true if the engine will request client authentication.
    void
    messageReceived(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message)
     
    void
    messageSent(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message)
     
    void
    onPostAdd(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter)
     
    void
    onPreAdd(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter)
     
    void
    onPreRemove(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter)
     
    void
    sessionClosed(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session)
     
    void
    setEnabledCipherSuites(String[] cipherSuites)
    Sets the list of cipher suites to be enabled when SSLEngine is initialized.
    void
    setEnabledProtocols(String[] protocols)
    Sets the list of protocols to be enabled when SSLEngine is initialized.
    void
    setNeedClientAuth(boolean needClientAuth)
    Configures the engine to require client authentication.
    void
    setUseClientMode(boolean clientMode)
    Configures the engine to use client (or server) mode when handshaking.
    void
    setWantClientAuth(boolean wantClientAuth)
    Configures the engine to request client authentication.
    boolean
    startSSL(org.apache.mina.common.IoSession session)
    (Re)starts SSL session for the specified session if not started yet.
    org.apache.mina.common.WriteFuture
    stopSSL(org.apache.mina.common.IoSession session)
    Stops the SSL session by sending TLS close_notify message to initiate TLS closure.

    Methods inherited from class org.apache.mina.common.IoFilterAdapter

    destroy, exceptionCaught, init, onPostRemove, sessionCreated, sessionIdle, sessionOpened

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • SSL_SESSION

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

    • DISABLE_ENCRYPTION_ONCE

      public static final String 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 String USE_NOTIFICATION
      A session attribute key that makes this filter to emit a IoHandler.messageReceived(IoSession, Object) event with a special message (SESSION_SECURED or SESSION_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.

    • SESSION_SECURED

      public static final SSLFilter.SSLFilterMessage SESSION_SECURED
      A special message object which is emitted with a IoHandler.messageReceived(IoSession, Object) event when the session is secured and its USE_NOTIFICATION attribute is set.

    • SESSION_UNSECURED

      public static final SSLFilter.SSLFilterMessage SESSION_UNSECURED
      A special message object which is emitted with a IoHandler.messageReceived(IoSession, Object) event when the session is not secure anymore and its USE_NOTIFICATION attribute is set.

  • Constructor Details

    • SSLFilter

      public SSLFilter(SSLContext sslContext)
      Creates a new SSL filter using the specified SSLContext.

  • Method Details

    • getSSLSession

      public SSLSession getSSLSession(org.apache.mina.common.IoSession session)
      Returns the underlying SSLSession for the specified session.
      Returns:
      null if no SSLSession is initialized yet.

    • startSSL

      public boolean startSSL(org.apache.mina.common.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.
      Returns:
      true if the SSL session has been started, false if already started.
      Throws:
      SSLException - if failed to start the SSL session

    • isSSLStarted

      public boolean isSSLStarted(org.apache.mina.common.IoSession session)
      Returns true if and only if the specified session is encrypted/decrypted over SSL/TLS currently. This method will start to retun false after TLS close_notify message is sent and any messages written after then is not goinf to get encrypted.

    • stopSSL

      public org.apache.mina.common.WriteFuture stopSSL(org.apache.mina.common.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
      Throws:
      SSLException - if failed to initiate TLS closure
      IllegalArgumentException - if this filter is not managing the specified session

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

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

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

    • getEnabledCipherSuites

      public String[] getEnabledCipherSuites()
      Returns the list of cipher suites to be enabled when SSLEngine is initialized.
      Returns:
      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.
      Returns:
      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(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) throws SSLException
      Specified by:
      onPreAdd in interface org.apache.mina.common.IoFilter
      Overrides:
      onPreAdd in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException

    • onPostAdd

      public void onPostAdd(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) throws SSLException
      Specified by:
      onPostAdd in interface org.apache.mina.common.IoFilter
      Overrides:
      onPostAdd in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException

    • onPreRemove

      public void onPreRemove(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) throws SSLException
      Specified by:
      onPreRemove in interface org.apache.mina.common.IoFilter
      Overrides:
      onPreRemove in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException

    • sessionClosed

      public void sessionClosed(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session) throws SSLException
      Specified by:
      sessionClosed in interface org.apache.mina.common.IoFilter
      Overrides:
      sessionClosed in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException

    • messageReceived

      public void messageReceived(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message) throws SSLException
      Specified by:
      messageReceived in interface org.apache.mina.common.IoFilter
      Overrides:
      messageReceived in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException

    • messageSent

      public void messageSent(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message)
      Specified by:
      messageSent in interface org.apache.mina.common.IoFilter
      Overrides:
      messageSent in class org.apache.mina.common.IoFilterAdapter

    • filterWrite

      public void filterWrite(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, org.apache.mina.common.IoFilter.WriteRequest writeRequest) throws SSLException
      Specified by:
      filterWrite in interface org.apache.mina.common.IoFilter
      Overrides:
      filterWrite in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException

    • filterClose

      public void filterClose(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session) throws SSLException
      Specified by:
      filterClose in interface org.apache.mina.common.IoFilter
      Overrides:
      filterClose in class org.apache.mina.common.IoFilterAdapter
      Throws:
      SSLException