RFR: 8297878: KEM: Implementation

[Sean Mullan]

On Fri, 31 Mar 2023 02:25:04 GMT, Weijun Wang <weijun at openjdk.org> wrote:

> The KEM API and DHKEM impl. Note that this PR uses new methods in https://github.com/openjdk/jdk/pull/13250.

src/java.base/share/classes/javax/crypto/KEM.java line 36:

> 34: 
> 35: /**
> 36:  * The Key Encapsulation Mechanism.

How about a bit more here: "This class provides the functionality of a Key Encapsulation Mechanism (KEM). A KEM can be used to encrypt symmetric keys using asymmetric or public key cryptography."

src/java.base/share/classes/javax/crypto/KEM.java line 49:

> 47:  * or public key, and the optional {@code AlgorithmParameterSpec} object,
> 48:  * the {@code newEncapsulator} or {@code newDecapsulator} method
> 49:  * may return encapsulators or decapsulators from different providers. The user

This sentence is kind of long. Suggest breaking it up, ex: "If a provider is not specified in the {@code getInstance} method when  instantiating a {@code KEM} object,  the {@code newEncapsulator} and {@code newDecapsulator} method may return encapsulators or decapsulators from different providers. The provider selected is based on the parameters passed to the the {@code newEncapsulator} or {@code newDecapsulator} methods: the private or public key and the optional {@code AlgorithmParameterSpec}."

src/java.base/share/classes/javax/crypto/KEM.java line 50:

> 48:  * the {@code newEncapsulator} or {@code newDecapsulator} method
> 49:  * may return encapsulators or decapsulators from different providers. The user
> 50:  * can call the {@link Encapsulator#provider} or {@link Decapsulator#provider}

I would avoid referring to "The user". Suggest: "The {@link Encapsulator#provider} and {@link Decapsulator#provider} methods return the selected provider."

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1165787134
PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1165798901
PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1165800833