org.apache.mina.filter.ssl

## 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 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;
          }
       }

  Author:
    Apache MINA Project

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and 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.core.filterchain.IoFilter

      `IoFilter.NextFilter`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static AttributeKey` | `DISABLE_ENCRYPTION_ONCE` A session attribute key that makes next one write request bypass this filter (not encrypting the data).
    `static AttributeKey` | `PEER_ADDRESS` A session attribute key that should be set to an `InetSocketAddress`.
    `static 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 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 AttributeKey` | `SSL_SESSION` A session attribute key that stores underlying `SSLSession` for each session.
    `static AttributeKey` | `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 and Description
    `SslFilter(SSLContext sslContext)` Creates a new SSL filter using the specified `SSLContext`.
    `SslFilter(SSLContext sslContext, boolean autoStart)` Creates a new SSL filter using the specified `SSLContext`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause)` Filters `IoHandler.exceptionCaught(IoSession,Throwable)` event.
    `void` | `filterClose(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoSession.close()` method invocation.
    `void` | `filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)` Filters `IoSession.write(Object)` method invocation.
    `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(IoSession session)` Returns the underlying `SSLSession` for the specified session.
    `boolean` | `isNeedClientAuth()` Returns `true` if the engine will require client authentication.
    `boolean` | `isSslStarted(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(IoFilter.NextFilter nextFilter, IoSession session, Object message)` Filters `IoHandler.messageReceived(IoSession,Object)` event.
    `void` | `messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)` Filters `IoHandler.messageSent(IoSession,Object)` event.
    `void` | `onPostAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked after this filter is added to the specified `parent`.
    `void` | `onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` 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
    `void` | `onPreRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked before this filter is removed from the specified `parent`.
    `void` | `sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoHandler.sessionClosed(IoSession)` event.
    `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(IoSession session)` (Re)starts SSL session for the specified `session` if not started yet.
    `WriteFuture` | `stopSsl(IoSession session)` Stops the SSL session by sending TLS `close_notify` message to initiate TLS closure.

    - ### Methods inherited from class org.apache.mina.core.filterchain.IoFilterAdapter

      `destroy, init, onPostRemove, sessionCreated, sessionIdle, sessionOpened, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### 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 (`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.

    - #### 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:
        `SSLContext.createSSLEngine(String, int)`

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

    - #### SslFilter

          public SslFilter(SSLContext sslContext)

      Creates a new SSL filter using the specified `SSLContext`. The handshake will start immediately.

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

  - ### Method Detail

    - #### getSslSession

          public SSLSession getSslSession(IoSession session)

      Returns the underlying `SSLSession` for the specified 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.
      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)

      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.

    - #### 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
      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(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`
      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`
      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`

    - #### 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`
      Throws:
        `Exception`

    - #### 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`
      Throws:
        `SSLException`

    - #### filterClose

          public void filterClose(IoFilter.NextFilter nextFilter,
                         IoSession session)
                           throws SSLException

      Description copied from class: `IoFilterAdapter`
      Filters `IoSession.close()` method invocation.
      Specified by:
        `filterClose` in interface `IoFilter`
      Overrides:
        `filterClose` in class `IoFilterAdapter`
      Throws:
        `SSLException`

Copyright © 2004-2012 Apache MINA Project. All Rights Reserved.