Document hostname verification for Java client

References rabbitmq/rabbitmq-java-client#394

Author: acogoluegnes

site/api-guide.xml

@@ -1698,7 +1698,7 @@ factory.useSslProtocol();
         To learn more about TLS support in RabbitMQ, see
         the <a href="ssl.html">TLS guide</a>. If you only want to configure
         the Java client (especially the peer verification and trust manager parts),
-        read <a href="ssl.html#trust-levels">the appropriate section</a> of the TLS guide.
+        read <a href="ssl.html#java-client">the appropriate section</a> of the TLS guide.
       </p>
     </doc:section>
   </body>

site/ssl.xml

@@ -722,14 +722,11 @@ ssl_options.fail_if_no_peer_cert = false
 import java.io.*;
 import java.security.*;
 
-
 import com.rabbitmq.client.*;
 
-public class Example1
-{
-    public static void main(String[] args) throws Exception
-    {
+public class Example1 {
 
+    public static void main(String[] args) throws Exception {
         ConnectionFactory factory = new ConnectionFactory();
         factory.setHost("localhost");
         factory.setPort(5671);
@@ -745,16 +742,14 @@ public class Example1
         channel.queueDeclare("rabbitmq-java-test", false, true, true, null);
         channel.basicPublish("", "rabbitmq-java-test", null, "Hello, World".getBytes());
 
-
         GetResponse chResponse = channel.basicGet("rabbitmq-java-test", false);
-        if(chResponse == null) {
+        if (chResponse == null) {
             System.out.println("No message retrieved");
         } else {
             byte[] body = chResponse.getBody();
-            System.out.println("Recieved: " + new String(body));
+            System.out.println("Received: " + new String(body));
         }
 
-
         channel.close();
         conn.close();
     }
@@ -806,12 +801,9 @@ import javax.net.ssl.*;
 
 import com.rabbitmq.client.*;
 
+public class Example2 {
 
-public class Example2
-{
-    public static void main(String[] args) throws Exception
-    {
-
+    public static void main(String[] args) throws Exception {
       char[] keyPassphrase = "MySecretPassword".toCharArray();
       KeyStore ks = KeyStore.getInstance("PKCS12");
       ks.load(new FileInputStream("/path/to/client_key.p12"), keyPassphrase);
@@ -826,30 +818,29 @@ public class Example2
       TrustManagerFactory tmf = TrustManagerFactory.getInstance("SunX509");
       tmf.init(tks);
 
-      SSLContext c = SSLContext.getInstance("TLSv1.1");
+      SSLContext c = SSLContext.getInstance("TLSv1.2");
       c.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);
 
       ConnectionFactory factory = new ConnectionFactory();
       factory.setHost("localhost");
       factory.setPort(5671);
       factory.useSslProtocol(c);
+      factory.enableHostnameVerification();
 
       Connection conn = factory.newConnection();
       Channel channel = conn.createChannel();
 
       channel.queueDeclare("rabbitmq-java-test", false, true, true, null);
       channel.basicpublish("", "rabbitmq-java-test", null, "Hello, World".getBytes());
 
-
       GetResponse chResponse = channel.basicGet("rabbitmq-java-test", false);
-      if(chResponse == null) {
+      if (chResponse == null) {
           System.out.println("No message retrieved");
       } else {
           byte[] body = chResponse.getBody();
-          System.out.println("Recieved: " + new String(body));
+          System.out.println("Received: " + new String(body));
       }
 
-
       channel.close();
       conn.close();
   }
@@ -861,6 +852,33 @@ public class Example2
             a RabbitMQ node with a certificate that has not been imported
             into the key store and watch the connection fail.
           </p>
+
+          <p>
+            Note hostname verification must be explicitly enabled with
+            <code>ConnectionFactory#enableHostnameVerification()</code>. This checks
+            that the server certificate has been issued for the hostname the
+            client is requested. If you're using Java 6, you need to add
+            the Commons HttpClient dependency to your project, e.g. for Maven
+            and Gradle:
+          </p>
+<pre class="sourcecode xml">
+&lt;!-- Maven dependency to add for hostname verification on Java 6 --&gt;
+&lt;dependency&gt;
+    &lt;groupId&gt;org.apache.httpcomponents&lt;/groupId&gt;
+    &lt;artifactId&gt;httpclient&lt;/artifactId&gt;
+    &lt;version&gt;4.5.6&lt;/version&gt;
+&lt;/dependency&gt;
+</pre>
+<pre class="sourcecode groovy">
+// Gradle dependency to add for hostname verification on Java 6
+compile group: 'org.apache.httpcomponents', name: 'httpclient', version: '4.5.6'
+</pre>
+          <p>If you don't want to use Commons HttpClient, use
+            <code>ConnectionFactory#enableHostnameVerification(HostnameVerifier)</code>
+            with the <code>HostnameVerifier</code> instance of your choice. Again, this is
+            needed only for Java 6, hostname verification is built-in in Java 7 and more.
+          </p>
+
         </doc:subsection>
 
         <doc:subsection name="tls-versions-java-client">