Package org.apache.mina.filter
Class SSLFilter
java.lang.Object
org.apache.mina.common.IoFilterAdapter
org.apache.mina.filter.SSLFilter
- All Implemented Interfaces:
org.apache.mina.common.IoFilter
public class SSLFilter
extends org.apache.mina.common.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
Nested ClassesModifier and TypeClassDescriptionstatic class
A message that is sent fromSSLFilter
when the connection became secure or is not secure anymore.Nested classes/interfaces inherited from interface org.apache.mina.common.IoFilter
org.apache.mina.common.IoFilter.NextFilter, org.apache.mina.common.IoFilter.WriteRequest
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
A session attribute key that makes next one write request bypass this filter (not encrypting the data).static final SSLFilter.SSLFilterMessage
A special message object which is emitted with aIoHandler.messageReceived(IoSession, Object)
event when the session is secured and itsUSE_NOTIFICATION
attribute is set.static final SSLFilter.SSLFilterMessage
A special message object which is emitted with aIoHandler.messageReceived(IoSession, Object)
event when the session is not secure anymore and itsUSE_NOTIFICATION
attribute is set.static final String
A session attribute key that stores underlyingSSLSession
for each session.static final String
A session attribute key that makes this filter to emit aIoHandler.messageReceived(IoSession, Object)
event with a special message (SESSION_SECURED
orSESSION_UNSECURED
). -
Constructor Summary
ConstructorsConstructorDescriptionSSLFilter
(SSLContext sslContext) Creates a new SSL filter using the specifiedSSLContext
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
filterClose
(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session) void
filterWrite
(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, org.apache.mina.common.IoFilter.WriteRequest writeRequest) String[]
Returns the list of cipher suites to be enabled whenSSLEngine
is initialized.String[]
Returns the list of protocols to be enabled whenSSLEngine
is initialized.getSSLSession
(org.apache.mina.common.IoSession session) Returns the underlyingSSLSession
for the specified session.boolean
Returns true if the engine will require client authentication.boolean
isSSLStarted
(org.apache.mina.common.IoSession session) Returns true if and only if the specified session is encrypted/decrypted over SSL/TLS currently.boolean
Returns true if the engine is set to use client mode when handshaking.boolean
Returns true if the engine will request client authentication.void
messageReceived
(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message) void
messageSent
(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message) void
onPostAdd
(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) void
onPreAdd
(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) void
onPreRemove
(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) void
sessionClosed
(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session) void
setEnabledCipherSuites
(String[] cipherSuites) Sets the list of cipher suites to be enabled whenSSLEngine
is initialized.void
setEnabledProtocols
(String[] protocols) Sets the list of protocols to be enabled whenSSLEngine
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
(org.apache.mina.common.IoSession session) (Re)starts SSL session for the specified session if not started yet.org.apache.mina.common.WriteFuture
stopSSL
(org.apache.mina.common.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, init, onPostRemove, sessionCreated, sessionIdle, sessionOpened
-
Field Details
-
SSL_SESSION
A session attribute key that stores underlyingSSLSession
for each session. -
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 asIoSession.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
A session attribute key that makes this filter to emit aIoHandler.messageReceived(IoSession, Object)
event with a special message (SESSION_SECURED
orSESSION_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. -
SESSION_SECURED
A special message object which is emitted with aIoHandler.messageReceived(IoSession, Object)
event when the session is secured and itsUSE_NOTIFICATION
attribute is set. -
SESSION_UNSECURED
A special message object which is emitted with aIoHandler.messageReceived(IoSession, Object)
event when the session is not secure anymore and itsUSE_NOTIFICATION
attribute is set.
-
-
Constructor Details
-
SSLFilter
Creates a new SSL filter using the specifiedSSLContext
.
-
-
Method Details
-
getSSLSession
Returns the underlyingSSLSession
for the specified session.- Returns:
- null if no
SSLSession
is initialized yet.
-
startSSL
(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(org.apache.mina.common.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. -
stopSSL
public org.apache.mina.common.WriteFuture stopSSL(org.apache.mina.common.IoSession session) throws SSLException Stops the SSL session by sending TLS close_notify message to initiate TLS closure.- Parameters:
session
- theIoSession
to initiate TLS closure- Throws:
SSLException
- if failed to initiate TLS closureIllegalArgumentException
- 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
Returns the list of cipher suites to be enabled whenSSLEngine
is initialized.- Returns:
- null means 'use
SSLEngine
's default.'
-
setEnabledCipherSuites
Sets the list of cipher suites to be enabled whenSSLEngine
is initialized.- Parameters:
cipherSuites
- null means 'useSSLEngine
's default.'
-
getEnabledProtocols
Returns the list of protocols to be enabled whenSSLEngine
is initialized.- Returns:
- null means 'use
SSLEngine
's default.'
-
setEnabledProtocols
Sets the list of protocols to be enabled whenSSLEngine
is initialized.- Parameters:
protocols
- null means 'useSSLEngine
's default.'
-
onPreAdd
public void onPreAdd(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) throws SSLException - Specified by:
onPreAdd
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
onPreAdd
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-
onPostAdd
public void onPostAdd(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) throws SSLException - Specified by:
onPostAdd
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
onPostAdd
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-
onPreRemove
public void onPreRemove(org.apache.mina.common.IoFilterChain parent, String name, org.apache.mina.common.IoFilter.NextFilter nextFilter) throws SSLException - Specified by:
onPreRemove
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
onPreRemove
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-
sessionClosed
public void sessionClosed(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session) throws SSLException - Specified by:
sessionClosed
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
sessionClosed
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-
messageReceived
public void messageReceived(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message) throws SSLException - Specified by:
messageReceived
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
messageReceived
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-
messageSent
public void messageSent(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, Object message) - Specified by:
messageSent
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
messageSent
in classorg.apache.mina.common.IoFilterAdapter
-
filterWrite
public void filterWrite(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session, org.apache.mina.common.IoFilter.WriteRequest writeRequest) throws SSLException - Specified by:
filterWrite
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
filterWrite
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-
filterClose
public void filterClose(org.apache.mina.common.IoFilter.NextFilter nextFilter, org.apache.mina.common.IoSession session) throws SSLException - Specified by:
filterClose
in interfaceorg.apache.mina.common.IoFilter
- Overrides:
filterClose
in classorg.apache.mina.common.IoFilterAdapter
- Throws:
SSLException
-