org.jboss.netty.handler.ssl

类 SslHandler

java.lang.Object

org.jboss.netty.channel.SimpleChannelUpstreamHandler

org.jboss.netty.handler.codec.frame.FrameDecoder

org.jboss.netty.handler.ssl.SslHandler

所有已实现的接口:

ChannelDownstreamHandler, ChannelHandler, ChannelUpstreamHandler, LifeCycleAwareChannelHandler

public class SslHandler
extends FrameDecoder
implements ChannelDownstreamHandler

Adds SSL · TLS and StartTLS support to a Channel. Please refer to the "SecureChat" example in the distribution or the web site for the detailed usage.

Beginning the handshake

You must make sure not to write a message while the handshake is in progress unless you are renegotiating. You will be notified by the ChannelFuture which is returned by the handshake() method when the handshake process succeeds or fails.

Handshake

If isIssueHandshake() is false (default) you will need to take care of calling handshake() by your own. In most situations were SslHandler is used in 'client mode' you want to issue a handshake once the connection was established. if setIssueHandshake(boolean) is set to true you don't need to worry about this as the SslHandler will take care of it.

Renegotiation

If enableRenegotiation is true (default) and the initial handshake has been done successfully, you can call handshake() to trigger the renegotiation.

If enableRenegotiation is false, an attempt to trigger renegotiation will result in the connection closure.

Please note that TLS renegotiation had a security issue before. If your runtime environment did not fix it, please make sure to disable TLS renegotiation by calling setEnableRenegotiation(boolean) with false. For more information, please refer to the following documents:

• CVE-2009-3555
• RFC5746
• Phased Approach to Fixing the TLS Renegotiation Issue

Closing the session

To close the SSL session, the close() method should be called to send the close_notify message to the remote peer. One exception is when you close the Channel - SslHandler intercepts the close request and send the close_notify message before the channel closure automatically. Once the SSL session is closed, it is not reusable, and consequently you should create a new SslHandler with a new SSLEngine as explained in the following section.

Restarting the session

To restart the SSL session, you must remove the existing closed SslHandler from the ChannelPipeline, insert a new SslHandler with a new SSLEngine into the pipeline, and start the handshake process as described in the first section.

Implementing StartTLS

StartTLS is the communication pattern that secures the wire in the middle of the plaintext connection. Please note that it is different from SSL · TLS, that secures the wire from the beginning of the connection. Typically, StartTLS is composed of three steps:

1. Client sends a StartTLS request to server.
2. Server sends a StartTLS response to client.
3. Client begins SSL handshake.

If you implement a server, you need to:

1. create a new SslHandler instance with startTls flag set to true,
2. insert the SslHandler to the ChannelPipeline, and
3. write a StartTLS response.

Please note that you must insert SslHandler before sending the StartTLS response. Otherwise the client can send begin SSL handshake before SslHandler is inserted to the ChannelPipeline, causing data corruption.

The client-side implementation is much simpler.

1. Write a StartTLS request,
2. wait for the StartTLS response,
3. create a new SslHandler instance with startTls flag set to false,
4. insert the SslHandler to the ChannelPipeline, and
5. Initiate SSL handshake by calling handshake().

Known issues

Because of a known issue with the current implementation of the SslEngine that comes with Java it may be possible that you see blocked IO-Threads while a full GC is done.

So if you are affected you can workaround this problem by adjust the cache settings like shown below:

     SslContext context = ...;
     context.getServerSessionContext().setSessionCacheSize(someSaneSize);
     context.getServerSessionContext().setSessionTime(someSameTimeout);
 

What values to use here depends on the nature of your application and should be set based on monitoring and debugging of it. For more details see #832 in our issue tracker.

嵌套类概要

从接口继承的嵌套类/接口 org.jboss.netty.channel.ChannelHandler

ChannelHandler.Sharable

字段概要

从类继承的字段 org.jboss.netty.handler.codec.frame.FrameDecoder

cumulation, DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS

构造器概要

构造器

构造器和说明
SslHandler(javax.net.ssl.SSLEngine engine) Creates a new instance.
SslHandler(javax.net.ssl.SSLEngine engine, boolean startTls) Creates a new instance.
SslHandler(javax.net.ssl.SSLEngine engine, SslBufferPool bufferPool) Creates a new instance.
SslHandler(javax.net.ssl.SSLEngine engine, SslBufferPool bufferPool, boolean startTls) Creates a new instance.
SslHandler(javax.net.ssl.SSLEngine engine, SslBufferPool bufferPool, boolean startTls, Timer timer, long handshakeTimeoutInMillis) Creates a new instance.

方法概要

方法

限定符和类型	方法和说明
void	afterRemove(ChannelHandlerContext ctx) Fail all pending writes which we were not able to flush out
void	beforeAdd(ChannelHandlerContext ctx)
void	channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e) Loop over all the pending writes and fail them.
void	channelConnected(ChannelHandlerContext ctx, ChannelStateEvent e) Calls handshake() once the Channel is connected
void	channelDisconnected(ChannelHandlerContext ctx, ChannelStateEvent e) Invoked when a Channel was disconnected from its remote peer.
ChannelFuture	close() Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine.
protected java.lang.Object	decode(ChannelHandlerContext ctx, Channel channel, ChannelBuffer in) Decodes the received packets so far into a frame.
void	exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) Invoked when an exception was raised by an I/O thread or a ChannelHandler.
boolean	getCloseOnSSLException()
static SslBufferPool	getDefaultBufferPool() Returns the default SslBufferPool used when no pool is specified in the constructor.
javax.net.ssl.SSLEngine	getEngine() Returns the SSLEngine which is used by this handler.
long	getHandshakeTimeout() Return the timeout (in ms) after which the ChannelFuture of handshake() will be failed, while a handshake is in progress
ChannelFuture	getSSLEngineInboundCloseFuture() Return the ChannelFuture that will get notified if the inbound of the SSLEngine will get closed.
void	handleDownstream(ChannelHandlerContext context, ChannelEvent evt) Handles the specified downstream event.
ChannelFuture	handshake() Starts an SSL / TLS handshake for the specified channel.
boolean	isEnableRenegotiation() Returns true if and only if TLS renegotiation is enabled.
static boolean	isEncrypted(ChannelBuffer buffer) Returns true if the given ChannelBuffer is encrypted.
boolean	isIssueHandshake() Returns true if the automatic handshake is enabled
void	setCloseOnSSLException(boolean closeOnSslException) If set to true, the Channel will automatically get closed one a SSLException was caught.
void	setEnableRenegotiation(boolean enableRenegotiation) Enables or disables TLS renegotiation.
void	setIssueHandshake(boolean issueHandshake) Enables or disables the automatic handshake once the Channel is connected.

从类继承的方法 org.jboss.netty.handler.codec.frame.FrameDecoder

actualReadableBytes, afterAdd, appendToCumulation, beforeRemove, cleanup, decodeLast, extractFrame, getMaxCumulationBufferCapacity, getMaxCumulationBufferComponents, internalBuffer, isUnfold, messageReceived, newCumulationBuffer, replace, setMaxCumulationBufferCapacity, setMaxCumulationBufferComponents, setUnfold, unfoldAndFireMessageReceived, updateCumulation

从类继承的方法 org.jboss.netty.channel.SimpleChannelUpstreamHandler

channelBound, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete

从类继承的方法 java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造器详细资料

SslHandler

public SslHandler(javax.net.ssl.SSLEngine engine)

Creates a new instance.

参数:

engine - the SSLEngine this handler will use

SslHandler

public SslHandler(javax.net.ssl.SSLEngine engine,
          SslBufferPool bufferPool)

Creates a new instance.

参数:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

SslHandler

public SslHandler(javax.net.ssl.SSLEngine engine,
          boolean startTls)

Creates a new instance.

参数:

engine - the SSLEngine this handler will use

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

SslHandler

public SslHandler(javax.net.ssl.SSLEngine engine,
          SslBufferPool bufferPool,
          boolean startTls)

Creates a new instance.

参数:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

SslHandler

public SslHandler(javax.net.ssl.SSLEngine engine,
          SslBufferPool bufferPool,
          boolean startTls,
          Timer timer,
          long handshakeTimeoutInMillis)

Creates a new instance.

参数:

engine - the SSLEngine this handler will use

bufferPool - the SslBufferPool where this handler will acquire the buffers required by the SSLEngine

startTls - true if the first write request shouldn't be encrypted by the SSLEngine

timer - the Timer which will be used to process the timeout of the handshake(). Be aware that the given Timer will not get stopped automaticly, so it is up to you to cleanup once you not need it anymore

handshakeTimeoutInMillis - the time in milliseconds after whic the handshake() will be failed, and so the future notified

方法详细资料

getDefaultBufferPool

public static SslBufferPool getDefaultBufferPool()

Returns the default SslBufferPool used when no pool is specified in the constructor.

getEngine

public javax.net.ssl.SSLEngine getEngine()

Returns the SSLEngine which is used by this handler.

handshake

public ChannelFuture handshake()

Starts an SSL / TLS handshake for the specified channel.

返回:

a ChannelFuture which is notified when the handshake succeeds or fails.

close

public ChannelFuture close()

Sends an SSL close_notify message to the specified channel and destroys the underlying SSLEngine.

isEnableRenegotiation

public boolean isEnableRenegotiation()

Returns true if and only if TLS renegotiation is enabled.

setEnableRenegotiation

public void setEnableRenegotiation(boolean enableRenegotiation)

Enables or disables TLS renegotiation.

setIssueHandshake

public void setIssueHandshake(boolean issueHandshake)

Enables or disables the automatic handshake once the Channel is connected. The value will only have affect if its set before the Channel is connected.

isIssueHandshake

public boolean isIssueHandshake()

Returns true if the automatic handshake is enabled

getSSLEngineInboundCloseFuture

public ChannelFuture getSSLEngineInboundCloseFuture()

Return the ChannelFuture that will get notified if the inbound of the SSLEngine will get closed. This method will return the same ChannelFuture all the time. For more informations see the apidocs of SSLEngine

getHandshakeTimeout

public long getHandshakeTimeout()

Return the timeout (in ms) after which the ChannelFuture of handshake() will be failed, while a handshake is in progress

setCloseOnSSLException

public void setCloseOnSSLException(boolean closeOnSslException)

If set to true, the Channel will automatically get closed one a SSLException was caught. This is most times what you want, as after this its almost impossible to recover. Anyway the default is false to not break compatibility with older releases. This will be changed to true in the next major release.

getCloseOnSSLException

public boolean getCloseOnSSLException()

handleDownstream

public void handleDownstream(ChannelHandlerContext context,
                    ChannelEvent evt)
                      throws java.lang.Exception

从接口复制的说明: ChannelDownstreamHandler

Handles the specified downstream event.

指定者:

handleDownstream 在接口中 ChannelDownstreamHandler

参数:

context - the context object for this handler

evt - the downstream event to process or intercept

抛出:

java.lang.Exception

channelDisconnected

public void channelDisconnected(ChannelHandlerContext ctx,
                       ChannelStateEvent e)
                         throws java.lang.Exception

从类复制的说明: SimpleChannelUpstreamHandler

Invoked when a Channel was disconnected from its remote peer.

覆盖:

channelDisconnected 在类中 FrameDecoder

抛出:

java.lang.Exception

exceptionCaught

public void exceptionCaught(ChannelHandlerContext ctx,
                   ExceptionEvent e)
                     throws java.lang.Exception

从类复制的说明: SimpleChannelUpstreamHandler

Invoked when an exception was raised by an I/O thread or a ChannelHandler.

覆盖:

exceptionCaught 在类中 FrameDecoder

抛出:

java.lang.Exception

isEncrypted

public static boolean isEncrypted(ChannelBuffer buffer)

Returns true if the given ChannelBuffer is encrypted. Be aware that this method will not increase the readerIndex of the given ChannelBuffer.

参数:

buffer - The ChannelBuffer to read from. Be aware that it must have at least 5 bytes to read, otherwise it will throw an IllegalArgumentException.

返回:

encrypted true if the ChannelBuffer is encrypted, false otherwise.

抛出:

java.lang.IllegalArgumentException - Is thrown if the given ChannelBuffer has not at least 5 bytes to read.

decode

protected java.lang.Object decode(ChannelHandlerContext ctx,
                      Channel channel,
                      ChannelBuffer in)
                           throws java.lang.Exception

从类复制的说明: FrameDecoder

Decodes the received packets so far into a frame. If an sub-class wants to extract a frame out of the buffer it should use the FrameDecoder.extractFrame(ChannelBuffer, int, int) method, to make optimizations easier later.

指定者:

decode 在类中 FrameDecoder

参数:

ctx - the context of this handler

channel - the current channel

in - the cumulative buffer of received packets so far. Note that the buffer might be empty, which means you should not make an assumption that the buffer contains at least one byte in your decoder implementation.

返回:

the decoded frame if a full frame was received and decoded. null if there's not enough data in the buffer to decode a frame.

抛出:

java.lang.Exception

beforeAdd

public void beforeAdd(ChannelHandlerContext ctx)
               throws java.lang.Exception

指定者:

beforeAdd 在接口中 LifeCycleAwareChannelHandler

覆盖:

beforeAdd 在类中 FrameDecoder

抛出:

java.lang.Exception

afterRemove

public void afterRemove(ChannelHandlerContext ctx)
                 throws java.lang.Exception

Fail all pending writes which we were not able to flush out

指定者:

afterRemove 在接口中 LifeCycleAwareChannelHandler

覆盖:

afterRemove 在类中 FrameDecoder

抛出:

java.lang.Exception

channelConnected

public void channelConnected(ChannelHandlerContext ctx,
                    ChannelStateEvent e)
                      throws java.lang.Exception

Calls handshake() once the Channel is connected

覆盖:

channelConnected 在类中 SimpleChannelUpstreamHandler

抛出:

java.lang.Exception

channelClosed

public void channelClosed(ChannelHandlerContext ctx,
                 ChannelStateEvent e)
                   throws java.lang.Exception

Loop over all the pending writes and fail them. See #305 for more details.

覆盖:

channelClosed 在类中 FrameDecoder

抛出:

java.lang.Exception