public class SslFilter extends IoFilterAdapter
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.
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; } }
Modifier and Type | Class and Description |
---|---|
static class |
SslFilter.SslFilterMessage
A message that is sent from
SslFilter when the connection became
secure or is not secure anymore. |
IoFilter.NextFilter
Modifier and Type | Field and Description |
---|---|
static 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 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. |
static AttributeKey |
SSL_SESSION
A session attribute key that stores underlying
SSLSession
for each session. |
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 ). |
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 . |
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. |
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 |
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)
Invoked before this filter is added to the specified parent.
|
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.
|
destroy, init, onPostRemove, sessionCreated, sessionIdle, sessionOpened, toString
public static final AttributeKey SSL_SESSION
SSLSession
for each session.public static final AttributeKey DISABLE_ENCRYPTION_ONCE
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.public static final AttributeKey USE_NOTIFICATION
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.public static final AttributeKey PEER_ADDRESS
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.SSLSession
objects may be cached and reused
when in client mode.SSLContext.createSSLEngine(String, int)
public static final SslFilter.SslFilterMessage SESSION_SECURED
IoHandler.messageReceived(IoSession, Object)
event when the session is secured and its USE_NOTIFICATION
attribute is set.public static final SslFilter.SslFilterMessage SESSION_UNSECURED
IoHandler.messageReceived(IoSession, Object)
event when the session is not secure anymore and its USE_NOTIFICATION
attribute is set.public SslFilter(javax.net.ssl.SSLContext sslContext)
SSLContext
.
The handshake will start immediately.public SslFilter(javax.net.ssl.SSLContext sslContext, boolean autoStart)
SSLContext
.
If the autostart
flag is set to true
, the
handshake will start immediately.public javax.net.ssl.SSLSession getSslSession(IoSession session)
SSLSession
for the specified session.SSLSession
is initialized yet.public boolean startSsl(IoSession session) throws javax.net.ssl.SSLException
javax.net.ssl.SSLException
- if failed to start the SSL sessionpublic boolean isSslStarted(IoSession session)
public WriteFuture stopSsl(IoSession session) throws javax.net.ssl.SSLException
session
- the IoSession
to initiate TLS closurejavax.net.ssl.SSLException
- if failed to initiate TLS closurejava.lang.IllegalArgumentException
- if this filter is not managing the specified sessionpublic boolean isUseClientMode()
public void setUseClientMode(boolean clientMode)
public boolean isNeedClientAuth()
public void setNeedClientAuth(boolean needClientAuth)
public boolean isWantClientAuth()
public void setWantClientAuth(boolean wantClientAuth)
public java.lang.String[] getEnabledCipherSuites()
SSLEngine
is initialized.SSLEngine
's default.'public void setEnabledCipherSuites(java.lang.String[] cipherSuites)
SSLEngine
is initialized.cipherSuites
- null means 'use SSLEngine
's default.'public java.lang.String[] getEnabledProtocols()
SSLEngine
is initialized.SSLEngine
's default.'public void setEnabledProtocols(java.lang.String[] protocols)
SSLEngine
is initialized.protocols
- null means 'use SSLEngine
's default.'public void onPreAdd(IoFilterChain parent, java.lang.String name, IoFilter.NextFilter nextFilter) throws javax.net.ssl.SSLException
IoFilterAdapter
IoFilter.init()
is invoked.onPreAdd
in interface IoFilter
onPreAdd
in class IoFilterAdapter
parent
- the parent who called this methodname
- the name assigned to this filternextFilter
- the IoFilter.NextFilter
for this filter. You can reuse
this object until this filter is removed from the chain.javax.net.ssl.SSLException
public void onPostAdd(IoFilterChain parent, java.lang.String name, IoFilter.NextFilter nextFilter) throws javax.net.ssl.SSLException
IoFilterAdapter
IoFilter.init()
is invoked.onPostAdd
in interface IoFilter
onPostAdd
in class IoFilterAdapter
parent
- the parent who called this methodname
- the name assigned to this filternextFilter
- the IoFilter.NextFilter
for this filter. You can reuse
this object until this filter is removed from the chain.javax.net.ssl.SSLException
public void onPreRemove(IoFilterChain parent, java.lang.String name, IoFilter.NextFilter nextFilter) throws javax.net.ssl.SSLException
IoFilterAdapter
IoFilter.destroy()
is invoked.onPreRemove
in interface IoFilter
onPreRemove
in class IoFilterAdapter
parent
- the parent who called this methodname
- the name assigned to this filternextFilter
- the IoFilter.NextFilter
for this filter. You can reuse
this object until this filter is removed from the chain.javax.net.ssl.SSLException
public void sessionClosed(IoFilter.NextFilter nextFilter, IoSession session) throws javax.net.ssl.SSLException
IoFilterAdapter
IoHandler.sessionClosed(IoSession)
event.sessionClosed
in interface IoFilter
sessionClosed
in class IoFilterAdapter
javax.net.ssl.SSLException
public void messageReceived(IoFilter.NextFilter nextFilter, IoSession session, java.lang.Object message) throws javax.net.ssl.SSLException
IoFilterAdapter
IoHandler.messageReceived(IoSession,Object)
event.messageReceived
in interface IoFilter
messageReceived
in class IoFilterAdapter
javax.net.ssl.SSLException
public void messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
IoFilterAdapter
IoHandler.messageSent(IoSession,Object)
event.messageSent
in interface IoFilter
messageSent
in class IoFilterAdapter
public void exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, java.lang.Throwable cause) throws java.lang.Exception
IoFilterAdapter
IoHandler.exceptionCaught(IoSession,Throwable)
event.exceptionCaught
in interface IoFilter
exceptionCaught
in class IoFilterAdapter
java.lang.Exception
public void filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws javax.net.ssl.SSLException
IoFilterAdapter
IoSession.write(Object)
method invocation.filterWrite
in interface IoFilter
filterWrite
in class IoFilterAdapter
javax.net.ssl.SSLException
public void filterClose(IoFilter.NextFilter nextFilter, IoSession session) throws javax.net.ssl.SSLException
IoFilterAdapter
IoSession.close()
method invocation.filterClose
in interface IoFilter
filterClose
in class IoFilterAdapter
javax.net.ssl.SSLException
Copyright © 2004-2019 Apache MINA Project. All Rights Reserved.