Improve Javadoc

Signed-off-by: Mandy Chessell <[email protected]>

open-metadata-implementation/adapters/authentication-plugins/http-helper/README.md

@@ -1,11 +1,19 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 <!-- Copyright Contributors to the ODPi Egeria project 2019. -->
 
-![Released](../../../../images/egeria-content-status-released.png#pagewidth)
+![Stable](../../../../images/egeria-content-status-released.png#pagewidth)
 
 # HTTP Helper
 
-A plug-in for managing Transport Level Security (TLS) in the server.
+A plug-in for managing Transport Level Security (TLS) in a client.
+
+## Client-side certificate checking
+
+Egeria is set up to validate certificates in the caller to a REST API.
+The certificate received from the server is typically validated against
+the certificates in the client's trust store.
+
+The HTTP helpers make it possible to turn off this certificate checking.
 
 ----
 Return to [authentication-plugins](..) module.

open-metadata-implementation/adapters/authentication-plugins/http-helper/src/main/java/org/odpi/openmetadata/http/HttpHelper.java

@@ -12,55 +12,63 @@
 import java.security.GeneralSecurityException;
 import java.security.cert.X509Certificate;
 
-public class HttpHelper {
+/**
+ * Turn off client-side checking of certificates.  There are two options, one to turn it off all the time and the other is
+ * controlled through the -Dstrict.ssl=false property.
+ */
+public class HttpHelper
+{
 
     private static final Logger LOGGER = LoggerFactory.getLogger(HttpHelper.class);
 
     /**
-     * Allows using self signed certificates https connections
-     * makes all the clients and servers trusted no matter the certificate
+     * Allows the use of self-signed certificates on https connections.
+     * The client will trust the server no matter which certificate is sent.
      */
     public static void noStrictSSL(){
 
         LOGGER.warn("Strict SSL is set to false! Invalid certificates will be accepted for connection!");
 
         // Create a trust manager that does not validate certificate chains
         TrustManager[] trustAllCerts = new TrustManager[] {
-                new X509TrustManager() {
+                new X509TrustManager()
+                {
                     public java.security.cert.X509Certificate[] getAcceptedIssuers() {
                         return new X509Certificate[0];
                     }
-                    public void checkClientTrusted(
-                            java.security.cert.X509Certificate[] certs, String authType) {
+                    public void checkClientTrusted(java.security.cert.X509Certificate[] certs, String authType)
+                    {
                     }
-                    public void checkServerTrusted(
-                            java.security.cert.X509Certificate[] certs, String authType) {
+                    public void checkServerTrusted(java.security.cert.X509Certificate[] certs, String authType)
+                    {
                     }
                 }
         };
 
         // Install the all-trusting trust manager
-        try {
+        try
+        {
             SSLContext sc = SSLContext.getInstance("SSL");
             sc.init(null, trustAllCerts, new java.security.SecureRandom());
             HttpsURLConnection.setDefaultSSLSocketFactory(sc.getSocketFactory());
             HttpsURLConnection.setDefaultHostnameVerifier ((hostname, session) -> true);
-        } catch (GeneralSecurityException e) {
+        }
+        catch (GeneralSecurityException e)
+        {
             LOGGER.error("The configuration for no strict SSL went wrong");
         }
     }
 
+
     /**
-     * Allows using self signed certificates https connections
-     * makes all the clients and servers trusted no matter the certificate
-     * Only if the override property strict.ssl is set
+     * Allows using self-signed certificates https connections.
+     * If -Dstrict.ssl=false is set, the client will trust the server no matter the certificate passed.
      */
-    public static void noStrictSSLIfConfigured() {
+    public static void noStrictSSLIfConfigured()
+    {
         if ("false".equalsIgnoreCase(System.getProperty("strict.ssl")))
         {
             noStrictSSL();
         }
-
     }
-
 }