Add warnings to getSupportedCipherSuites()

One of our supported cipher suites is TLS_FALLBACK_SCSV.  It's useful
to support this in order to enable downgrade attack protection on
client-initiated version fallbacks, but if it's enabled improperly it
can prevent connections to servers that support higher versions than
the client.  (In particular, TLS 1.3-supporting servers will reject
connections from clients that only support TLS 1.2 if
TLS_FALLBACK_SCSV is enabled.)

To attempt to discourage that, warn users against blindly enabling all
cipher suites, and show them the appropriate way to use
getSupportedCipherSuites().

Test: make docs
Fixes: 128907031
Change-Id: I31bf4f886185d21118b281d014d6761c0d92ba60
diff --git a/ojluni/src/main/java/javax/net/ssl/SSLEngine.java b/ojluni/src/main/java/javax/net/ssl/SSLEngine.java
index d5070ac..76f8f66 100644
--- a/ojluni/src/main/java/javax/net/ssl/SSLEngine.java
+++ b/ojluni/src/main/java/javax/net/ssl/SSLEngine.java
@@ -1523,6 +1523,7 @@
     public abstract boolean isOutboundDone();
 
 
+    // Android-changed: Added warnings about misuse
     /**
      * Returns the names of the cipher suites which could be enabled for use
      * on this engine.  Normally, only a subset of these will actually
@@ -1530,6 +1531,15 @@
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites might be useful in specialized applications.
      *
+     * <p class="caution">Applications should not blindly enable all supported
+     * cipher suites.  The supported cipher suites can include signaling cipher suite
+     * values that can cause connection problems if enabled inappropriately.
+     *
+     * <p>The proper way to use this method is to either check if a specific cipher
+     * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)}
+     * or to filter a desired list of cipher suites to only the supported ones via
+     * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}.
+     *
      * @return  an array of cipher suite names
      * @see     #getEnabledCipherSuites()
      * @see     #setEnabledCipherSuites(String [])
diff --git a/ojluni/src/main/java/javax/net/ssl/SSLServerSocket.java b/ojluni/src/main/java/javax/net/ssl/SSLServerSocket.java
index 7b07cfa..35c14ea 100644
--- a/ojluni/src/main/java/javax/net/ssl/SSLServerSocket.java
+++ b/ojluni/src/main/java/javax/net/ssl/SSLServerSocket.java
@@ -229,6 +229,7 @@
     public abstract void setEnabledCipherSuites(String suites []);
 
 
+    // Android-changed: Added warnings about misuse
     /**
      * Returns the names of the cipher suites which could be enabled for use
      * on an SSL connection.
@@ -238,6 +239,15 @@
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites are useful in specialized applications.
      *
+     * <p class="caution">Applications should not blindly enable all supported
+     * cipher suites.  The supported cipher suites can include signaling cipher suite
+     * values that can cause connection problems if enabled inappropriately.
+     *
+     * <p>The proper way to use this method is to either check if a specific cipher
+     * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)}
+     * or to filter a desired list of cipher suites to only the supported ones via
+     * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}.
+     *
      * @return an array of cipher suite names
      * @see #getEnabledCipherSuites()
      * @see #setEnabledCipherSuites(String [])
diff --git a/ojluni/src/main/java/javax/net/ssl/SSLServerSocketFactory.java b/ojluni/src/main/java/javax/net/ssl/SSLServerSocketFactory.java
index 2db63bb..5067f8f 100644
--- a/ojluni/src/main/java/javax/net/ssl/SSLServerSocketFactory.java
+++ b/ojluni/src/main/java/javax/net/ssl/SSLServerSocketFactory.java
@@ -162,6 +162,7 @@
     public abstract String [] getDefaultCipherSuites();
 
 
+    // Android-changed: Added warnings about misuse
     /**
      * Returns the names of the cipher suites which could be enabled for use
      * on an SSL connection created by this factory.
@@ -170,6 +171,15 @@
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites are useful in specialized applications.
      *
+     * <p class="caution">Applications should not blindly enable all supported
+     * cipher suites.  The supported cipher suites can include signaling cipher suite
+     * values that can cause connection problems if enabled inappropriately.
+     *
+     * <p>The proper way to use this method is to either check if a specific cipher
+     * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)}
+     * or to filter a desired list of cipher suites to only the supported ones via
+     * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}.
+     *
      * @return an array of cipher suite names
      * @see #getDefaultCipherSuites()
      */
diff --git a/ojluni/src/main/java/javax/net/ssl/SSLSocket.java b/ojluni/src/main/java/javax/net/ssl/SSLSocket.java
index f75538e..a2ba960 100644
--- a/ojluni/src/main/java/javax/net/ssl/SSLSocket.java
+++ b/ojluni/src/main/java/javax/net/ssl/SSLSocket.java
@@ -1019,6 +1019,7 @@
         { super(address, port, clientAddress, clientPort); }
 
 
+    // Android-changed: Added warnings about misuse
     /**
      * Returns the names of the cipher suites which could be enabled for use
      * on this connection.  Normally, only a subset of these will actually
@@ -1026,6 +1027,15 @@
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites might be useful in specialized applications.
      *
+     * <p class="caution">Applications should not blindly enable all supported
+     * cipher suites.  The supported cipher suites can include signaling cipher suite
+     * values that can cause connection problems if enabled inappropriately.
+     *
+     * <p>The proper way to use this method is to either check if a specific cipher
+     * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)}
+     * or to filter a desired list of cipher suites to only the supported ones via
+     * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}.
+     *
      * @return an array of cipher suite names
      * @see #getEnabledCipherSuites()
      * @see #setEnabledCipherSuites(String [])
diff --git a/ojluni/src/main/java/javax/net/ssl/SSLSocketFactory.java b/ojluni/src/main/java/javax/net/ssl/SSLSocketFactory.java
index 93b5dc7..8b0966b 100644
--- a/ojluni/src/main/java/javax/net/ssl/SSLSocketFactory.java
+++ b/ojluni/src/main/java/javax/net/ssl/SSLSocketFactory.java
@@ -187,6 +187,7 @@
      */
     public abstract String [] getDefaultCipherSuites();
 
+    // Android-changed: Added warnings about misuse
     /**
      * Returns the names of the cipher suites which could be enabled for use
      * on an SSL connection.  Normally, only a subset of these will actually
@@ -194,6 +195,15 @@
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites are useful in specialized applications.
      *
+     * <p class="caution">Applications should not blindly enable all supported
+     * cipher suites.  The supported cipher suites can include signaling cipher suite
+     * values that can cause connection problems if enabled inappropriately.
+     *
+     * <p>The proper way to use this method is to either check if a specific cipher
+     * suite is supported via {@code Arrays.asList(getSupportedCipherSuites()).contains(...)}
+     * or to filter a desired list of cipher suites to only the supported ones via
+     * {@code desiredSuiteSet.retainAll(Arrays.asList(getSupportedCipherSuites()))}.
+     *
      * @see #getDefaultCipherSuites()
      * @return an array of cipher suite names
      */