Summary

Update the javadoc for javax.crypto.Cipher.getParameters() method to cover the cases below:

1. the returned parameters may be a combination of user-supplied parameter values and provider-specific default or random parameter values.
2. allow null to be returned when parameters is required but cannot be generated.

Problem

Existing javadoc of javax.crypto.Cipher.getParameters() method states that null is returned when the Cipher impl does not use parameters. This may not work well when a particular cipher algorithm requires parameters but the provider cannot generate default parameters. In addition, the javadoc also states that the returned parameter is either the user-specified parameters or provider-specific default/random parameters. However, for some cipher algorithms, callers may not supply all of the parameter values. The Cipher impl will take the supplied values and then generate the remaining with provider-specific defaults or random values. Existing javadoc should be clarified.

Solution

Update the javadoc to cover the combined parameters scenario and allow null to be returned when no parameters is generated. Same javadoc update is made to javax.crypto.CipherSpi.engineGetParameters() method.

Specification

1) Update of the javax.crypto.Cipher.getParameters() method javadoc:

@@ -1047,16 +1048,16 @@

     /**
      * Returns the parameters used with this cipher.
      *
      * <p>The returned parameters may be the same that were used to initialize
-     * this cipher, or may contain a combination of default and random
-     * parameter values used by the underlying cipher implementation if this
-     * cipher requires algorithm parameters but was not initialized with any.
+     * this cipher, or may contain additional default or random parameter
+     * values used by the underlying cipher implementation. If the required
+     * parameters were not supplied and can be generated by the cipher, the
+     * generated parameters are returned. Otherwise, {@code null} is returned.
      *
-     * @return the parameters used with this cipher, or null if this cipher
-     * does not use any parameters.
+     * @return the parameters used with this cipher, or {@code null}
      */
     public final AlgorithmParameters getParameters() {
         chooseFirstProvider();
         return spi.engineGetParameters();
     }

2) Update of the javax.crypto.CipherSpi.engineGetParameters() method javadoc:

@@ -286,16 +286,16 @@

     /**
      * Returns the parameters used with this cipher.
      *
      * <p>The returned parameters may be the same that were used to initialize
-     * this cipher, or may contain a combination of default and random
-     * parameter values used by the underlying cipher implementation if this
-     * cipher requires algorithm parameters but was not initialized with any.
+     * this cipher, or may contain additional default or random parameter
+     * values used by the underlying cipher implementation. If the required
+     * parameters were not supplied and can be generated by the cipher, the
+     * generated parameters are returned. Otherwise, {@code null} is returned.
      *
-     * @return the parameters used with this cipher, or null if this cipher
-     * does not use any parameters.
+     * @return the parameters used with this cipher, or {@code null}
      */
     protected abstract AlgorithmParameters engineGetParameters();