Class KEM

java.lang.Object

javax.crypto.KEM

public final class KEM extends Object

This class provides the functionality of a Key Encapsulation Mechanism (KEM). A KEM can be used to secure symmetric keys using asymmetric or public key cryptography between two parties. The sender calls the encapsulate method to generate a secret key and a key encapsulation message, and the receiver calls the decapsulate method to recover the same secret key from the key encapsulation message.

The getInstance method creates a new KEM object that implements the specified algorithm.

A KEM object is immutable. It is safe to call multiple newEncapsulator and newDecapsulator methods on the same KEM object at the same time.

If a provider is not specified in the getInstance method when instantiating a KEM object, the newEncapsulator and newDecapsulator methods may return encapsulators or decapsulators from different providers. The provider selected is based on the parameters passed to the newEncapsulator or newDecapsulator methods: the private or public key and the optional AlgorithmParameterSpec. The KEM.Encapsulator.providerName() and KEM.Decapsulator.providerName() methods return the name of the selected provider.

Encapsulator and Decapsulator objects are also immutable. It is safe to invoke multiple encapsulate and decapsulate methods on the same Encapsulator or Decapsulator object at the same time. Each invocation of encapsulate will generate a new shared secret and key encapsulation message.

Example operation using a fictitious KEM algorithm ABC:

    // Receiver side
    KeyPairGenerator g = KeyPairGenerator.getInstance("ABC");
    KeyPair kp = g.generateKeyPair();
    publishKey(kp.getPublic());

    // Sender side
    KEM senderKEM = KEM.getInstance("ABC");
    PublicKey receiverPublicKey = retrieveKey();
    ABCKEMParameterSpec senderSpec = new ABCKEMParameterSpec(args);
    KEM.Encapsulator e = senderKEM.newEncapsulator(
            receiverPublicKey, senderSpec, null);
    KEM.Encapsulated enc = e.encapsulate();
    SecretKey senderSecret = enc.key();

    sendBytes(enc.encapsulation());
    sendBytes(enc.params());

    // Receiver side
    byte[] ciphertext = receiveBytes();
    byte[] params = receiveBytes();

    KEM receiverKEM = KEM.getInstance("ABC");
    AlgorithmParameters algParams =
            AlgorithmParameters.getInstance("ABC");
    algParams.init(params);
    ABCKEMParameterSpec receiverSpec =
            algParams.getParameterSpec(ABCKEMParameterSpec.class);
    KEM.Decapsulator d =
            receiverKEM.newDecapsulator(kp.getPrivate(), receiverSpec);
    SecretKey receiverSecret = d.decapsulate(ciphertext);

    // senderSecret and receiverSecret should now be equal.

Since:: 21

Nested Class Summary

Modifier and Type	Class	Description
`static final class`	`KEM.Decapsulator`	A decapsulator, generated by `newDecapsulator(PrivateKey)` on the KEM receiver side.
`static final class`	`KEM.Encapsulated`	This class specifies the return value of the encapsulate method of a Key Encapsulation Mechanism (KEM), which includes the shared secret (as a `SecretKey`), the key encapsulation message, and optional parameters.
`static final class`	`KEM.Encapsulator`	An encapsulator, generated by `newEncapsulator(PublicKey)` on the KEM sender side.

Method Summary

Modifier and Type	Method	Description
`String`	`getAlgorithm()`	Returns the name of the algorithm for this `KEM` object.
`static KEM`	`getInstance(String algorithm)`	Returns a `KEM` object that implements the specified algorithm.
`static KEM`	`getInstance(String algorithm, String provider)`	Returns a `KEM` object that implements the specified algorithm from the specified security provider.
`static KEM`	`getInstance(String algorithm, Provider provider)`	Returns a `KEM` object that implements the specified algorithm from the specified security provider.
`KEM.Decapsulator`	`newDecapsulator(PrivateKey privateKey)`	Creates a KEM decapsulator on the KEM receiver side.
`KEM.Decapsulator`	`newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec)`	Creates a KEM decapsulator on the KEM receiver side.
`KEM.Encapsulator`	`newEncapsulator(PublicKey publicKey)`	Creates a KEM encapsulator on the KEM sender side.
`KEM.Encapsulator`	`newEncapsulator(PublicKey publicKey, SecureRandom secureRandom)`	Creates a KEM encapsulator on the KEM sender side.
`KEM.Encapsulator`	`newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom)`	Creates a KEM encapsulator on the KEM sender side.

Methods declared in class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Modifier and Type	Method	Description
`protected Object`	`clone()`	Creates and returns a copy of this object.
`boolean`	`equals(Object obj)`	Indicates whether some other object is "equal to" this one.
`protected void`	`finalize()`	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
`final Class<?>`	`getClass()`	Returns the runtime class of this `Object`.
`int`	`hashCode()`	Returns a hash code value for this object.
`final void`	`notify()`	Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()`	Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()`	Returns a string representation of the object.
`final void`	`wait()`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`	`wait(long timeoutMillis)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis, int nanos)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Method Details

getInstance

public static KEM getInstance(String algorithm) throws NoSuchAlgorithmException

Returns a KEM object that implements the specified algorithm.

Parameters:

algorithm - the name of the KEM algorithm. See the KEM section in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.

Returns:

the new KEM object

Throws:

NoSuchAlgorithmException - if no Provider supports a KEM implementation for the specified algorithm

NullPointerException - if algorithm is null

External Specifications

getInstance

public static KEM getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException

Returns a KEM object that implements the specified algorithm from the specified security provider.

Parameters:

algorithm - the name of the KEM algorithm. See the KEM section in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.

provider - the provider. If null, this method is equivalent to getInstance(String).

Returns:

the new KEM object

Throws:

NoSuchAlgorithmException - if a provider is specified and it does not support the specified KEM algorithm, or if provider is null and there is no provider that supports a KEM implementation of the specified algorithm

NullPointerException - if algorithm is null

External Specifications

getInstance

public static KEM getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Returns a KEM object that implements the specified algorithm from the specified security provider.

Parameters:

algorithm - the name of the KEM algorithm. See the KEM section in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.

provider - the provider. If null, this method is equivalent to getInstance(String).

Returns:

the new KEM object

Throws:

NoSuchProviderException - if the specified provider is not registered in the security provider list

NullPointerException - if algorithm is null

External Specifications

newEncapsulator

public KEM.Encapsulator newEncapsulator(PublicKey publicKey) throws InvalidKeyException

Creates a KEM encapsulator on the KEM sender side.

This method is equivalent to newEncapsulator(publicKey, null, null).

Parameters:: publicKey - the receiver's public key, must not be null
Returns:: the encapsulator for this key
Throws:: InvalidKeyException - if publicKey is null or invalid; UnsupportedOperationException - if this method is not supported because an AlgorithmParameterSpec must be provided

newEncapsulator

public KEM.Encapsulator newEncapsulator(PublicKey publicKey, SecureRandom secureRandom) throws InvalidKeyException

Creates a KEM encapsulator on the KEM sender side.

This method is equivalent to newEncapsulator(publicKey, null, secureRandom).

Parameters:: publicKey - the receiver's public key, must not be null; secureRandom - the source of randomness for encapsulation. If null, a default one from the implementation will be used.
Returns:: the encapsulator for this key
Throws:: InvalidKeyException - if publicKey is null or invalid; UnsupportedOperationException - if this method is not supported because an AlgorithmParameterSpec must be provided

newEncapsulator

public KEM.Encapsulator newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) throws InvalidAlgorithmParameterException, InvalidKeyException

Creates a KEM encapsulator on the KEM sender side.

An algorithm can define an AlgorithmParameterSpec child class to provide extra information in this method. This is especially useful if the same key can be used to derive shared secrets in different ways. If any extra information inside this object needs to be transmitted along with the key encapsulation message so that the receiver is able to create a matching decapsulator, it will be included as a byte array returned by the KEM.Encapsulated.params() method within the encapsulation output. In this case, the security provider should provide an AlgorithmParameters implementation using the same algorithm name as the KEM. The receiver can initiate such an AlgorithmParameters instance with the params byte array received and recover an AlgorithmParameterSpec object to be used in its newDecapsulator(PrivateKey, AlgorithmParameterSpec) call.

Parameters:: publicKey - the receiver's public key, must not be null; spec - the optional parameter, can be null; secureRandom - the source of randomness for encapsulation. If null, a default one from the implementation will be used.
Returns:: the encapsulator for this key
Throws:: InvalidAlgorithmParameterException - if spec is invalid or one is required but spec is null; InvalidKeyException - if publicKey is null or invalid

newDecapsulator

public KEM.Decapsulator newDecapsulator(PrivateKey privateKey) throws InvalidKeyException

Creates a KEM decapsulator on the KEM receiver side.

This method is equivalent to newDecapsulator(privateKey, null).

Parameters:: privateKey - the receiver's private key, must not be null
Returns:: the decapsulator for this key
Throws:: InvalidKeyException - if privateKey is null or invalid; UnsupportedOperationException - if this method is not supported because an AlgorithmParameterSpec must be provided

newDecapsulator

public KEM.Decapsulator newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException

Creates a KEM decapsulator on the KEM receiver side.

Parameters:: privateKey - the receiver's private key, must not be null; spec - the parameter, can be null
Returns:: the decapsulator for this key
Throws:: InvalidAlgorithmParameterException - if spec is invalid or one is required but spec is null; InvalidKeyException - if privateKey is null or invalid

getAlgorithm

public String getAlgorithm()

Returns the name of the algorithm for this KEM object.

Returns:: the name of the algorithm for this KEM object.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.