SSLFilter (Apache MINA API Documentation)

java.lang.Object
- org.apache.mina.io.IoFilterAdapter
- - org.apache.mina.io.filter.SSLFilter

All Implemented Interfaces:: IoFilter

public class SSLFilter
extends IoFilterAdapter

An SSL filter that encrypts and decrypts the data exchanged in the session. 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 Logger.

Implementing StartTLS

You can use DISABLE_ENCRYPTION_ONCE attribute to implement StartTLS:

 public void messageReceived(ProtocolSession session, Object message) {
    if (message instanceof MyStartTLSRequest) {
        // Insert SSLFilter to get ready for handshaking
        IoSession ioSession = ((IoProtocolSession) session).getIoSession();
        ioSession.getFilterChain().addLast(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: 326583 $, $Date: 2005-10-19 17:36:22 +0200 (Wed, 19 Oct 2005) $
Author:: The Apache Directory Project (dev@directory.apache.org)

Nested Class Summary
- Nested classes/interfaces inherited from interface org.apache.mina.io.IoFilter
  IoFilter.NextFilter

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`DISABLE_ENCRYPTION_ONCE` A session attribute key that makes next one write request bypass this filter (not encrypting the data).
`static java.lang.String`	`SSL_SESSION` A session attribute key that stores underlying `SSLSession` for each session.

Constructor Summary

Constructors
Constructor and Description

SSLFilter(javax.net.ssl.SSLContext sslContext)
Creates a new SSL filter using the specified SSLContext.

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`dataRead(IoFilter.NextFilter nextFilter, IoSession session, ByteBuffer buf)` Filters `IoHandler.dataRead(IoSession, ByteBuffer)` event.
`void`	`dataWritten(IoFilter.NextFilter nextFilter, IoSession session, java.lang.Object marker)` Filters `IoHandler.dataWritten(IoSession, Object)` event.
`void`	`filterWrite(IoFilter.NextFilter nextFilter, IoSession session, ByteBuffer buf, java.lang.Object marker)` Filters `IoSession.write(ByteBuffer, 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.
`javax.net.ssl.SSLSession`	`getSSLSession(IoSession session)` Returns the underlying `SSLSession` for the specified session.
`boolean`	`isNeedClientAuth()` Returns `true` if the engine will require client authentication.
`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`	`sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoHandler.sessionClosed(IoSession)` event.
`void`	`sessionOpened(IoFilter.NextFilter nextFilter, IoSession session)` Filters `IoHandler.sessionOpened(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.

Methods inherited from class org.apache.mina.io.IoFilterAdapter
exceptionCaught, sessionIdle

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 java.lang.String SSL_SESSION
```
    A session attribute key that stores underlying SSLSession for each session.
  - DISABLE_ENCRYPTION_ONCE
```
public static final java.lang.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(ByteBuffer, 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.
- Constructor Detail
  - SSLFilter
```
public SSLFilter(javax.net.ssl.SSLContext sslContext)
```
    Creates a new SSL filter using the specified SSLContext.
- 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.
  - 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.'
  - sessionOpened
```
public void sessionOpened(IoFilter.NextFilter nextFilter,
                          IoSession session)
                   throws javax.net.ssl.SSLException
```
    Description copied from interface: IoFilter
    
    Filters IoHandler.sessionOpened(IoSession) event.
    
    Specified by:
    
    sessionOpened in interface IoFilter
    
    Overrides:
    
    sessionOpened in class IoFilterAdapter
    
    Throws:
    
    javax.net.ssl.SSLException
  - sessionClosed
```
public void sessionClosed(IoFilter.NextFilter nextFilter,
                          IoSession session)
                   throws javax.net.ssl.SSLException
```
    Description copied from interface: IoFilter
    
    Filters IoHandler.sessionClosed(IoSession) event.
    
    Specified by:
    
    sessionClosed in interface IoFilter
    
    Overrides:
    
    sessionClosed in class IoFilterAdapter
    
    Throws:
    
    javax.net.ssl.SSLException
  - dataRead
```
public void dataRead(IoFilter.NextFilter nextFilter,
                     IoSession session,
                     ByteBuffer buf)
              throws javax.net.ssl.SSLException
```
    Description copied from interface: IoFilter
    
    Filters IoHandler.dataRead(IoSession, ByteBuffer) event.
    
    Specified by:
    
    dataRead in interface IoFilter
    
    Overrides:
    
    dataRead in class IoFilterAdapter
    
    Throws:
    
    javax.net.ssl.SSLException
  - dataWritten
```
public void dataWritten(IoFilter.NextFilter nextFilter,
                        IoSession session,
                        java.lang.Object marker)
```
    Description copied from interface: IoFilter
    
    Filters IoHandler.dataWritten(IoSession, Object) event.
    
    Specified by:
    
    dataWritten in interface IoFilter
    
    Overrides:
    
    dataWritten in class IoFilterAdapter
  - filterWrite
```
public void filterWrite(IoFilter.NextFilter nextFilter,
                        IoSession session,
                        ByteBuffer buf,
                        java.lang.Object marker)
                 throws javax.net.ssl.SSLException
```
    Description copied from interface: IoFilter
    
    Filters IoSession.write(ByteBuffer, Object) method invocation.
    
    Specified by:
    
    filterWrite in interface IoFilter
    
    Overrides:
    
    filterWrite in class IoFilterAdapter
    
    Throws:
    
    javax.net.ssl.SSLException

Class SSLFilter

Implementing StartTLS

Nested Class Summary

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

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.apache.mina.io.IoFilterAdapter

Methods inherited from class java.lang.Object

Field Detail

SSL_SESSION

DISABLE_ENCRYPTION_ONCE

Constructor Detail

SSLFilter

Method Detail

getSSLSession

isUseClientMode

setUseClientMode

isNeedClientAuth

setNeedClientAuth

isWantClientAuth

setWantClientAuth

getEnabledCipherSuites

setEnabledCipherSuites

getEnabledProtocols

setEnabledProtocols

sessionOpened

sessionClosed

dataRead

dataWritten

filterWrite