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

[Alan Bateman]

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 47:

> 45:  * This class provides the functionality of a Key Derivation Function (KDF),
> 46:  * which is a cryptographic algorithm for deriving additional keys from input
> 47:  * keying material and (optionally) other data.

Do you want to say "key material" rather than "keying material" here?

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

> 51:  * <p>
> 52:  * The class has two derive methods, {@code deriveKey} and {@code deriveData}.
> 53:  * The {@code deriveKey} method accepts an algorithm {@code String} and

It might be clearer to say an algorithm name, or  algorithm name as a String.

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

> 94:  * deriveData methods. Therefore, it is recommended not to call the {@code
> 95:  * getProviderName} or {@code getParameters} methods until after a key
> 96:  * derivation operation. Once a provider is selected, it cannot be changed.

If I read this correctly, the first part of this paragraph is repeating the previous paragraph but with different wording, maybe the previous paragraph is left over from a previous iteration?

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

> 49:  * Implementations which do not support {@code KDFParameters} may require
> 50:  * {@code null} to be passed, otherwise an {@code InvalidAlgorithmParameterException}
> 51:  * may be thrown. On the other hand, implementations which require

I think you may need to clarify this paragraph for both provider implementations and anything that uses the concrete implementation. For a non-null kdfParameters that is not supported, the current wording seems to allow a provider to ignore parameters that it doesn't support, is that the intention?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1749288137
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1749288635
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1749289351
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1749287565