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/KEMSpi.java line 37:

> 35:  * This class defines the Service Provider Interface (SPI)
> 36:  * for the {@link KEM} class. A security provider implements this interface
> 37:  * to implement a KEM algorithm.

Suggest defining what KEM stands for. Also, a few wording suggestions:

"A security provider implements this interface to provide an implementation of a Key Encapsulation Mechanism (KEM) algorithm."

src/java.base/share/classes/javax/crypto/KEMSpi.java line 39:

> 37:  * to implement a KEM algorithm.
> 38:  * <p>
> 39:  * A KEM algorithm may contain a family of configurations.

Would "support" instead of "contain" be better?

src/java.base/share/classes/javax/crypto/KEMSpi.java line 42:

> 40:  * Different configurations accept different types of keys, uses different
> 41:  * underlying cryptographic primitives, and supports different sizes of shared
> 42:  * secrets and key encapsulation messages. A configuration must be decided

Wording suggestions: "Each configuration may accept different types of keys, cryptographic primitives, and sizes of shared secrets and key encapsulation messages."

src/java.base/share/classes/javax/crypto/KEMSpi.java line 45:

> 43:  * by the KEM algorithm name, the key it uses, and an optional
> 44:  * {@code AlgorithmParameterSpec} argument when creating an encapsulator or
> 45:  * decapsulator. The result of either {@link #engineNewDecapsulator} or

How about: "A configuration is defined by the ..." and "... argument that is specified when ..."

"The result of calling {@link #engineNewDecapsulator} or .."

src/java.base/share/classes/javax/crypto/KEMSpi.java line 52:

> 50:  * A {@code KEMSpi} implementation should be immutable. It should be safe to
> 51:  * call multiple {@code engineNewEncapsulator} and {@code engineNewDecapsulator}
> 52:  * methods at the same time.

I would make these "should" requirements a "must", otherwise you cannot guarantee it when testing for API compliance. Same comment for the EncapsulatorSpi and DecapsulatorSpi below.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1164235638
PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1164243774
PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1164241949
PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1164249995
PR Review Comment: https://git.openjdk.org/jdk/pull/13256#discussion_r1164251531