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
--- 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