8148500: [Spec] Enabled SSL Protocols may not be used

Reviewed-by: mullan, jnimeh

jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -875,10 +875,11 @@ public abstract class SSLEngine {
      * created, all enabled cipher suites support a minimum quality of
      * service.  Thus, in some environments this value might be empty.
      * <P>
-     * Even if a suite has been enabled, it might never be used.  (For
+     * Note that even if a suite is enabled, it may never be used. This
-     * example, the peer does not support it, the requisite
+     * can occur if the peer does not support it, or its use is restricted,
-     * certificates/private keys for the suite are not available, or an
+     * or the requisite certificates (and private keys) for the suite are
-     * anonymous suite is enabled but authentication is required.)
+     * not available, or an anonymous suite is enabled but authentication
+     * is required.
      *
      * @return  an array of cipher suite names
      * @see     #getSupportedCipherSuites()
@@ -920,6 +921,11 @@ public abstract class SSLEngine {
     /**
      * Returns the names of the protocol versions which are currently
      * enabled for use with this {@code SSLEngine}.
+     * <P>
+     * Note that even if a protocol is enabled, it may never be used.
+     * This can occur if the peer does not support the protocol, or its
+     * use is restricted, or there are no enabled cipher suites supported
+     * by the protocol.
      *
      * @return  an array of protocols
      * @see     #setEnabledProtocols(String [])

jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -190,12 +190,11 @@ public abstract class SSLServerSocket extends ServerSocket {
      * default guarantees a minimum quality of service in all enabled
      * cipher suites.
      * <P>
-     * There are several reasons why an enabled cipher suite might
+     * Note that even if a suite is enabled, it may never be used. This
-     * not actually be used.  For example:  the server socket might
+     * can occur if the peer does not support it, or its use is restricted,
-     * not have appropriate private keys available to it or the cipher
+     * or the requisite certificates (and private keys) for the suite are
-     * suite might be anonymous, precluding the use of client authentication,
+     * not available, or an anonymous suite is enabled but authentication
-     * while the server socket has been told to require that sort of
+     * is required.
-     * authentication.
      *
      * @return an array of cipher suites enabled
      * @see #getSupportedCipherSuites()
@@ -258,6 +257,11 @@ public abstract class SSLServerSocket extends ServerSocket {
     /**
      * Returns the names of the protocols which are currently
      * enabled for use by the newly accepted connections.
+     * <P>
+     * Note that even if a protocol is enabled, it may never be used.
+     * This can occur if the peer does not support the protocol, or its
+     * use is restricted, or there are no enabled cipher suites supported
+     * by the protocol.
      *
      * @return an array of protocol names
      * @see #getSupportedProtocols()

jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -279,10 +279,11 @@ public abstract class SSLSocket extends Socket
      * created, all enabled cipher suites support a minimum quality of
      * service.  Thus, in some environments this value might be empty.
      * <P>
-     * Even if a suite has been enabled, it might never be used.  (For
+     * Note that even if a suite is enabled, it may never be used. This
-     * example, the peer does not support it, the requisite certificates
+     * can occur if the peer does not support it, or its use is restricted,
-     * (and private keys) for the suite are not available, or an
+     * or the requisite certificates (and private keys) for the suite are
-     * anonymous suite is enabled but authentication is required.
+     * not available, or an anonymous suite is enabled but authentication
+     * is required.
      *
      * @return an array of cipher suite names
      * @see #getSupportedCipherSuites()
@@ -324,6 +325,12 @@ public abstract class SSLSocket extends Socket
     /**
      * Returns the names of the protocol versions which are currently
      * enabled for use on this connection.
+     * <P>
+     * Note that even if a protocol is enabled, it may never be used.
+     * This can occur if the peer does not support the protocol, or its
+     * use is restricted, or there are no enabled cipher suites supported
+     * by the protocol.
+     *
      * @see #setEnabledProtocols(String [])
      * @return an array of protocols
      */