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; } }
限定符和类型 | 类和说明 |
---|---|
static class |
SslFilter.SslFilterMessage
A message that is sent from
SslFilter when the connection became
secure or is not secure anymore. |
IoFilter.NextFilter
限定符和类型 | 字段和说明 |
---|---|
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 ). |
构造器和说明 |
---|
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 . |
限定符和类型 | 方法和说明 |
---|---|
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(boolean) method invocation. |
void |
filterWrite(IoFilter.NextFilter nextFilter,
IoSession session,
WriteRequest writeRequest)
Filters
IoSession.write(Object) method invocation. |
java.lang.String[] |
getEnabledCipherSuites() |
java.lang.String[] |
getEnabledProtocols() |
javax.net.ssl.SSLSession |
getSslSession(IoSession session)
Returns the underlying
SSLSession for the specified session. |
void |
initiateHandshake(IoSession session)
Initiate the SSL handshake.
|
boolean |
isNeedClientAuth() |
boolean |
isSslStarted(IoSession session) |
boolean |
isUseClientMode() |
boolean |
isWantClientAuth() |
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)
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
|
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, inputClosed, 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.sslContext
- The SSLContext to usepublic SslFilter(javax.net.ssl.SSLContext sslContext, boolean autoStart)
SSLContext
.
If the autostart flag is set to true, the
handshake will start immediately.sslContext
- The SSLContext to useautoStart
- The flag used to tell the filter to start the handshake immediatelypublic javax.net.ssl.SSLSession getSslSession(IoSession session)
SSLSession
for the specified session.session
- The current sessionSSLSession
is initialized yet.public boolean startSsl(IoSession session) throws javax.net.ssl.SSLException
session
- The session that will be switched to SSL modejavax.net.ssl.SSLException
- if failed to start the SSL sessionpublic boolean isSslStarted(IoSession session)
session
- the session we want to checkpublic WriteFuture stopSsl(IoSession session) throws javax.net.ssl.SSLException
session
- the IoSession
to initiate TLS closurejavax.net.ssl.SSLException
- if failed to initiate TLS closurepublic boolean isUseClientMode()
public void setUseClientMode(boolean clientMode)
clientMode
- true when we are in client mode, false when in server modepublic boolean isNeedClientAuth()
public void setNeedClientAuth(boolean needClientAuth)
needClientAuth
- A flag set when we need to authenticate the clientpublic boolean isWantClientAuth()
public void setWantClientAuth(boolean wantClientAuth)
wantClientAuth
- A flag set when we want to check the client authenticationpublic java.lang.String[] getEnabledCipherSuites()
SSLEngine
is initialized. null means 'use 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. null means 'use 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
onPreAdd
在接口中 IoFilter
onPreAdd
在类中 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
在接口中 IoFilter
onPostAdd
在类中 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
在接口中 IoFilter
onPreRemove
在类中 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
在接口中 IoFilter
sessionClosed
在类中 IoFilterAdapter
nextFilter
- the IoFilter.NextFilter
for this filter. You can reuse this
object until this filter is removed from the chain.session
- The IoSession
which has received this eventjavax.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
在接口中 IoFilter
messageReceived
在类中 IoFilterAdapter
nextFilter
- the IoFilter.NextFilter
for this filter. You can reuse this
object until this filter is removed from the chain.session
- The IoSession
which has received this eventmessage
- The received messagejavax.net.ssl.SSLException
public void messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
IoFilterAdapter
IoHandler.messageSent(IoSession,Object)
event.messageSent
在接口中 IoFilter
messageSent
在类中 IoFilterAdapter
nextFilter
- the IoFilter.NextFilter
for this filter. You can reuse this
object until this filter is removed from the chain.session
- The IoSession
which has received this eventwriteRequest
- The WriteRequest
that contains the sent messagepublic void exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, java.lang.Throwable cause) throws java.lang.Exception
IoFilterAdapter
IoHandler.exceptionCaught(IoSession,Throwable)
event.exceptionCaught
在接口中 IoFilter
exceptionCaught
在类中 IoFilterAdapter
nextFilter
- the IoFilter.NextFilter
for this filter. You can reuse this
object until this filter is removed from the chain.session
- The IoSession
which has received this eventcause
- The exception that cause this event to be receivedjava.lang.Exception
- If an error occurred while processing the eventpublic void filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws javax.net.ssl.SSLException
IoFilterAdapter
IoSession.write(Object)
method invocation.filterWrite
在接口中 IoFilter
filterWrite
在类中 IoFilterAdapter
nextFilter
- the IoFilter.NextFilter
for this filter. You can reuse this
object until this filter is removed from the chain.session
- The IoSession
which has to process this invocationwriteRequest
- The WriteRequest
to processjavax.net.ssl.SSLException
public void filterClose(IoFilter.NextFilter nextFilter, IoSession session) throws javax.net.ssl.SSLException
IoFilterAdapter
IoSession.close(boolean)
method invocation.filterClose
在接口中 IoFilter
filterClose
在类中 IoFilterAdapter
nextFilter
- the IoFilter.NextFilter
for this filter. You can reuse this
object until this filter is removed from the chain.session
- The IoSession
which has to process this method
invocationjavax.net.ssl.SSLException
public void initiateHandshake(IoSession session) throws javax.net.ssl.SSLException
session
- The session for which the SSL handshake should be donejavax.net.ssl.SSLException
- If the handshake failed