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

[Valerie Peng]

On Tue, 19 Apr 2022 02:20:10 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> src/java.base/share/classes/javax/crypto/Cipher.java line 1054:
>> 
>>> 1052:      * this cipher, or may contain additional default or random parameter
>>> 1053:      * values used by the underlying cipher implementation if this cipher can
>>> 1054:      * successfully generate the required parameter values when not supplied.
>> 
>> A few comments:
>> 
>> 1. I don't think this new text covers the case where the cipher is not initialized with any parameters, but the provider returns parameters. I tried to think of how to say that all in one sentence, but I think it is best to have two sentences covering each case, ex:
>> 
>> "If this cipher was not initialized with parameters, the returned parameters may be null or may be ..."
>> "If this cipher was initialized with parameters, the returned parameters may be the same or may be ..."
>> 
>> 2. Should `Signature.getParameters` be updated to be consistent? Are there any cases, or could there be, where a signature provider may return additional parameters other than what the user specified?
>
> Hmm, I tried the suggested approach in (1), the result looks very lengthy. Actually, the Cipher.init(..) methods already has a few paragraphs describing the behavior for parameter generation, perhaps we should not repeat stating the "If this cipher was initialized" vs "was not initialized" since lengthy description may confuse users and have higher risks of inconsistency. What do you think?
> As for (2), currently only RSASSA-PSS signature impl uses parameters. When specified using PSSParameterSpec, it's possible that some of the parameters are not set, so it's possible for providers to use provider-specific default values for PSS case. So, yes, Signature class may have to updated in the same way to cover this particular scenario.

For (1), how about something like below:

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

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

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