changeset 40411:e936d2ba0281

8162808: Add references to the standard JSSE cipher suite names in javadoc Summary: Add hyperlinks to the cipher suite section of the Standard Names documentation for various SSL class methods when they reference cipher suites by name Reviewed-by: xuelei, mullan
author jnimeh
date Thu, 18 Aug 2016 12:48:23 -0700
parents 5fd4a1f809f8
children 30db85b72746
files jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocket.java jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocketFactory.java jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java jdk/src/java.base/share/classes/javax/net/ssl/SSLSocketFactory.java
diffstat 6 files changed, 123 insertions(+), 5 deletions(-) [+]
line wrap: on
line diff
--- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java	Thu Aug 18 22:07:09 2016 +0300
+++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java	Thu Aug 18 12:48:23 2016 -0700
@@ -861,6 +861,13 @@
      * be enabled by default, since this list may include cipher suites which
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites might be useful in specialized applications.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return  an array of cipher suite names
      * @see     #getEnabledCipherSuites()
@@ -880,6 +887,13 @@
      * or the requisite certificates (and private keys) for the suite are
      * not available, or an anonymous suite is enabled but authentication
      * is required.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return  an array of cipher suite names
      * @see     #getSupportedCipherSuites()
@@ -896,6 +910,14 @@
      * fail.  Following a successful call to this method, only suites
      * listed in the {@code suites} parameter are enabled for use.
      * <P>
+     * Note that the standard list of cipher suite names may be found in the
+     * <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation.  Providers
+     * may support cipher suite names not found in this list or might not
+     * use the recommended name for a certain cipher suite.
+     * <P>
      * See {@link #getEnabledCipherSuites()} for more information
      * on why a specific cipher suite may never be used on a engine.
      *
--- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java	Thu Aug 18 22:07:09 2016 +0300
+++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java	Thu Aug 18 12:48:23 2016 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 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
@@ -108,7 +108,12 @@
      * <p>
      * Calling this constructor is equivalent to calling the no-args
      * constructor followed by
-     * {@code setCipherSuites(cipherSuites);}.
+     * {@code setCipherSuites(cipherSuites);}.  Note that the
+     * standard list of cipher suite names may be found in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation.  Providers
+     * may support cipher suite names not found in this list.
      *
      * @param cipherSuites the array of ciphersuites (or null)
      */
@@ -123,6 +128,12 @@
      * Calling this constructor is equivalent to calling the no-args
      * constructor followed by
      * {@code setCipherSuites(cipherSuites); setProtocols(protocols);}.
+     * Note that the standard list of cipher suite names may be found in the
+     * <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation.  Providers
+     * may support cipher suite names not found in this list.
      *
      * @param cipherSuites the array of ciphersuites (or null)
      * @param protocols the array of protocols (or null)
@@ -139,6 +150,13 @@
     /**
      * Returns a copy of the array of ciphersuites or null if none
      * have been set.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return a copy of the array of ciphersuites or null if none
      * have been set.
@@ -150,7 +168,13 @@
     /**
      * Sets the array of ciphersuites.
      *
-     * @param cipherSuites the array of ciphersuites (or null)
+     * @param cipherSuites the array of ciphersuites (or null).  Note that the
+     * standard list of cipher suite names may be found in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation.  Providers
+     * may support cipher suite names not found in this list or might not
+     * use the recommended name for a certain cipher suite.
      */
     public void setCipherSuites(String[] cipherSuites) {
         this.cipherSuites = clone(cipherSuites);
--- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocket.java	Thu Aug 18 22:07:09 2016 +0300
+++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocket.java	Thu Aug 18 12:48:23 2016 -0700
@@ -195,6 +195,13 @@
      * or the requisite certificates (and private keys) for the suite are
      * not available, or an anonymous suite is enabled but authentication
      * is required.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return an array of cipher suites enabled
      * @see #getSupportedCipherSuites()
@@ -215,6 +222,14 @@
      * in this ServerSocket's authentication context will not be used
      * in any case, even if they are enabled.
      * <P>
+     * Note that the standard list of cipher suite names may be found in the
+     * <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation.  Providers
+     * may support cipher suite names not found in this list or might not
+     * use the recommended name for a certain cipher suite.
+     * <P>
      * <code>SSLSocket</code>s returned from <code>accept()</code>
      * inherit this setting.
      *
@@ -236,6 +251,13 @@
      * be enabled by default, since this list may include cipher suites which
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites are useful in specialized applications.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return an array of cipher suite names
      * @see #getEnabledCipherSuites()
--- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocketFactory.java	Thu Aug 18 22:07:09 2016 +0300
+++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLServerSocketFactory.java	Thu Aug 18 12:48:23 2016 -0700
@@ -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
@@ -123,6 +123,13 @@
      * will use one of these cipher suites.  The minimum quality of service
      * for these defaults requires confidentiality protection and server
      * authentication (that is, no anonymous cipher suites).
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @see #getSupportedCipherSuites()
      * @return array of the cipher suites enabled by default
@@ -137,6 +144,13 @@
      * be enabled by default, since this list may include cipher suites which
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites are useful in specialized applications.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return an array of cipher suite names
      * @see #getDefaultCipherSuites()
--- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java	Thu Aug 18 22:07:09 2016 +0300
+++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java	Thu Aug 18 12:48:23 2016 -0700
@@ -265,6 +265,13 @@
      * be enabled by default, since this list may include cipher suites which
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites might be useful in specialized applications.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return an array of cipher suite names
      * @see #getEnabledCipherSuites()
@@ -284,6 +291,13 @@
      * or the requisite certificates (and private keys) for the suite are
      * not available, or an anonymous suite is enabled but authentication
      * is required.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @return an array of cipher suite names
      * @see #getSupportedCipherSuites()
@@ -300,6 +314,14 @@
      * fail.  Following a successful call to this method, only suites
      * listed in the <code>suites</code> parameter are enabled for use.
      * <P>
+     * Note that the standard list of cipher suite names may be found in the
+     * <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation.  Providers
+     * may support cipher suite names not found in this list or might not
+     * use the recommended name for a certain cipher suite.
+     * <P>
      * See {@link #getEnabledCipherSuites()} for more information
      * on why a specific ciphersuite may never be used on a connection.
      *
--- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocketFactory.java	Thu Aug 18 22:07:09 2016 +0300
+++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocketFactory.java	Thu Aug 18 12:48:23 2016 -0700
@@ -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
@@ -148,6 +148,13 @@
      * will use one of these cipher suites.  The minimum quality of service
      * for these defaults requires confidentiality protection and server
      * authentication (that is, no anonymous cipher suites).
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @see #getSupportedCipherSuites()
      * @return array of the cipher suites enabled by default
@@ -160,6 +167,13 @@
      * be enabled by default, since this list may include cipher suites which
      * do not meet quality of service requirements for those defaults.  Such
      * cipher suites are useful in specialized applications.
+     * <P>
+     * The returned array includes cipher suites from the list of standard
+     * cipher suite names in the <a href=
+     * "{@docRoot}/../technotes/guides/security/StandardNames.html#ciphersuites">
+     * JSSE Cipher Suite Names</a> section of the Java Cryptography
+     * Architecture Standard Algorithm Name Documentation, and may also
+     * include other cipher suites that the provider supports.
      *
      * @see #getDefaultCipherSuites()
      * @return an array of cipher suite names