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;
}
}
getEnabledCipherSuites
public String[] getEnabledCipherSuites()
Returns the list of cipher suites to be enabled when SSLEngine
is initialized.
- null means 'use
SSLEngine
's default.'
getEnabledProtocols
public String[] getEnabledProtocols()
Returns the list of protocols to be enabled when SSLEngine
is initialized.
- null means 'use
SSLEngine
's default.'
getSSLSession
public SSLSession getSSLSession(IoSession session)
Returns the underlying SSLSession
for the specified session.
- null if no
SSLSession
is initialized yet.
isNeedClientAuth
public boolean isNeedClientAuth()
Returns true if the engine will require client authentication.
This option is only useful to engines in the server mode.
isSSLStarted
public boolean isSSLStarted(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.
isUseClientMode
public boolean isUseClientMode()
Returns true if the engine is set to use client mode
when handshaking.
isWantClientAuth
public boolean isWantClientAuth()
Returns true if the engine will request client authentication.
This option is only useful to engines in the server mode.
setEnabledCipherSuites
public void setEnabledCipherSuites(String[] cipherSuites)
Sets the list of cipher suites to be enabled when SSLEngine
is initialized.
cipherSuites
- null means 'use SSLEngine
's default.'
setEnabledProtocols
public void setEnabledProtocols(String[] protocols)
Sets the list of protocols to be enabled when SSLEngine
is initialized.
protocols
- null means 'use SSLEngine
's default.'
setNeedClientAuth
public void setNeedClientAuth(boolean needClientAuth)
Configures the engine to require client authentication.
This option is only useful for engines in the server mode.
setUseClientMode
public void setUseClientMode(boolean clientMode)
Configures the engine to use client (or server) mode when handshaking.
setWantClientAuth
public void setWantClientAuth(boolean wantClientAuth)
Configures the engine to request client authentication.
This option is only useful for engines in the server mode.
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.
- true if the SSL session has been started, false if already started.
stopSSL
public WriteFuture stopSSL(IoSession session)
throws SSLException
Stops the SSL session by sending TLS close_notify message to
initiate TLS closure.
session
- the IoSession
to initiate TLS closure