kipedia.org/wiki/Transport_Layer_Security">SSL · TLS and StartTLS support to a {@link 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 {@linkplain #handshake() handshake} is in progress unless you arerenegotiating. You will be notified by the {@link ChannelFuture} which isreturned by the {@link #handshake()} method when the handshakeprocess succeeds or fails.
Renegotiation
TLS renegotiation has been disabled by default due to a known security issue, CVE-2009-3555. You can re-enable renegotiation by calling {@link #setEnableRenegotiation(boolean)}with {@code true} at your own risk.
If {@link #isEnableRenegotiation() enableRenegotiation} is {@code true} andthe initial handshake has been done successfully, you can call {@link #handshake()} to trigger the renegotiation.
If {@link #isEnableRenegotiation() enableRenegotiation} is {@code false}, an attempt to trigger renegotiation will result in the connection closure.
Closing the session
To close the SSL session, the {@link #close()} method should becalled to send the {@code close_notify} message to the remote peer. Oneexception is when you close the {@link Channel} - {@link SslHandler}intercepts the close request and send the {@code close_notify} messagebefore the channel closure automatically. Once the SSL session is closed, it is not reusable, and consequently you should create a new {@link SslHandler} with a new {@link SSLEngine} as explained in thefollowing section.
Restarting the session
To restart the SSL session, you must remove the existing closed {@link SslHandler} from the {@link ChannelPipeline}, insert a new {@link SslHandler} with a new {@link 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:
- Client sends a StartTLS request to server.
- Server sends a StartTLS response to client.
- Client begins SSL handshake.
If you implement a server, you need to:
- create a new {@link SslHandler} instance with {@code startTls} flag setto {@code true},
- insert the {@link SslHandler} to the {@link ChannelPipeline}, and
- write a StartTLS response.
Please note that you must insert {@link SslHandler}
before sendingthe StartTLS response. Otherwise the client can send begin SSL handshake before {@link SslHandler} is inserted to the {@link ChannelPipeline}, causing data corruption.
The client-side implementation is much simpler.
- Write a StartTLS request,
- wait for the StartTLS response,
- create a new {@link SslHandler} instance with {@code startTls} flag setto {@code false},
- insert the {@link SslHandler} to the {@link ChannelPipeline}, and
- Initiate SSL handshake by calling {@link SslHandler#handshake()}.
@author
The Netty Project
@author
Trustin Lee
@version $Rev: 2369 $, $Date: 2010-10-19 13:05:28 +0900 (Tue, 19 Oct 2010) $
@apiviz.landmark
@apiviz.uses org.jboss.netty.handler.ssl.SslBufferPool