On Sat, 14 Sep 2024 22:39:18 GMT, Weijun Wang <wei...@openjdk.org> wrote:
>> Kevin Driver has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> refine wording on DPS getInstance with params exception
>
> src/java.base/share/classes/javax/crypto/KDF.java line 345:
>
>> 343: * if at least one {@code Provider} supports a {@code KDFSpi}
>> 344: * implementation for the specified algorithm but none of them
>> 345: * support the specified parameters
>
> One of the two `@throws` above uses `supports a {@code KDF} implementation`
> and the other uses `supports a {@code KDFSpi} implementation`. We'd better
> choose the same class name.
See:
https://github.com/openjdk/jdk/pull/20301/commits/ea5ba798819568ca86d639ba6c7a9489d4e66c95.
> src/java.base/share/classes/javax/crypto/KDF.java line 555:
>
>> 553:
>> 554: /**
>> 555: * Obtains raw data from a key derivation function.
>
> The first sentences of the two `derive` methods use different verbs:
> `Derives` and `Obtains`. Is it possible to use a same one?
See:
https://github.com/openjdk/jdk/pull/20301/commits/ea5ba798819568ca86d639ba6c7a9489d4e66c95.
> src/java.base/share/classes/javax/crypto/KDFSpi.java line 46:
>
>> 44: * super(params)} passing the parameters supplied. The constructor must
>> also
>> 45: * throw an {@code InvalidAlgorithmParameterException} if the supplied
>> 46: * parameters are inappropriate.
>
> I think it's worth saying explicitly that
>> If a `KDF` object is instantiated with one of the `getInstance` methods that
>> contains a `KDFParameters` parameter, the user-provided `KDFParameters`
>> object will be passed to the constructor of the `KDFSpi` implementation.
>> Otherwise, if it is instantiated with one of the `getInstance` methods
>> without a `KDFParameters` parameter, a `null` value will be passed to the
>> constructor.
>
> My words might be a little verbose, but I'd rather to precise and clear.
Added in
https://github.com/openjdk/jdk/pull/20301/commits/ea5ba798819568ca86d639ba6c7a9489d4e66c95.
> src/java.base/share/classes/javax/crypto/KDFSpi.java line 95:
>
>> 93: * If the required parameters were not supplied and can be generated
>> by
>> 94: * the {@code KDF} object, the generated parameters are returned;
>> 95: * otherwise {@code null} is returned.
>
> According to the class spec, when you say parameters are _required_ the
> caller must provide a non-null value. The sentence above contradicts with
> this.
This newer wording more clearly reflects the original intent of this passage:
https://github.com/openjdk/jdk/pull/20301/commits/ea5ba798819568ca86d639ba6c7a9489d4e66c95.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1761712651
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1761713555
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1761711178
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1761710899
