Class KEM
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
Nested ClassesModifier and TypeClassDescriptionstatic final classA decapsulator, generated bynewDecapsulator(java.security.PrivateKey)on the KEM receiver side.static final classThis class specifies the return value of the encapsulate method of a Key Encapsulation Mechanism (KEM), which includes the shared secret (as aSecretKey), the key encapsulation message, and optional parameters.static final classAn encapsulator, generated bynewEncapsulator(java.security.PublicKey)on the KEM sender side. -
Method Summary
Modifier and TypeMethodDescriptionReturns the name of the algorithm for thisKEMobject.static KEMgetInstance(String algorithm) Returns aKEMobject that implements the specified algorithm.static KEMgetInstance(String algorithm, String provider) Returns aKEMobject that implements the specified algorithm from the specified security provider.static KEMgetInstance(String algorithm, Provider provider) Returns aKEMobject that implements the specified algorithm from the specified security provider.newDecapsulator(PrivateKey privateKey) Creates a KEM decapsulator on the KEM receiver side.newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) Creates a KEM decapsulator on the KEM receiver side.newEncapsulator(PublicKey publicKey) Creates a KEM encapsulator on the KEM sender side.newEncapsulator(PublicKey publicKey, SecureRandom secureRandom) Creates a KEM encapsulator on the KEM sender side.newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) Creates a KEM encapsulator on the KEM sender side.
-
Method Details
-
getInstance
Returns aKEMobject that implements the specified algorithm.- Parameters:
algorithm- the name of the KEM algorithm. See theKEMsection in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.- Returns:
- the new
KEMobject - Throws:
NoSuchAlgorithmException- if noProvidersupports aKEMimplementation for the specified algorithmNullPointerException- ifalgorithmisnull
-
getInstance
Returns aKEMobject that implements the specified algorithm from the specified security provider.- Parameters:
algorithm- the name of the KEM algorithm. See theKEMsection in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.provider- the provider. Ifnull, this method is equivalent togetInstance(String).- Returns:
- the new
KEMobject - Throws:
NoSuchAlgorithmException- if aprovideris specified and it does not support the specified KEM algorithm, or ifproviderisnulland there is no provider that supports a KEM implementation of the specified algorithmNullPointerException- ifalgorithmisnull
-
getInstance
public static KEM getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException Returns aKEMobject that implements the specified algorithm from the specified security provider.- Parameters:
algorithm- the name of the KEM algorithm. See theKEMsection in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.provider- the provider. Ifnull, this method is equivalent togetInstance(String).- Returns:
- the new
KEMobject - Throws:
NoSuchAlgorithmException- if aprovideris specified and it does not support the specified KEM algorithm, or ifproviderisnulland there is no provider that supports a KEM implementation of the specified algorithmNoSuchProviderException- if the specified provider is not registered in the security provider listNullPointerException- ifalgorithmisnull
-
newEncapsulator
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 benull- Returns:
- the encapsulator for this key
- Throws:
InvalidKeyException- ifpublicKeyisnullor invalidUnsupportedOperationException- if this method is not supported because anAlgorithmParameterSpecmust 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 benullsecureRandom- 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- ifpublicKeyisnullor invalidUnsupportedOperationException- if this method is not supported because anAlgorithmParameterSpecmust 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
AlgorithmParameterSpecchild 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 theKEM.Encapsulated.paramsfield inside the encapsulation output. In this case, the security provider should provide anAlgorithmParametersimplementation using the same algorithm name as the KEM. The receiver can initiate such anAlgorithmParametersinstance with theparamsbyte array received and recover anAlgorithmParameterSpecobject to be used in itsnewDecapsulator(PrivateKey, AlgorithmParameterSpec)call.- Parameters:
publicKey- the receiver's public key, must not benullspec- the optional parameter, can benullsecureRandom- 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- ifspecis invalid or one is required butspecisnullInvalidKeyException- ifpublicKeyisnullor invalid
-
newDecapsulator
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 benull- Returns:
- the decapsulator for this key
- Throws:
InvalidKeyException- ifprivateKeyisnullor invalidUnsupportedOperationException- if this method is not supported because anAlgorithmParameterSpecmust 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 benullspec- the parameter, can benull- Returns:
- the decapsulator for this key
- Throws:
InvalidAlgorithmParameterException- ifspecis invalid or one is required butspecisnullInvalidKeyException- ifprivateKeyisnullor invalid
-
getAlgorithm
Returns the name of the algorithm for thisKEMobject.- Returns:
- the name of the algorithm for this
KEMobject.
-