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

[Sean Mullan]

On Thu, 1 Aug 2024 22:29:21 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> I disagree. I think this is a helpful bit of info for the developer who may be surprised later by an `Exception`.
>
> OK. As long as the exception does not cover it.

You should be careful putting the word "must" in an API specification - I think this would indicate that it is a condition that needs to be tested. And I think an HKDF implementation should throw an exception if the length is too high, right? I also think there is likely to cause confusion about what the HMAC length is and why the max is 255 * it. Also should it be hash length?

This could be a useful tip, but I also think there it is likely to inevitably prompt questions from users about what the HMAC length is for a given algorithm and why the max is 255 * that; in other words it requires some knowledge of the RFC and crypto. 

Suggest something like:

"the length of the output key material. The length must be > 0 and < 255 * hash length. For example, for the HKDFWithSHA256 algorithm, the hash length is ... so the maximum length is ... If less than 0, this method throws an IllegalArgumentException. If the length exceeds the maximum this method will not throw an exception because the hash algorithm is not known at this time. For example, for the HKDFWithSHA256 algorithm, the hash length is ... so the maximum length is ...  However an HKDF implementation of `KDF` will throw an `InvalidAlgorithmParameterException` when any of the `deriveKey` or `deriveObject` methods are called with a length that exceeds the maximum."

Also, there are other methods like `Builder.thenExpand` that take a length argument that do not contain this wording. They should be consistent.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1705665465