RFR: 8331008: Implement JEP 478: Key Derivation Function API (Preview) [v36]

[Kevin Driver]

On Sat, 14 Sep 2024 22:39:18 GMT, Weijun Wang <weijun at 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