Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 4f1bce22 authored by Neil Fuller's avatar Neil Fuller
Browse files

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 9f5e6f22)
parent bee0cbe5

core/java/android/net/SSLCertificateSocketFactory.java

+14 −11
Original line number Diff line number Diff line
@@ -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.

     */