Improve documentation around HostnameVerifier

Explain usage of HostnameVerifier / HttpsURLConnection.

Bug: 126851476
Test: make docs / visual inspection
Merged-In: I6bc86f8e7efc47521316d41e07ef546ea995061c
Change-Id: I6bc86f8e7efc47521316d41e07ef546ea995061c
(cherry picked from commit 9f5e6f22bdc086ee0396f01556e3367c621737c0)

diff --git a/core/java/android/net/SSLCertificateSocketFactory.java b/core/java/android/net/SSLCertificateSocketFactory.java
index 45860b3..95d66bb 100644 (file)
--- a/core/java/android/net/SSLCertificateSocketFactory.java
+++ b/core/java/android/net/SSLCertificateSocketFactory.java
@@ -62,7 +62,7 @@ import javax.net.ssl.X509TrustManager;
  *
  * The handshake timeout does not apply to actual TCP socket connection.
  * If you want a connection timeout as well, use {@link #createSocket()}
- * and {@link Socket#connect(SocketAddress, int)}, after which you
+ * and {@link Socket#connect(java.net.SocketAddress, int)}, after which you
  * must verify the identity of the server you are connected to.
  *
  * <p class="caution"><b>Most {@link SSLSocketFactory} implementations do not
@@ -211,14 +211,14 @@ public class SSLCertificateSocketFactory extends SSLSocketFactory {
     }
 
     /**
-     * Verify the hostname of the certificate used by the other end of a
-     * connected socket.  You MUST call this if you did not supply a hostname
-     * to {@link #createSocket()}.  It is harmless to call this method
-     * redundantly if the hostname has already been verified.
+     * Verify the hostname of the certificate used by the other end of a connected socket using the
+     * {@link HostnameVerifier} obtained from {@code
+     * HttpsURLConnection.getDefaultHostnameVerifier()}. You MUST call this if you did not supply a
+     * hostname to {@link #createSocket()}.  It is harmless to call this method redundantly if the
+     * hostname has already been verified.
      *
-     * <p>Wildcard certificates are allowed to verify any matching hostname,
-     * so "foo.bar.example.com" is verified if the peer has a certificate
-     * for "*.example.com".
+     * <p>Wildcard certificates are allowed to verify any matching hostname, so
+     * "foo.bar.example.com" is verified if the peer has a certificate for "*.example.com".
      *
      * @param socket An SSL socket which has been connected to a server
      * @param hostname The expected hostname of the remote server
@@ -483,7 +483,8 @@ public class SSLCertificateSocketFactory extends SSLSocketFactory {
      * {@inheritDoc}
      *
      * <p>By default, this method returns a <i>connected</i> socket and verifies the peer's
-     * certificate hostname after connecting; if this instance was created with
+     * certificate hostname after connecting using the {@link HostnameVerifier} obtained from
+     * {@code HttpsURLConnection.getDefaultHostnameVerifier()}; if this instance was created with
      * {@link #getInsecure(int, SSLSessionCache)}, it returns a socket that is <i>not connected</i>
      * instead.
      */
@@ -562,7 +563,8 @@ public class SSLCertificateSocketFactory extends SSLSocketFactory {
      * {@inheritDoc}
      *
      * <p>By default, this method returns a <i>connected</i> socket and verifies the peer's
-     * certificate hostname after connecting; if this instance was created with
+     * certificate hostname after connecting using the {@link HostnameVerifier} obtained from
+     * {@code HttpsURLConnection.getDefaultHostnameVerifier()}; if this instance was created with
      * {@link #getInsecure(int, SSLSessionCache)}, it returns a socket that is <i>not connected</i>
      * instead.
      */
@@ -585,7 +587,8 @@ public class SSLCertificateSocketFactory extends SSLSocketFactory {
      * {@inheritDoc}
      *
      * <p>By default, this method returns a <i>connected</i> socket and verifies the peer's
-     * certificate hostname after connecting; if this instance was created with
+     * certificate hostname after connecting using the {@link HostnameVerifier} obtained from
+     * {@code HttpsURLConnection.getDefaultHostnameVerifier()}; if this instance was created with
      * {@link #getInsecure(int, SSLSessionCache)}, it returns a socket that is <i>not connected</i>
      * instead.
      */