On Wed, 20 Apr 2022 16:40:34 GMT, Sean Mullan <mul...@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
