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

[Weijun Wang]

On Mon, 13 May 2024 23:11:45 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).
>
> Kevin Driver has updated the pull request incrementally with one additional commit since the last revision:
> 
>   javadoc improvements

Some more comments on HKDF.

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

> 106:         }
> 107: 
> 108:         /**

The method spec should start with a paragraph saying "Adds key input material (IKM) to this builder", and then a new paragraph can talk about "AddIKM may be called....".

Also, the "may be called when..." sounds like there is another `setIKM` method when the IKM can be provided in a single shot. We should be very clear that this is the only method. We can probably say something like this:

This method can be invoked multiple times on a builder, appending each newly added IKM to the existing IKM. This is particularly useful for "labeled" HKDF Extract used in TLS 1.3 and HPKE, where the IKM consists of concatenated components, which may include both byte arrays and (possibly non-extractable) secret keys.

This applies to the 3 methods below as well.

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

> 230: 
> 231:     /**
> 232:      * Static helper-method that may be used to initialize an {@code Expand}

This is the only method to create a params set for the `Expand-Only` mode.

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

> 234:      *
> 235:      * @param prk
> 236:      *     the pseudorandom key

What's the requirement of `prk`. Although we might not be able to check in this method, it should be non-null and at least the length of HashLen.

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

> 238:      *     the optional context and application specific information
> 239:      * @param length
> 240:      *     the length of the output key material (must be > 0)

Same as `prk`. Although we cannot check here, the length has an upper limit. If you want to precise, say that a too long key will be rejected by an implementation.

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

> 256: 
> 257:     /**
> 258:      * Defines the input parameters of an Extract operation as defined in <a

We should be very clear this is for the "Extract-Only" mode.

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

> 276: 
> 277:         /**
> 278:          * Returns an unmodifiable {@code List} of initial key material

`s/initial/input/g`

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

> 277:         /**
> 278:          * Returns an unmodifiable {@code List} of initial key material
> 279:          * values.

Add a sentence like "an implementation should concatenate the input key materials into a single byte array and supply it into the HKDF-Extract as defined in section n.n of RFC xxxx". Same for `salts`.

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

PR Review: https://git.openjdk.org/jdk/pull/18924#pullrequestreview-2055350332
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600025746
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600084147
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600088605
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600090666
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600079386
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600070737
PR Review Comment: https://git.openjdk.org/jdk/pull/18924#discussion_r1600072500