Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.mina.filter
Class SSLFilter

    java.lang.Object
      org.apache.mina.common.IoFilterAdapter
          org.apache.mina.filter.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).

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

Version:
  $Rev: 587373 $, $Date: 2007-10-23 04:54:05 +0200 (Tue, 23 Oct 2007) $
Author:
  The Apache Directory Project (mina-dev@directory.apache.org)

Nested Class Summary
`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
`IoFilter.NextFilter, IoFilter.WriteRequest`

Field Summary
`static String` | `DISABLE_ENCRYPTION_ONCE` A session attribute key that makes next one write request bypass this filter (not encrypting the data).
`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 String` | `SSL_SESSION` A session attribute key that stores underlying `SSLSession` for each session.
`static 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
`SSLFilter(SSLContext sslContext)` Creates a new SSL filter using the specified `SSLContext`.

Method Summary
`void` | `filterClose(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoSession.close()` method invocation.
`void` | `filterWrite(IoFilter.NextFilter nextFilter, IoSession session, IoFilter.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, Object message)` 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)` Invoked before this filter is added to the specified `parent`.
`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.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 Detail

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

### SSLFilter

    public SSLFilter(SSLContext sslContext)

  Creates a new SSL filter using the specified `SSLContext`.

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 retun `false` after TLS `close_notify` message is sent and any messages written after then is not goinf 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

  Description copied from interface: `IoFilter`
  Invoked before 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:
    `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 interface: `IoFilter`
  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 interface: `IoFilter`
  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 interface: `IoFilter`
  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 interface: `IoFilter`
  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,
                            Object message)

  Description copied from interface: `IoFilter`
  Filters `IoHandler.messageSent(IoSession,Object)` event.

  Specified by:
    `messageSent` in interface `IoFilter`
  Overrides:
    `messageSent` in class `IoFilterAdapter`

### filterWrite

    public void filterWrite(IoFilter.NextFilter nextFilter,
                            IoSession session,
                            IoFilter.WriteRequest writeRequest)
                     throws SSLException

  Description copied from interface: `IoFilter`
  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 interface: `IoFilter`
  Filters `IoSession.close()` method invocation.

  Specified by:
    `filterClose` in interface `IoFilter`
  Overrides:
    `filterClose` in class `IoFilterAdapter`
  Throws:
    `SSLException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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