Module java.base
Package javax.crypto

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: 

   // Receiver side
   var kpg = KeyPairGenerator.getInstance("X25519");
   var kp = kpg.generateKeyPair();

   // Sender side
   var kem1 = KEM.getInstance("DHKEM");
   var sender = kem1.newEncapsulator(kp.getPublic());
   var encapsulated = sender.encapsulate();
   var k1 = encapsulated.key();

   // Receiver side
   var kem2 = KEM.getInstance("DHKEM");
   var receiver = kem2.newDecapsulator(kp.getPrivate());
   var k2 = receiver.decapsulate(encapsulated.encapsulation());

   assert Arrays.equals(k1.getEncoded(), k2.getEncoded());
Since:
21