# HG changeset patch
# User mullan
# Date 1541105634 14400
# Node ID 7b20c27b2ccb25a9b9717c0e3472c66e47997b97
# Parent  5ea020bcaa0d3287df0be17aef65845cf069d1e2
8212669: Add note to Cipher javadoc about using full transformation and not relying on defaults
Reviewed-by: xuelei

diff -r 5ea020bcaa0d -r 7b20c27b2ccb src/java.base/share/classes/javax/crypto/Cipher.java
--- a/src/java.base/share/classes/javax/crypto/Cipher.java	Thu Nov 01 17:56:01 2018 +0100
+++ b/src/java.base/share/classes/javax/crypto/Cipher.java	Thu Nov 01 16:53:54 2018 -0400
@@ -492,6 +492,12 @@
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @apiNote
+     * It is recommended to use a transformation that fully specifies the
+     * algorithm, mode, and padding. By not doing so, the provider will
+     * use a default for the mode and padding which may not meet the security
+     * requirements of your application.
+     *
      * @implNote
      * The JDK Reference Implementation additionally uses the
      * {@code jdk.security.provider.preferred}
@@ -499,6 +505,9 @@
      * the preferred provider order for the specified algorithm. This
      * may be different than the order of providers returned by
      * {@link Security#getProviders() Security.getProviders()}.
+     * See also the Cipher Transformations section of the {@extLink
+     * security_guide_jdk_providers JDK Providers} document for information
+     * on the transformation defaults used by JDK providers.
      *
      * @param transformation the name of the transformation, e.g.,
      * <i>AES/CBC/PKCS5Padding</i>.
@@ -578,6 +587,17 @@
      * <p> Note that the list of registered providers may be retrieved via
      * the {@link Security#getProviders() Security.getProviders()} method.
      *
+     * @apiNote
+     * It is recommended to use a transformation that fully specifies the
+     * algorithm, mode, and padding. By not doing so, the provider will
+     * use a default for the mode and padding which may not meet the security
+     * requirements of your application.
+     *
+     * @implNote
+     * See the Cipher Transformations section of the {@extLink
+     * security_guide_jdk_providers JDK Providers} document for information
+     * on the transformation defaults used by JDK providers.
+     *
      * @param transformation the name of the transformation,
      * e.g., <i>AES/CBC/PKCS5Padding</i>.
      * See the Cipher section in the <a href=
@@ -638,6 +658,17 @@
      * object is returned.  Note that the specified Provider object
      * does not have to be registered in the provider list.
      *
+     * @apiNote
+     * It is recommended to use a transformation that fully specifies the
+     * algorithm, mode, and padding. By not doing so, the provider will
+     * use a default for the mode and padding which may not meet the security
+     * requirements of your application.
+     *
+     * @implNote
+     * See the Cipher Transformations section of the {@extLink
+     * security_guide_jdk_providers JDK Providers} document for information
+     * on the transformation defaults used by JDK providers.
+     *
      * @param transformation the name of the transformation,
      * e.g., <i>AES/CBC/PKCS5Padding</i>.
      * See the Cipher section in the <a href=