|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectorg.apache.mina.common.IoFilterAdapter
org.apache.mina.filter.SSLFilter
public class SSLFilter
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.
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 | |
|---|---|
static class |
SSLFilter.SSLFilterMessage
A message that is sent from SSLFilter when the connection became
secure or is not secure anymore. |
| Nested classes/interfaces inherited from interface org.apache.mina.common.IoFilter |
|---|
IoFilter.NextFilter, IoFilter.WriteRequest |
| Field Summary | |
|---|---|
static String |
DISABLE_ENCRYPTION_ONCE
A session attribute key that makes next one write request bypass this filter (not encrypting the data). |
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 String |
SSL_SESSION
A session attribute key that stores underlying SSLSession
for each session. |
static String |
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 Summary | |
|---|---|
SSLFilter(SSLContext sslContext)
Creates a new SSL filter using the specified SSLContext. |
|
| Method Summary | |
|---|---|
void |
filterClose(IoFilter.NextFilter nextFilter,
IoSession session)
Filters IoSession.close() method invocation. |
void |
filterWrite(IoFilter.NextFilter nextFilter,
IoSession session,
IoFilter.WriteRequest writeRequest)
Filters IoSession.write(Object) method invocation. |
String[] |
getEnabledCipherSuites()
Returns the list of cipher suites to be enabled when SSLEngine
is initialized. |
String[] |
getEnabledProtocols()
Returns the list of protocols to be enabled when SSLEngine
is initialized. |
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,
Object message)
Filters IoHandler.messageReceived(IoSession,Object)
event. |
void |
messageSent(IoFilter.NextFilter nextFilter,
IoSession session,
Object message)
Filters IoHandler.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)
Invoked before this filter is added to the specified parent. |
void |
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)
Filters IoHandler.sessionClosed(IoSession) event. |
void |
setEnabledCipherSuites(String[] cipherSuites)
Sets the list of cipher suites to be enabled when SSLEngine
is initialized. |
void |
setEnabledProtocols(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. |
| Methods inherited from class org.apache.mina.common.IoFilterAdapter |
|---|
destroy, exceptionCaught, init, onPostRemove, sessionCreated, sessionIdle, sessionOpened |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final String SSL_SESSION
SSLSession
for each session.
public static final String 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 String 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 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.
| Constructor Detail |
|---|
public SSLFilter(SSLContext sslContext)
SSLContext.
| Method Detail |
|---|
public SSLSession getSSLSession(IoSession session)
SSLSession for the specified session.
SSLSession is initialized yet.
public boolean startSSL(IoSession session)
throws SSLException
SSLException - if failed to start the SSL sessionpublic boolean isSSLStarted(IoSession session)
public WriteFuture stopSSL(IoSession session)
throws SSLException
session - the IoSession to initiate TLS closure
SSLException - if failed to initiate TLS closure
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 String[] getEnabledCipherSuites()
SSLEngine
is initialized.
SSLEngine's default.'public void setEnabledCipherSuites(String[] cipherSuites)
SSLEngine
is initialized.
cipherSuites - null means 'use SSLEngine's default.'public String[] getEnabledProtocols()
SSLEngine
is initialized.
SSLEngine's default.'public void setEnabledProtocols(String[] protocols)
SSLEngine
is initialized.
protocols - null means 'use SSLEngine's default.'
public void onPreAdd(IoFilterChain parent,
String name,
IoFilter.NextFilter nextFilter)
throws SSLException
IoFilterIoFilter.init() is invoked.
onPreAdd in interface IoFilteronPreAdd in class IoFilterAdapterparent - 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.
SSLException
public void onPostAdd(IoFilterChain parent,
String name,
IoFilter.NextFilter nextFilter)
throws SSLException
IoFilterIoFilter.init() is invoked.
onPostAdd in interface IoFilteronPostAdd in class IoFilterAdapterparent - 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.
SSLException
public void onPreRemove(IoFilterChain parent,
String name,
IoFilter.NextFilter nextFilter)
throws SSLException
IoFilterIoFilter.destroy() is invoked.
onPreRemove in interface IoFilteronPreRemove in class IoFilterAdapterparent - 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.
SSLException
public void sessionClosed(IoFilter.NextFilter nextFilter,
IoSession session)
throws SSLException
IoFilterIoHandler.sessionClosed(IoSession) event.
sessionClosed in interface IoFiltersessionClosed in class IoFilterAdapterSSLException
public void messageReceived(IoFilter.NextFilter nextFilter,
IoSession session,
Object message)
throws SSLException
IoFilterIoHandler.messageReceived(IoSession,Object)
event.
messageReceived in interface IoFiltermessageReceived in class IoFilterAdapterSSLException
public void messageSent(IoFilter.NextFilter nextFilter,
IoSession session,
Object message)
IoFilterIoHandler.messageSent(IoSession,Object)
event.
messageSent in interface IoFiltermessageSent in class IoFilterAdapter
public void filterWrite(IoFilter.NextFilter nextFilter,
IoSession session,
IoFilter.WriteRequest writeRequest)
throws SSLException
IoFilterIoSession.write(Object) method invocation.
filterWrite in interface IoFilterfilterWrite in class IoFilterAdapterSSLException
public void filterClose(IoFilter.NextFilter nextFilter,
IoSession session)
throws SSLException
IoFilterIoSession.close() method invocation.
filterClose in interface IoFilterfilterClose in class IoFilterAdapterSSLException
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||