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

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`SslFilter.EncryptedWriteRequest`
`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
`private boolean`	`autoStart` A flag used to tell the filter to start the handshake immediately
`private boolean`	`client`
`static AttributeKey`	`DISABLE_ENCRYPTION_ONCE` A session attribute key that makes next one write request bypass this filter (not encrypting the data).
`private java.lang.String[]`	`enabledCipherSuites`
`private java.lang.String[]`	`enabledProtocols`
`private static org.slf4j.Logger`	`LOGGER` The logger
`private boolean`	`needClientAuth`
`private static AttributeKey`	`NEXT_FILTER`
`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.
`private static AttributeKey`	`SSL_HANDLER`
`static AttributeKey`	`SSL_SESSION` A session attribute key that stores underlying `SSLSession` for each session.
`(package private) javax.net.ssl.SSLContext`	`sslContext` The SslContext used
`private static boolean`	`START_HANDSHAKE` A flag used to determinate if the handshake should start immediately
`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`).
`private boolean`	`wantClientAuth`

Constructor Summary

Constructors
Constructor and Description
`SslFilter(javax.net.ssl.SSLContext sslContext)` Creates a new SSL filter using the specified `SSLContext`.
`SslFilter(javax.net.ssl.SSLContext sslContext, boolean autoStart)` Creates a new SSL filter using the specified `SSLContext`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, java.lang.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.
`java.lang.String[]`	`getEnabledCipherSuites()` Returns the list of cipher suites to be enabled when `SSLEngine` is initialized.
`java.lang.String[]`	`getEnabledProtocols()` Returns the list of protocols to be enabled when `SSLEngine` is initialized.
`(package private) java.lang.String`	`getSessionInfo(IoSession session)` An extended toString() method for sessions.
`javax.net.ssl.SSLSession`	`getSslSession(IoSession session)` Returns the underlying `SSLSession` for the specified session.
`private SslHandler`	`getSslSessionHandler(IoSession session)`
`private void`	`handleAppDataRead(IoFilter.NextFilter nextFilter, SslHandler sslHandler)`
`private void`	`handleSslData(IoFilter.NextFilter nextFilter, SslHandler sslHandler)`
`private WriteFuture`	`initiateClosure(IoFilter.NextFilter nextFilter, IoSession session)`
`private void`	`initiateHandshake(IoFilter.NextFilter nextFilter, IoSession session)`
`private boolean`	`isCloseNotify(java.lang.Object message)`
`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, java.lang.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, java.lang.String name, IoFilter.NextFilter nextFilter)` Invoked after this filter is added to the specified `parent`.
`void`	`onPreAdd(IoFilterChain parent, java.lang.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, java.lang.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(java.lang.String[] cipherSuites)` Sets the list of cipher suites to be enabled when `SSLEngine` is initialized.
`void`	`setEnabledProtocols(java.lang.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, inputClosed, onPostRemove, sessionCreated, sessionIdle, sessionOpened, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - LOGGER
```
private static final org.slf4j.Logger LOGGER
```
    The logger
  - 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.
  - NEXT_FILTER
```
private static final AttributeKey NEXT_FILTER
```
  - SSL_HANDLER
```
private static final AttributeKey SSL_HANDLER
```
  - sslContext
```
final javax.net.ssl.SSLContext sslContext
```
    The SslContext used
  - autoStart
```
private final boolean autoStart
```
    A flag used to tell the filter to start the handshake immediately
  - START_HANDSHAKE
```
private static final boolean START_HANDSHAKE
```
    A flag used to determinate if the handshake should start immediately
    
    See Also:
    
    Constant Field Values
  - client
```
private boolean client
```
  - needClientAuth
```
private boolean needClientAuth
```
  - wantClientAuth
```
private boolean wantClientAuth
```
  - enabledCipherSuites
```
private java.lang.String[] enabledCipherSuites
```
  - enabledProtocols
```
private java.lang.String[] enabledProtocols
```
- Constructor Detail
  - SslFilter
```
public SslFilter(javax.net.ssl.SSLContext sslContext)
```
    Creates a new SSL filter using the specified SSLContext. The handshake will start immediately.
  - SslFilter
```
public SslFilter(javax.net.ssl.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 javax.net.ssl.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 javax.net.ssl.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:
    
    javax.net.ssl.SSLException - if failed to start the SSL session
  - getSessionInfo
```
java.lang.String getSessionInfo(IoSession session)
```
    An extended toString() method for sessions. If the SSL handshake is not yet completed, we will print (ssl) in small caps. Once it's completed, we will use SSL capitalized.
  - 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 javax.net.ssl.SSLException
```
    Stops the SSL session by sending TLS close_notify message to initiate TLS closure.
    
    Parameters:
    
    session - the IoSession to initiate TLS closure
    
    Throws:
    
    javax.net.ssl.SSLException - if failed to initiate TLS closure
    
    java.lang.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 java.lang.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(java.lang.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 java.lang.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(java.lang.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,
                     java.lang.String name,
                     IoFilter.NextFilter nextFilter)
              throws javax.net.ssl.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:
    
    javax.net.ssl.SSLException
  - onPostAdd
```
public void onPostAdd(IoFilterChain parent,
                      java.lang.String name,
                      IoFilter.NextFilter nextFilter)
               throws javax.net.ssl.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:
    
    javax.net.ssl.SSLException
  - onPreRemove
```
public void onPreRemove(IoFilterChain parent,
                        java.lang.String name,
                        IoFilter.NextFilter nextFilter)
                 throws javax.net.ssl.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:
    
    javax.net.ssl.SSLException
  - sessionClosed
```
public void sessionClosed(IoFilter.NextFilter nextFilter,
                          IoSession session)
                   throws javax.net.ssl.SSLException
```
    Description copied from class: IoFilterAdapter
    
    Filters IoHandler.sessionClosed(IoSession) event.
    
    Specified by:
    
    sessionClosed in interface IoFilter
    
    Overrides:
    
    sessionClosed in class IoFilterAdapter
    
    Parameters:
    
    nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
    
    session - The IoSession which has received this event
    
    Throws:
    
    javax.net.ssl.SSLException
  - messageReceived
```
public void messageReceived(IoFilter.NextFilter nextFilter,
                            IoSession session,
                            java.lang.Object message)
                     throws javax.net.ssl.SSLException
```
    Description copied from class: IoFilterAdapter
    
    Filters IoHandler.messageReceived(IoSession,Object) event.
    
    Specified by:
    
    messageReceived in interface IoFilter
    
    Overrides:
    
    messageReceived in class IoFilterAdapter
    
    Parameters:
    
    nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
    
    session - The IoSession which has received this event
    
    message - The received message
    
    Throws:
    
    javax.net.ssl.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
    
    Parameters:
    
    nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
    
    session - The IoSession which has received this event
    
    writeRequest - The WriteRequest that contains the sent message
  - exceptionCaught
```
public void exceptionCaught(IoFilter.NextFilter nextFilter,
                            IoSession session,
                            java.lang.Throwable cause)
                     throws java.lang.Exception
```
    Description copied from class: IoFilterAdapter
    
    Filters IoHandler.exceptionCaught(IoSession,Throwable) event.
    
    Specified by:
    
    exceptionCaught in interface IoFilter
    
    Overrides:
    
    exceptionCaught in class IoFilterAdapter
    
    Parameters:
    
    nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
    
    session - The IoSession which has received this event
    
    cause - The exception that cause this event to be received
    
    Throws:
    
    java.lang.Exception
  - isCloseNotify
```
private boolean isCloseNotify(java.lang.Object message)
```
  - filterWrite
```
public void filterWrite(IoFilter.NextFilter nextFilter,
                        IoSession session,
                        WriteRequest writeRequest)
                 throws javax.net.ssl.SSLException
```
    Description copied from class: IoFilterAdapter
    
    Filters IoSession.write(Object) method invocation.
    
    Specified by:
    
    filterWrite in interface IoFilter
    
    Overrides:
    
    filterWrite in class IoFilterAdapter
    
    Parameters:
    
    nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
    
    session - The IoSession which has to process this invocation
    
    writeRequest - The WriteRequest to process
    
    Throws:
    
    javax.net.ssl.SSLException
  - filterClose
```
public void filterClose(IoFilter.NextFilter nextFilter,
                        IoSession session)
                 throws javax.net.ssl.SSLException
```
    Description copied from class: IoFilterAdapter
    
    Filters IoSession.close() method invocation.
    
    Specified by:
    
    filterClose in interface IoFilter
    
    Overrides:
    
    filterClose in class IoFilterAdapter
    
    Parameters:
    
    nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
    
    session - The IoSession which has to process this method invocation
    
    Throws:
    
    javax.net.ssl.SSLException
  - initiateHandshake
```
private void initiateHandshake(IoFilter.NextFilter nextFilter,
                               IoSession session)
                        throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - initiateClosure
```
private WriteFuture initiateClosure(IoFilter.NextFilter nextFilter,
                                    IoSession session)
                             throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - handleSslData
```
private void handleSslData(IoFilter.NextFilter nextFilter,
                           SslHandler sslHandler)
                    throws javax.net.ssl.SSLException
```
    Throws:
    
    javax.net.ssl.SSLException
  - handleAppDataRead
```
private void handleAppDataRead(IoFilter.NextFilter nextFilter,
                               SslHandler sslHandler)
```
  - getSslSessionHandler
```
private SslHandler getSslSessionHandler(IoSession session)
```

Class SslFilter

Implementing StartTLS

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.mina.core.filterchain.IoFilter

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

LOGGER

SSL_SESSION

DISABLE_ENCRYPTION_ONCE

USE_NOTIFICATION

PEER_ADDRESS

SESSION_SECURED

SESSION_UNSECURED

NEXT_FILTER

SSL_HANDLER

sslContext

autoStart

START_HANDSHAKE

client

needClientAuth

wantClientAuth

enabledCipherSuites

enabledProtocols

Constructor Detail

SslFilter

SslFilter

Method Detail

getSslSession

startSsl

getSessionInfo

isSslStarted

stopSsl

isUseClientMode

setUseClientMode

isNeedClientAuth

setNeedClientAuth

isWantClientAuth

setWantClientAuth

getEnabledCipherSuites

setEnabledCipherSuites

getEnabledProtocols

setEnabledProtocols

onPreAdd

onPostAdd

onPreRemove

sessionClosed

messageReceived

messageSent

exceptionCaught

isCloseNotify

filterWrite

filterClose

initiateHandshake

initiateClosure

handleSslData

handleAppDataRead

getSslSessionHandler