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

[Valerie Peng]

On Wed, 20 Apr 2022 16:40:34 GMT, Sean Mullan <mullan at openjdk.org> wrote:

>>> 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? 
>> 
>> That's a good point, the `init` methods do go into a lot of detail about that.
>> 
>>> 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.
>> 
>> Ok, I think we should try to make the spec consistent across `Cipher` and `Signature` once we settle on the right wording. I think it would be better to do it as part of this issue, but I would be ok doing it later as long as it is also fixed in 19.
>
>> 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.
>  
> I like this first sentence.
> 
>> > If no parameters
>> >  * is supplied and this cipher successfully generated the required
>> >  * parameter values, it will be returned. 
> 
> What does "successfully" mean? If it wasn't successful, what happens? Maybe we should avoid that word. How about:
> 
> "If parameters were not supplied and this cipher requires parameters, the returned parameters will contain the parameter values generated by the underlying cipher implementation."
> 
>> > Otherwise, {@code null} is
>> >  * returned.
>> > ```

> > 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?
> 
> That's a good point, the `init` methods do go into a lot of detail about that.
> 
> > 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.
> 
> Ok, I think we should try to make the spec consistent across `Cipher` and `Signature` once we settle on the right wording. I think it would be better to do it as part of this issue, but I would be ok doing it later as long as it is also fixed in 19.

I can do the Signature update through https://bugs.openjdk.java.net/browse/JDK-8253176 which I have targeted to fix in 19 also.

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

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