Improve qhelp

Author: atorralba

java/ql/src/Security/CWE/CWE-273/UnsafeCertTrust.qhelp

@@ -4,26 +4,23 @@
 <qhelp>
 
 <overview>
-<p>When SSLSocket or SSLEngine is created without a valid parameter of setEndpointIdentificationAlgorithm, hostname verification is disabled by default.</p>
-<p>Unsafe implementation of the interface X509TrustManager and SSLSocket/SSLEngine ignores all SSL certificate validation errors when establishing an HTTPS connection, thereby making the app vulnerable to man-in-the-middle attacks.</p>
-<p>This query checks whether setEndpointIdentificationAlgorithm is missing. The query also covers a special implementation com.rabbitmq.client.ConnectionFactory.</p>
+<p>Java offers two mechanisms for SSL authentication - trust manager and hostname verifier (the later is checked by the <code>java/insecure-hostname-verifier</code> query). Trust manager validates the peer's certificate chain while hostname verification establishes that the hostname in the URL matches the hostname in the server's identification.</p>
+<p>When <code>SSLSocket</code> or <code>SSLEngine</code> are created without a secure <code>setEndpointIdentificationAlgorithm</code>, hostname verification is disabled by default.</p>
+<p>This query checks whether a trust manager is set to trust all certificates or <code>setEndpointIdentificationAlgorithm</code> is missing, thereby making the application vulnerable to man-in-the-middle attacks. The query also covers insecure configurations of <code>com.rabbitmq.client.ConnectionFactory</code>.</p>
 </overview>
 
 <recommendation>
-<p>Validate SSL certificate in SSL authentication.</p>
+<p>Validate SSL certificates in SSL authentication.</p>
 </recommendation>
 
 <example>
 <p>The following two examples show two ways of configuring SSLSocket/SSLEngine. In the 'BAD' case,
-setEndpointIdentificationAlgorithm is not called, thus no hostname verification takes place. In the 'GOOD' case, setEndpointIdentificationAlgorithm is called.</p>
+<code>setEndpointIdentificationAlgorithm</code> is not called, thus no hostname verification takes place. In the 'GOOD' case, <code>setEndpointIdentificationAlgorithm</code> is called.</p>
 <sample src="UnsafeCertTrust.java" />
 </example>
 
 <references>
 <li>
-<a href="https://cwe.mitre.org/data/definitions/273.html">CWE-273</a>
-</li>
-<li>
 <a href="https://github.com/OWASP/owasp-mstg/blob/master/Document/0x05g-Testing-Network-Communication.md">Testing Endpoint Identify Verification (MSTG-NETWORK-3)</a>
 </li>
 <li>