Stronger language around ConnectionFactory methods that enable TLS with a permissive TrustManager

Make it clear which methods are offered for convenience in development environments.

Author: michaelklishin

src/main/java/com/rabbitmq/client/ConnectionFactory.java

@@ -653,12 +653,14 @@ public boolean isSSL(){
     }
 
     /**
-     * Convenience method for setting up a SSL socket factory/engine, using
-     * the DEFAULT_SSL_PROTOCOL and a trusting TrustManager.
-     * Note the trust manager will trust every server certificate presented
+     * Convenience method for configuring TLS using
+     * the default set of TLS protocols and a trusting TrustManager.
+     * This setup is <strong>only suitable for development
+     * and QA environments</strong>.
+     * The trust manager will <strong>trust every server certificate presented</strong>
      * to it, this is convenient for local development but
-     * not recommended to use in production as it provides no protection
-     * against man-in-the-middle attacks.
+     * <strong>not recommended to use in production</strong> as it provides no protection
+     * against man-in-the-middle attacks. Prefer {@link #useSslProtocol(SSLContext)}.
      */
     public void useSslProtocol()
         throws NoSuchAlgorithmException, KeyManagementException
@@ -667,15 +669,19 @@ public void useSslProtocol()
     }
 
     /**
-     * Convenience method for setting up a SSL socket factory/engine, using
-     * the supplied protocol and a very trusting TrustManager.
-     * Note the trust manager will trust every server certificate presented
+     * Convenience method for configuring TLS using
+     * the supplied protocol and a very trusting TrustManager. This setup is <strong>only suitable for development
+     * and QA environments</strong>.
+     * The trust manager <strong>will trust every server certificate presented</strong>
      * to it, this is convenient for local development but
-     * not recommended to use in production as it provides no protection
-     * against man-in-the-middle attacks.
+     * not recommended to use in production as it <strong>provides no protection
+     * against man-in-the-middle attacks</strong>.
+     *
+     * Use {@link #useSslProtocol(SSLContext)} in production environments.
      * The produced {@link SSLContext} instance will be shared by all
-     * the connections created by this connection factory. Use
-     * {@link #setSslContextFactory(SslContextFactory)} for more flexibility.
+     * the connections created by this connection factory.
+     *
+     * Use {@link #setSslContextFactory(SslContextFactory)} for more flexibility.
      * @see #setSslContextFactory(SslContextFactory)
      */
     public void useSslProtocol(String protocol)
@@ -685,13 +691,18 @@ public void useSslProtocol(String protocol)
     }
 
     /**
-     * Convenience method for setting up an SSL socket factory/engine.
-     * Pass in the SSL protocol to use, e.g. "TLSv1" or "TLSv1.2".
+     * Convenience method for configuring TLS.
+     * Pass in the TLS protocol version to use, e.g. "TLSv1.2" or "TLSv1.1", and
+     * a desired {@link TrustManager}.
+     *
+     *
      * The produced {@link SSLContext} instance will be shared with all
      * the connections created by this connection factory. Use
      * {@link #setSslContextFactory(SslContextFactory)} for more flexibility.
-     * @param protocol SSL protocol to use.
+     * @param protocol the TLS protocol to use.
+     * @param trustManager the {@link TrustManager} implementation to use.
      * @see #setSslContextFactory(SslContextFactory)
+     * @see #useSslProtocol(SSLContext)
      */
     public void useSslProtocol(String protocol, TrustManager trustManager)
         throws NoSuchAlgorithmException, KeyManagementException
@@ -702,8 +713,11 @@ public void useSslProtocol(String protocol, TrustManager trustManager)
     }
 
     /**
-     * Convenience method for setting up an SSL socket socketFactory/engine.
-     * Pass in an initialized SSLContext.
+     * Sets up TLS with an initialized {@link SSLContext}. The caller is responsible
+     * for setting up the context with a {@link TrustManager} with suitable security guarantees,
+     * e.g. peer verification.
+     *
+     *
      * The {@link SSLContext} instance will be shared with all
      * the connections created by this connection factory. Use
      * {@link #setSslContextFactory(SslContextFactory)} for more flexibility.

src/main/java/com/rabbitmq/client/TrustEverythingTrustManager.java

@@ -22,16 +22,18 @@
 import java.security.cert.X509Certificate;
 
 /**
- * Convenience class providing a default implementation of javax.net.ssl.X509TrustManager.
- * Trusts every single certificate presented to it.
+ * Convenience class providing a default implementation of {@link javax.net.ssl.X509TrustManager}.
+ * Trusts every single certificate presented to it. This implementation does not perform peer
+ * verification and <strong>provides no protection against Man-in-the-Middle (MITM) attacks</strong> and therefore
+ * <strong>only suitable for some development and QA environments</strong>.
  */
 public class TrustEverythingTrustManager implements X509TrustManager {
 
     public TrustEverythingTrustManager() {
         LoggerFactory.getLogger(TrustEverythingTrustManager.class).warn(
-            "This trust manager trusts every certificate, effectively disabling peer verification. " +
-            "This is convenient for local development but prone to man-in-the-middle attacks. " +
-            "Please see http://www.rabbitmq.com/ssl.html#validating-cerficates to learn more about peer certificate validation."
+            "SECURITY ALERT: this trust manager trusts every certificate, effectively disabling peer verification. " +
+            "This is convenient for local development but offers no protection against man-in-the-middle attacks. " +
+            "Please see https://www.rabbitmq.com/ssl.html#validating-cerficates to learn more about peer certificate verification."
         );
     }