SslFilter (Apache MINA 2.0.4 API Documentation)

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