Package org.apache.mina.filter.ssl
Class 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 callstartSsl(IoSession)
manually unless you are implementing StartTLS (see below). If you don't want the handshake procedure to start immediately, please specifyfalse
asautoStart
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 temporarily. // 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; } }
- Author:
- Apache MINA Project
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SslFilter.SslFilterMessage
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.core.filterchain.IoFilter
IoFilter.NextFilter
-
-
Field Summary
Fields Modifier and Type Field Description static boolean
CLIENT_HANDSHAKE
A flag used to determinate if the handshake should wait for the client to initiate the handshakestatic AttributeKey
DISABLE_ENCRYPTION_ONCE
A session attribute key that makes next one write request bypass this filter (not encrypting the data).static AttributeKey
PEER_ADDRESS
A session attribute key that should be set to anInetSocketAddress
.static SslFilter.SslFilterMessage
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.static SslFilter.SslFilterMessage
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.static AttributeKey
SSL_SESSION
A session attribute key that stores underlyingSSLSession
for each session.static boolean
START_HANDSHAKE
A flag used to determinate if the handshake should start immediatelystatic AttributeKey
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
).
-
Constructor Summary
Constructors Constructor Description SslFilter(SSLContext sslContext)
Creates a new SSL filter using the specifiedSSLContext
.SslFilter(SSLContext sslContext, boolean autoStart)
Creates a new SSL filter using the specifiedSSLContext
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause)
FiltersIoHandler.exceptionCaught(IoSession,Throwable)
event.void
filterClose(IoFilter.NextFilter nextFilter, IoSession session)
FiltersIoSession.closeNow()
or aIoSession.closeOnFlush()
method invocations.void
filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
FiltersIoSession.write(Object)
method invocation.String[]
getEnabledCipherSuites()
String[]
getEnabledProtocols()
SSLSession
getSslSession(IoSession session)
Returns the underlyingSSLSession
for the specified session.void
initiateHandshake(IoSession session)
Initiate the SSL handshake.boolean
isNeedClientAuth()
boolean
isSecured(IoSession session)
boolean
isSslStarted(IoSession session)
boolean
isUseClientMode()
boolean
isWantClientAuth()
void
messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message)
FiltersIoHandler.messageReceived(IoSession,Object)
event.void
messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
FiltersIoHandler.messageSent(IoSession,Object)
event.void
onPostAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
Invoked after this filter is added to the specified parent.void
onPreAdd(IoFilterChain parent, 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 Attributesvoid
onPreRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
Invoked before this filter is removed from the specified parent.void
sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)
FiltersIoHandler.sessionClosed(IoSession)
event.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(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
-
-
-
-
Field Detail
-
SSL_SESSION
public static final AttributeKey SSL_SESSION
A session attribute key that stores underlyingSSLSession
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 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
public static final AttributeKey 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.
-
PEER_ADDRESS
public static final AttributeKey PEER_ADDRESS
A session attribute key that should be set to anInetSocketAddress
. Setting this attribute causesSSLContext.createSSLEngine(String, int)
to be called passing the hostname and port of theInetSocketAddress
to get anSSLEngine
instance. If not setSSLContext.createSSLEngine()
will be called.
Using this featureSSLSession
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 aIoHandler.messageReceived(IoSession, Object)
event when the session is secured and itsUSE_NOTIFICATION
attribute is set.
-
SESSION_UNSECURED
public static final SslFilter.SslFilterMessage 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.
-
START_HANDSHAKE
public static final boolean START_HANDSHAKE
A flag used to determinate if the handshake should start immediately- See Also:
- Constant Field Values
-
CLIENT_HANDSHAKE
public static final boolean CLIENT_HANDSHAKE
A flag used to determinate if the handshake should wait for the client to initiate the handshake- See Also:
- Constant Field Values
-
-
Constructor Detail
-
SslFilter
public SslFilter(SSLContext sslContext)
Creates a new SSL filter using the specifiedSSLContext
. The handshake will start immediately after the filter has been added to the chain.- Parameters:
sslContext
- The SSLContext to use
-
SslFilter
public SslFilter(SSLContext sslContext, boolean autoStart)
Creates a new SSL filter using the specifiedSSLContext
. If the autostart flag is set to true, the handshake will start immediately after the filter has been added to the chain.- Parameters:
sslContext
- The SSLContext to useautoStart
- The flag used to tell the filter to start the handshake immediately
-
-
Method Detail
-
getSslSession
public SSLSession getSslSession(IoSession session)
Returns the underlyingSSLSession
for the specified session.- Parameters:
session
- The current session- Returns:
- null if no
SSLSession
is initialized yet.
-
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.- Parameters:
session
- The session that will be switched to SSL mode- 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(IoSession session)
- Parameters:
session
- the session we want to check- 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.
-
isSecured
public boolean isSecured(IoSession session)
- Parameters:
session
- the session we want to check- Returns:
- true if and only if the conditions for
isSslStarted(IoSession)
are met, and the handhake has completed.
-
stopSsl
public WriteFuture stopSsl(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- Returns:
- The Future for the initiated closure
- Throws:
SSLException
- if failed to initiate TLS closure
-
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.- Parameters:
clientMode
- true when we are in client mode, false when in server mode
-
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.- Parameters:
needClientAuth
- A flag set when we need to authenticate the client
-
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.- Parameters:
wantClientAuth
- A flag set when we want to check the client authentication
-
getEnabledCipherSuites
public String[] getEnabledCipherSuites()
-
setEnabledCipherSuites
public void setEnabledCipherSuites(String[] cipherSuites)
Sets the list of cipher suites to be enabled whenSSLEngine
is initialized.- Parameters:
cipherSuites
- null means 'useSSLEngine
's default.'
-
getEnabledProtocols
public String[] getEnabledProtocols()
-
setEnabledProtocols
public void setEnabledProtocols(String[] protocols)
Sets the list of protocols to be enabled whenSSLEngine
is initialized.- Parameters:
protocols
- null means 'useSSLEngine
's default.'
-
onPreAdd
public void onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter) throws 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 interfaceIoFilter
- Overrides:
onPreAdd
in classIoFilterAdapter
- Parameters:
parent
- the parent who called this methodname
- the name assigned to this filternextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.- Throws:
SSLException
-
onPostAdd
public void onPostAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter) throws 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 beforeIoFilter.init()
is invoked.- Specified by:
onPostAdd
in interfaceIoFilter
- Overrides:
onPostAdd
in classIoFilterAdapter
- Parameters:
parent
- the parent who called this methodname
- the name assigned to this filternextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.- Throws:
SSLException
-
onPreRemove
public void onPreRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter) throws 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 beforeIoFilter.destroy()
is invoked.- Specified by:
onPreRemove
in interfaceIoFilter
- Overrides:
onPreRemove
in classIoFilterAdapter
- Parameters:
parent
- the parent who called this methodname
- the name assigned to this filternextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.- Throws:
SSLException
-
sessionClosed
public void sessionClosed(IoFilter.NextFilter nextFilter, IoSession session) throws SSLException
Description copied from class:IoFilterAdapter
FiltersIoHandler.sessionClosed(IoSession)
event.- Specified by:
sessionClosed
in interfaceIoFilter
- Overrides:
sessionClosed
in classIoFilterAdapter
- Parameters:
nextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.session
- TheIoSession
which has received this event- Throws:
SSLException
-
messageReceived
public void messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message) throws SSLException
Description copied from class:IoFilterAdapter
FiltersIoHandler.messageReceived(IoSession,Object)
event.- Specified by:
messageReceived
in interfaceIoFilter
- Overrides:
messageReceived
in classIoFilterAdapter
- Parameters:
nextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.session
- TheIoSession
which has received this eventmessage
- The received message- Throws:
SSLException
-
messageSent
public void messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
Description copied from class:IoFilterAdapter
FiltersIoHandler.messageSent(IoSession,Object)
event.- Specified by:
messageSent
in interfaceIoFilter
- Overrides:
messageSent
in classIoFilterAdapter
- Parameters:
nextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.session
- TheIoSession
which has received this eventwriteRequest
- TheWriteRequest
that contains the sent message
-
exceptionCaught
public void exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause) throws Exception
Description copied from class:IoFilterAdapter
FiltersIoHandler.exceptionCaught(IoSession,Throwable)
event.- Specified by:
exceptionCaught
in interfaceIoFilter
- Overrides:
exceptionCaught
in classIoFilterAdapter
- Parameters:
nextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.session
- TheIoSession
which has received this eventcause
- The exception that cause this event to be received- Throws:
Exception
- If an error occurred while processing the event
-
filterWrite
public void filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws SSLException
Description copied from class:IoFilterAdapter
FiltersIoSession.write(Object)
method invocation.- Specified by:
filterWrite
in interfaceIoFilter
- Overrides:
filterWrite
in classIoFilterAdapter
- Parameters:
nextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.session
- TheIoSession
which has to process this invocationwriteRequest
- TheWriteRequest
to process- Throws:
SSLException
-
filterClose
public void filterClose(IoFilter.NextFilter nextFilter, IoSession session) throws SSLException
Description copied from class:IoFilterAdapter
FiltersIoSession.closeNow()
or aIoSession.closeOnFlush()
method invocations.- Specified by:
filterClose
in interfaceIoFilter
- Overrides:
filterClose
in classIoFilterAdapter
- Parameters:
nextFilter
- theIoFilter.NextFilter
for this filter. You can reuse this object until this filter is removed from the chain.session
- TheIoSession
which has to process this method invocation- Throws:
SSLException
-
initiateHandshake
public void initiateHandshake(IoSession session) throws SSLException
Initiate the SSL handshake. This can be invoked if you have set the 'autoStart' to false when creating the SslFilter instance.- Parameters:
session
- The session for which the SSL handshake should be done- Throws:
SSLException
- If the handshake failed
-
-