org.apache.mina.filter

Class SSLFilter

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

Nested Class Summary

static class
SSLFilter.SSLFilterMessage
A message that is sent from SSLFilter when the connection became secure or is not secure anymore.

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(NextFilter nextFilter, IoSession session)
void
filterWrite(NextFilter nextFilter, IoSession session, 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(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(NextFilter nextFilter, IoSession session, Object message)
void
messageSent(NextFilter nextFilter, IoSession session, Object message)
void
onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter)
void
onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter)
void
onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter)
void
sessionClosed(NextFilter nextFilter, 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(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, filterClose, filterWrite, init, messageReceived, messageSent, onPostAdd, onPostRemove, onPreAdd, onPreRemove, sessionClosed, sessionCreated, sessionIdle, sessionOpened

Field Details

DISABLE_ENCRYPTION_ONCE

public static final String DISABLE_ENCRYPTION_ONCE

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.

SSL_SESSION

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

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.

Constructor Details

SSLFilter

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

Method Details

filterClose

public void filterClose(NextFilter nextFilter,
                        IoSession session)
            throws SSLException
Overrides:
filterClose in interface IoFilterAdapter

filterWrite

public void filterWrite(NextFilter nextFilter,
                        IoSession session,
                        WriteRequest writeRequest)
            throws SSLException
Overrides:
filterWrite in interface IoFilterAdapter

getEnabledCipherSuites

public String[] getEnabledCipherSuites()
Returns the list of cipher suites to be enabled when SSLEngine is initialized.
Returns:
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.'

getSSLSession

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

isNeedClientAuth

public boolean isNeedClientAuth()
Returns true if the engine will require client authentication. This option is only useful to engines in the server mode.

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.

isUseClientMode

public boolean isUseClientMode()
Returns true if the engine is set to use client mode when handshaking.

isWantClientAuth

public boolean isWantClientAuth()
Returns true if the engine will request client authentication. This option is only useful to engines in the server mode.

messageReceived

public void messageReceived(NextFilter nextFilter,
                            IoSession session,
                            Object message)
            throws SSLException
Overrides:
messageReceived in interface IoFilterAdapter

messageSent

public void messageSent(NextFilter nextFilter,
                        IoSession session,
                        Object message)
Overrides:
messageSent in interface IoFilterAdapter

onPostAdd

public void onPostAdd(IoFilterChain parent,
                      String name,
                      NextFilter nextFilter)
            throws SSLException
Overrides:
onPostAdd in interface IoFilterAdapter

onPreAdd

public void onPreAdd(IoFilterChain parent,
                     String name,
                     NextFilter nextFilter)
            throws SSLException
Overrides:
onPreAdd in interface IoFilterAdapter

onPreRemove

public void onPreRemove(IoFilterChain parent,
                        String name,
                        NextFilter nextFilter)
            throws SSLException
Overrides:
onPreRemove in interface IoFilterAdapter

sessionClosed

public void sessionClosed(NextFilter nextFilter,
                          IoSession session)
            throws SSLException
Overrides:
sessionClosed in interface IoFilterAdapter

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

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

setNeedClientAuth

public void setNeedClientAuth(boolean needClientAuth)
Configures the engine to require client authentication. This option is only useful for engines in the server mode.

setUseClientMode

public void setUseClientMode(boolean clientMode)
Configures the engine to use client (or server) mode when handshaking.

setWantClientAuth

public void setWantClientAuth(boolean wantClientAuth)
Configures the engine to request client authentication. This option is only useful for engines in the server mode.

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.

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