RFR: 8209038: Clarify the javadoc of Cipher.getParameters()

[Valerie Peng]

On Wed, 6 Apr 2022 19:41:28 GMT, Xue-Lei Andrew Fan <xuelei at openjdk.org> wrote:

>> Can you be more specific like which block of code that you are referring to as the filtering and modification?
>> I'd expect the intention is to use the parameter specified. Otherwise an exception should be thrown if the specified parameter is invalid. Only when no parameter is specified, the provider would try to generate the parameters using whatever values it has or got.
>
> I read the following methods in com.sun.crypto.provider.CipherCore:
> 
>     void init(int opmode, Key key, AlgorithmParameterSpec params,
>             SecureRandom random)
> 
> where the 'params' are converted to IV byte array for further processing. 
> 
> 
>     void init(int opmode, Key key, AlgorithmParameters params,
>               SecureRandom random)
> 
> where the spec is retrieved from the 'params', and then pass the call to the init() method above.
> 
> 
>     AlgorithmParameters getParameters(String algName) {
> 
> where the returned parameters are re-constructed.
> 
> It may be fine to use a strict spec, but there is a chance to have compatibility impact unless we check the implementation carefully.  It may not worthy the risks as a behavioral update may be not necessary for developers.

How about this then?

     * <p>The returned parameters may be the same that were used to initialize
     * this cipher, or may contain additional default and random parameter
     * values used by the underlying cipher implementation if this
     * cipher can successfully generate the required parameter values when
     * not supplied. Otherwise, {@code null} is returned.

-------------

PR: https://git.openjdk.java.net/jdk/pull/8117