Package org.apache.mina.filter.ssl

Class 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;
    }
 }
    Author:
    Apache MINA Project

    • Constructor Detail

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

      • 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

      • 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

      • 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

      • 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