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

[Sean Mullan]

On Fri, 6 Sep 2024 18:45:42 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:
> 
>   updated comments around locking mechanism

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

> 52:  * The class has two derive methods, {@code deriveKey} and {@code deriveData}.
> 53:  * The {@code deriveKey} method accepts an algorithm {@code String} and
> 54:  * will return a {@code SecretKey} object with the specified algorithm. The

Keep wording consistent with next sentence ("returns a byte array").

s/will return/returns/

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

> 92:  * optional {@code KDFParameters} is chosen. This provider may not support
> 93:  * the key material that is subsequently passed to the deriveKey or
> 94:  * deriveData methods. Therefore, it is recommended not to call the {@code

Put @code around deriveKey and deriveData.

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

> 223:      *     if {@code algorithm} is {@code null}
> 224:      */
> 225:     public static KDF getInstance(String algorithm)

One thing that is missing from this method is an Implementation Note describing how the `jdk.security.provider.preferred` property affects the search algorithm. See any other JCE API - you can just copy/paste the text. Also affects the `getInstance` method that takes an algorithm and params.

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

> 347:                 Object obj = s.newInstance(kdfParameters);
> 348:                 if (!(obj instanceof KDFSpi spiObj)) {
> 349:                     lastException = new NoSuchAlgorithmException(

Unless I'm mistaken, you don't need to wrap the IAPE in a NSAE, only to unwrap it again in `handleException()`. I think you can throw it directly as an IAPE on line 379.

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

> 505:      * <p>
> 506:      * The {@code deriveKey} method may be called multiple times on a particular
> 507:      * {@code KDF} instance, but it is not considered thread-safe.

My preference would be to remove this sentence and the same one in deriveData now that you have the "Concurrent Access" section in the Class Summary which I think describes the concurrency behavior of the whole API better.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1752169245
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1752170033
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1752170158
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1752197908
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1752192026