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 SummaryNested 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 SummaryModifier 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- 
getInstanceReturns aKEMobject that implements the specified algorithm.- Parameters:
- algorithm- the name of the KEM algorithm. See the- KEMsection in the Java Security Standard Algorithm Names Specification for information about standard KEM algorithm names.
- Returns:
- the new KEMobject
- Throws:
- NoSuchAlgorithmException- if no- Providersupports a- KEMimplementation for the specified algorithm
- NullPointerException- if- algorithmis- null
 
- 
getInstanceReturns aKEMobject that implements the specified algorithm from the specified security provider.- Parameters:
- algorithm- the name of the KEM algorithm. See the- KEMsection 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 KEMobject
- Throws:
- NoSuchAlgorithmException- if a- provideris specified and it does not support the specified KEM algorithm, or if- provideris- nulland there is no provider that supports a KEM implementation of the specified algorithm
- NullPointerException- if- algorithmis- null
 
- 
getInstancepublic 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 the- KEMsection 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 KEMobject
- Throws:
- NoSuchAlgorithmException- if a- provideris specified and it does not support the specified KEM algorithm, or if- provideris- nulland 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- algorithmis- null
 
- 
newEncapsulatorCreates 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- publicKeyis- nullor invalid
- UnsupportedOperationException- if this method is not supported because an- AlgorithmParameterSpecmust be provided
 
- 
newEncapsulatorpublic 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- publicKeyis- nullor invalid
- UnsupportedOperationException- if this method is not supported because an- AlgorithmParameterSpecmust be provided
 
- 
newEncapsulatorpublic 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 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- specis invalid or one is required but- specis- null
- InvalidKeyException- if- publicKeyis- nullor invalid
 
- 
newDecapsulatorCreates 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- privateKeyis- nullor invalid
- UnsupportedOperationException- if this method is not supported because an- AlgorithmParameterSpecmust be provided
 
- 
newDecapsulatorpublic 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- specis invalid or one is required but- specis- null
- InvalidKeyException- if- privateKeyis- nullor invalid
 
- 
getAlgorithmReturns the name of the algorithm for thisKEMobject.- Returns:
- the name of the algorithm for this KEMobject.
 
 
-