W3cubDocs

/OpenJDK 21

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

Nested Class Summary

Modifier and Type Class Description
static final class  KEM.Decapsulator
A decapsulator, generated by newDecapsulator(java.security.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(java.security.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 java.lang.Object

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

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

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

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:
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
NoSuchProviderException - if the specified provider is not registered in the security provider list
NullPointerException - if algorithm is null

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 in the KEM.Encapsulated.params field inside 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, 2023, 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.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/KEM.html