From 4021ef46929a62148b148a0ab97292713f18c77f Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Thu, 16 Jul 2009 07:17:37 +0000 Subject: [PATCH] Improved SslHandler Javadoc --- .../jboss/netty/handler/ssl/SslHandler.java | 36 +++++++++++++++++-- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/src/main/java/org/jboss/netty/handler/ssl/SslHandler.java b/src/main/java/org/jboss/netty/handler/ssl/SslHandler.java index f0200f3314..a4d9b4ae9a 100644 --- a/src/main/java/org/jboss/netty/handler/ssl/SslHandler.java +++ b/src/main/java/org/jboss/netty/handler/ssl/SslHandler.java @@ -66,9 +66,9 @@ import org.jboss.netty.util.internal.ImmediateExecutor; * *

Beginning the handshake

*

- * A user should make sure not to write a message while the - * {@linkplain #handshake(Channel) handshake} is in progress unless it is a - * renegotiation. You will be notified by the {@link ChannelFuture} which is + * You must make sure not to write a message while the + * {@linkplain #handshake(Channel) handshake} is in progress unless you are + * renegotiating. You will be notified by the {@link ChannelFuture} which is * returned by the {@link #handshake(Channel)} method when the handshake * process succeeds or fails. * @@ -95,6 +95,36 @@ import org.jboss.netty.util.internal.ImmediateExecutor; * {@link SslHandler} with a new {@link SSLEngine} into the pipeline, * and start the handshake process as described in the first section. * + *

Implementing StartTLS

+ *

+ * Typically, StartTLS is composed of three steps. + *

    + *
  1. Client sends a StartTLS request to server.
    2. + *
  2. Server sends a StartTLS response to client.
    3. + *
  3. Client begins SSL handshake.
    4. + *
+ * If you implement a server, you need to: + *
    + *
  1. create a new {@link SslHandler} instance with {@code startTls} flag set + * to {@code true},
    2. + *
  2. insert the {@link SslHandler} to the {@link ChannelPipeline}, and
    3. + *
  3. write a StartTLS response.
    4. + *
+ * Please note that you must insert {@link SslHandler} before sending + * the 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. + *

    + *
  1. Write a StartTLS request,
    2. + *
  2. wait for the StartTLS response,
    3. + *
  3. create a new {@link SslHandler} instance with {@code startTls} flag set + * to {@code false},
    4. + *
  4. insert the {@link SslHandler} to the {@link ChannelPipeline}, and
    5. + *
  5. Initiate SSL handshake by calling {@link SslHandler#handshake(Channel)}.
    6. + *
+ * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) *