RFR: 8331008: KDF Implementation

[Sean Mullan]

On Tue, 23 Apr 2024 20:42:51 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).

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

> 41: 
> 42: /**
> 43:  * This class provides the functionality of a key derivation algorithm for the Java Cryptographic

We don't normally say "for the Java Cryptographic Extension framework" in our other APIs, so I would remove that part. Also, can you try to keep lines to around 80 characters - it helps with code reviews.

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

> 42: /**
> 43:  * This class provides the functionality of a key derivation algorithm for the Java Cryptographic
> 44:  * Extension (JCE) framework.

A sentence or two after this explaining what a KDF is and the methods that derive a key would be useful. See the KEM API for an example.

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

> 44:  * Extension (JCE) framework.
> 45:  * <p>
> 46:  * {@code KeyDerivation} objects will be instantiated through the {@code getInstance} family of

s/KeyDerivation/KDF/
s/will be/are/

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

> 45:  * <p>
> 46:  * {@code KeyDerivation} objects will be instantiated through the {@code getInstance} family of
> 47:  * methods.  Key derivation algorithm names will follow a naming convention of

remove "will".

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

> 46:  * {@code KeyDerivation} objects will be instantiated through the {@code getInstance} family of
> 47:  * methods.  Key derivation algorithm names will follow a naming convention of
> 48:  * <I>algorithm</I>/<I>PRF</I>.  The algorithm field will be the KDF name

s/will be/is/
s/name/algorithm/

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

> 52:  * the algorithm specifier may be omitted if the KDF algorithm has a fixed or default PRF.
> 53:  * <p>
> 54:  * TODO: finish this javadoc

You should state that a KDF object is immutable. A sample would also be useful.

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

> 87: 
> 88:     /**
> 89:      * Instantiates a KeyDerivation object.

s/KeyDerivation/KDF/

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

> 98:      *     the algorithm parameters
> 99:      */
> 100:     protected KDF(KDFSpi keyDerivSpi, Provider provider, String algorithm,

This class is final, so a protected constructor is not necessary. You should be able to make this private.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595373890
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595380447
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595374621
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595375376
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595375707
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595379864
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595383806
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1595389524