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

[Weijun Wang]

On Mon, 21 Oct 2024 18:21:37 GMT, Kevin Driver <kdriver at openjdk.org> wrote:

>> Introduce an API for Key Derivation Functions (KDFs), which are cryptographic algorithms for deriving additional keys from a secret key and other data. See [JEP 478](https://openjdk.org/jeps/478).
>> 
>> Work was begun in [another PR](https://github.com/openjdk/jdk/pull/18924).
>
> Kevin Driver has updated the pull request incrementally with one additional commit since the last revision:
> 
>   remove unused method

Several comments.

src/java.base/share/classes/javax/crypto/KDF.java line 224:

> 222:      * @throws NullPointerException
> 223:      *         if {@code algorithm} is {@code null}
> 224:      * @implNote The JDK Reference Implementation additionally uses the

I still recommend moving this `@implNote` right after the spec body text and before the 1st `@param`. Same with other `getInstance` methods and `engineDeriveKey` in `KDFSpi`.

src/java.base/share/classes/javax/crypto/KDF.java line 386:

> 384:      * @throws InvalidAlgorithmParameterException
> 385:      *         if the specified provider does not support a {@code KDF}
> 386:      *         implementation for the specified algorithm and parameters

Will it be clearer if we say `if the specified provider supports the specified {@code KDF} algorithm but does not support the provided parameters for that algorithm.`?

src/java.base/share/classes/javax/crypto/KDFSpi.java line 40:

> 38:  * All the abstract methods in this class must be implemented by each
> 39:  * cryptographic service provider who wishes to supply the implementation of a
> 40:  * particular key derivation algorithm.

Shall we say `key derivation function algorithm`?

src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java line 123:

> 121:          *         than 0)
> 122:          *
> 123:          * @return an {@code ExtractThenExpand} object

In `extractOnly`, you have `@return an immutable...`. Do you want to add the "immutable" word here also?

src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java line 336:

> 334:          * @return the unmodifiable {@code List} of salt values
> 335:          *
> 336:          * @implNote An HKDF implementation should concatenate the salt

Should this be `salt` or `salts`?

src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java line 415:

> 413: 
> 414:     /**
> 415:      * Defines the input parameters of an ExtractThenExpand operation as defined

In the class spec. the name of this operation is "Extract-then-Expand".

src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java line 477:

> 475:          * @return the unmodifiable {@code List} of salt values
> 476:          *
> 477:          * @implNote An HKDF implementation should concatenate the salt

Same comments. Shall we use `salt` or `salts`?

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

PR Review: https://git.openjdk.org/jdk/pull/20301#pullrequestreview-2399553428
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819382446
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819388314
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819401155
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819348634
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819351988
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819355456
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1819357743