On Fri, 31 Mar 2023 02:25:04 GMT, Weijun Wang <wei...@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
