From a8eda60857b8ad118327db0687b4b95a38f8f9f5 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Mon, 25 Jan 2010 11:40:47 +0000
Subject: [PATCH] Explanation on implementing client cert auth

---
 .../SecureChatServerPipelineFactory.java      |  3 +++
 .../SecureChatSslContextFactory.java          | 23 ++++++++++++++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/jboss/netty/example/securechat/SecureChatServerPipelineFactory.java b/src/main/java/org/jboss/netty/example/securechat/SecureChatServerPipelineFactory.java
index 2f304dc1ac..01952141f7 100644
--- a/src/main/java/org/jboss/netty/example/securechat/SecureChatServerPipelineFactory.java
+++ b/src/main/java/org/jboss/netty/example/securechat/SecureChatServerPipelineFactory.java
@@ -47,6 +47,9 @@ public class SecureChatServerPipelineFactory implements
         // and accept any invalid certificates in the client side.
         // You will need something more complicated to identify both
         // and server in the real world.
+        //
+        // Read SecureChatSslContextFactory
+        // if you need client certificate authentication.
 
         SSLEngine engine =
             SecureChatSslContextFactory.getServerContext().createSSLEngine();
diff --git a/src/main/java/org/jboss/netty/example/securechat/SecureChatSslContextFactory.java b/src/main/java/org/jboss/netty/example/securechat/SecureChatSslContextFactory.java
index ae0ff1ebfe..3db64e0d20 100644
--- a/src/main/java/org/jboss/netty/example/securechat/SecureChatSslContextFactory.java
+++ b/src/main/java/org/jboss/netty/example/securechat/SecureChatSslContextFactory.java
@@ -18,16 +18,37 @@ package org.jboss.netty.example.securechat;
 import java.security.KeyStore;
 import java.security.Security;
 
+import javax.net.ssl.KeyManager;
 import javax.net.ssl.KeyManagerFactory;
 import javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLEngine;
+import javax.net.ssl.TrustManager;
+
+import org.jboss.netty.handler.ssl.SslHandler;
 
 /**
  * Creates a bogus {@link SSLContext}.  A client-side context created by this
  * factory accepts any certificate even if it is invalid.  A server-side context
  * created by this factory sends a bogus certificate defined in {@link SecureChatKeyStore}.
- *
+ * <p>
  * You will have to create your context differently in a real world application.
  *
+ * <h3>Client Certificate Authentication</h3>
+ *
+ * To enable client certificate authentication:
+ * <ul>
+ * <li>Enable client authentication on the server side by calling
+ *     {@link SSLEngine#setNeedClientAuth(boolean)} before creating
+ *     {@link SslHandler}.</li>
+ * <li>When initializing an {@link SSLContext} on the client side,
+ *     specify the {@link KeyManager} that contains the client certificate as
+ *     the first argument of {@link SSLContext#init(KeyManager[], javax.net.ssl.TrustManager[], java.security.SecureRandom)}.</li>
+ * <li>When initializing an {@link SSLContext} on the server side,
+ *     specify the proper {@link TrustManager} as the second argument of
+ *     {@link SSLContext#init(KeyManager[], javax.net.ssl.TrustManager[], java.security.SecureRandom)}
+ *     to validate the the client certificate.</li>
+ * </ul>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)
  *