2.2.x vs 2.1.x differences

The SSL/TLS handling has been totally rewritten in MINA 2.2. This has an impact in many areas.

Removal of the SslFilter.DISABLE_ENCRYPTION_ONCE attribute

This attribute was used in previous MINA versions to insure that we can send some clear text message to the remote peer while establishing the TLS connection when using the startTLS command.

The idea is that the startTLS command is send by an application (a LDAP client, for instance), which tells the server it should establish the SSL/TLS layer. But the problem is that the server should be able to inform the clinet that the SSL/TLS layer is up and running, in clear text, which is not possible as the SSL/TLS layer is already fonctionning…

This kind of chicken/egg problem was solved by giving the opportunity to the SSL/TLS layer to send back the startTLS response to the client in clear text, assuming it’s the first server’s message. A kind of a hack.

In MINA 2.2, this attribute has been removed and replaced by either a filter to be added, or by encapsulating the message that should not be encrypted into an instance that implements the DisableEncryptWriteRequest interface.

Typically, in Apache Directory, we use this filter:

public class StartTlsFilter extends IoFilterAdapter 
{
    /**
     * {@inheritDoc}
     */
    @Override
    public void filterWrite( NextFilter nextFilter, IoSession session, WriteRequest writeRequest ) throws Exception 
    {
        if ( writeRequest.getOriginalMessage() instanceof StartTlsResponse )
        {
            // We need to bypass the SslFilter
            IoFilterChain chain = session.getFilterChain();
            
            for ( IoFilterChain.Entry entry : chain.getAll() )
            {
                IoFilter filter = entry.getFilter();
                
                if ( filter instanceof SslFilter )
                {
                    entry.getNextFilter().filterWrite( session, writeRequest );
                }
            }
        }
        else
        {
            nextFilter.filterWrite( session, writeRequest );
        }
    }
}

As we can see in this piece of code, we check if the message is a startTLS response, and if so, we bypass the SSLFilter, which leads to the message to be send in clear text.

Why is it API incompatible ?

The removal of the SslFilter.DISABLE_ENCRYPTION_ONCE attribute make it impossible for application that leverage the startTLS command to work, without some code change.

Migration

This is pretty straightforward :

  • Create a filter that bypasses the message that should not be encrypted, or encapsulate it into an inswtance that implements the DisableEncryptWriteRequest interface

and that’s it !