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 Encapsulator#providerName and 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	KEM.Decapsulator A decapsulator, generated by `newDecapsulator` on the KEM receiver side.
private static class	KEM.DelayedKEM
public static 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.
public static class	KEM.Encapsulator An encapsulator, generated by `newEncapsulator` on the KEM sender side.

Modifier and Type	Field and Description
private final String	algorithm
private final KEM.DelayedKEM	delayed
private final Provider	provider
private final KEMSpi	spi

Access	Constructor and Description
private	KEM(String algorithm, KEMSpi spi, Provider provider)
private	KEM(String algorithm, KEM.DelayedKEM delayed)

Method Summary

Modifier and Type	Method and Description
public String	Returns: the name of the algorithm for this `KEM` object. getAlgorithm() Returns the name of the algorithm for this `KEM` object.
public static KEM	Returns: the new `KEM` object getInstance(String 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. algorithm) Returns a `KEM` object that implements the specified algorithm.
public static KEM	Returns: the new `KEM` object getInstance(String 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. algorithm, Provider the provider. If `null`, this method is equivalent to `getInstance(String)`. provider) Returns a `KEM` object that implements the specified algorithm from the specified security provider.
public static KEM	Returns: the new `KEM` object getInstance(String 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. algorithm, String the provider. If `null`, this method is equivalent to `getInstance(String)`. provider) Returns a `KEM` object that implements the specified algorithm from the specified security provider.
public KEM.Decapsulator	Returns: the decapsulator for this key newDecapsulator(PrivateKey the receiver's private key, must not be `null` privateKey) Creates a KEM decapsulator on the KEM receiver side.
public KEM.Decapsulator	Returns: the decapsulator for this key newDecapsulator(PrivateKey the receiver's private key, must not be `null` privateKey, AlgorithmParameterSpec the parameter, can be `null` spec) Creates a KEM decapsulator on the KEM receiver side.
public KEM.Encapsulator	Returns: the encapsulator for this key newEncapsulator(PublicKey the receiver's public key, must not be `null` publicKey) Creates a KEM encapsulator on the KEM sender side.
public KEM.Encapsulator	Returns: the encapsulator for this key newEncapsulator(PublicKey the receiver's public key, must not be `null` publicKey, SecureRandom the source of randomness for encapsulation. If null, a default one from the implementation will be used. secureRandom) Creates a KEM encapsulator on the KEM sender side.
public KEM.Encapsulator	Returns: the encapsulator for this key newEncapsulator(PublicKey the receiver's public key, must not be `null` publicKey, AlgorithmParameterSpec the optional parameter, can be `null` spec, SecureRandom the source of randomness for encapsulation. If null, a default one from the implementation will be used. secureRandom) Creates a KEM encapsulator on the KEM sender side.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

algorithm	back to summary
private final String algorithm

delayed	back to summary
private final KEM.DelayedKEM delayed

provider	back to summary
private final Provider provider

spi	back to summary
private final KEMSpi spi

Constructor Detail

KEM	back to summary
private KEM(String algorithm, KEMSpi spi, Provider provider)

KEM	back to summary
private KEM(String algorithm, KEM.DelayedKEM delayed)

Method Detail

getAlgorithm back to summary

getAlgorithm	back to summary
public String getAlgorithm() Returns the name of the algorithm for this `KEM` object. Returns:String the name of the algorithm for this `KEM` object.

public String getAlgorithm()

Returns the name of the algorithm for this KEM object.

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

getInstance back to summary

getInstance	back to summary
public static KEM getInstance(String algorithm) throws NoSuchAlgorithmException Returns a `KEM` object that implements the specified algorithm. Parameters algorithm:String 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:KEM the new `KEM` object Exceptions NoSuchAlgorithmException: if no `Provider` supports a `KEM` implementation for the specified algorithm NullPointerException: if `algorithm` is `null` External Specification Java Security Standard Algorithm Names

public static KEM getInstance(String algorithm) throws NoSuchAlgorithmException

Returns a KEM object that implements the specified algorithm.

Parameters

algorithm:String: 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:KEM

the new KEM object

Exceptions

NoSuchAlgorithmException:: if no Provider supports a KEM implementation for the specified algorithm
NullPointerException:: if algorithm is null

External Specification

Java Security Standard Algorithm Names

getInstance back to summary

getInstance	back to summary
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:String 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:Provider the provider. If `null`, this method is equivalent to `getInstance(String)`. Returns:KEM the new `KEM` object Exceptions 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 Specification Java Security Standard Algorithm Names

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:String: 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:Provider: the provider. If null, this method is equivalent to getInstance(String).

Returns:KEM

the new KEM object

Exceptions

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 Specification

Java Security Standard Algorithm Names

getInstance back to summary

getInstance	back to summary
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:String 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:String the provider. If `null`, this method is equivalent to `getInstance(String)`. Returns:KEM the new `KEM` object Exceptions 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` External Specification Java Security Standard Algorithm Names

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:String: 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:String: the provider. If null, this method is equivalent to getInstance(String).

Returns:KEM

the new KEM object

Exceptions

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

External Specification

Java Security Standard Algorithm Names

newDecapsulator back to summary

newDecapsulator	back to summary
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:PrivateKey the receiver's private key, must not be `null` Returns:KEM.Decapsulator the decapsulator for this key Exceptions InvalidKeyException: if `privateKey` is `null` or invalid UnsupportedOperationException: if this method is not supported because an `AlgorithmParameterSpec` must be provided

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:PrivateKey: the receiver's private key, must not be null

Returns:KEM.Decapsulator

the decapsulator for this key

Exceptions

InvalidKeyException:: if privateKey is null or invalid
UnsupportedOperationException:: if this method is not supported because an AlgorithmParameterSpec must be provided

newDecapsulator back to summary

newDecapsulator	back to summary
public KEM.Decapsulator newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException Creates a KEM decapsulator on the KEM receiver side. Parameters privateKey:PrivateKey the receiver's private key, must not be `null` spec:AlgorithmParameterSpec the parameter, can be `null` Returns:KEM.Decapsulator the decapsulator for this key Exceptions InvalidAlgorithmParameterException: if `spec` is invalid or one is required but `spec` is `null` InvalidKeyException: if `privateKey` is `null` or invalid

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

Creates a KEM decapsulator on the KEM receiver side.

Parameters

privateKey:PrivateKey: the receiver's private key, must not be null
spec:AlgorithmParameterSpec: the parameter, can be null

Returns:KEM.Decapsulator

the decapsulator for this key

Exceptions

InvalidAlgorithmParameterException:: if spec is invalid or one is required but spec is null
InvalidKeyException:: if privateKey is null or invalid

newEncapsulator back to summary

newEncapsulator	back to summary
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:PublicKey the receiver's public key, must not be `null` Returns:KEM.Encapsulator the encapsulator for this key Exceptions InvalidKeyException: if `publicKey` is `null` or invalid UnsupportedOperationException: if this method is not supported because an `AlgorithmParameterSpec` must be provided

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:PublicKey: the receiver's public key, must not be null

Returns:KEM.Encapsulator

the encapsulator for this key

Exceptions

InvalidKeyException:: if publicKey is null or invalid
UnsupportedOperationException:: if this method is not supported because an AlgorithmParameterSpec must be provided

newEncapsulator back to summary

newEncapsulator	back to summary
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:PublicKey the receiver's public key, must not be `null` secureRandom:SecureRandom the source of randomness for encapsulation. If null, a default one from the implementation will be used. Returns:KEM.Encapsulator the encapsulator for this key Exceptions InvalidKeyException: if `publicKey` is `null` or invalid UnsupportedOperationException: if this method is not supported because an `AlgorithmParameterSpec` must be provided

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:PublicKey: the receiver's public key, must not be null
secureRandom:SecureRandom: the source of randomness for encapsulation. If null, a default one from the implementation will be used.

Returns:KEM.Encapsulator

the encapsulator for this key

Exceptions

InvalidKeyException:: if publicKey is null or invalid
UnsupportedOperationException:: if this method is not supported because an AlgorithmParameterSpec must be provided

newEncapsulator back to summary

newEncapsulator	back to summary
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 `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:PublicKey the receiver's public key, must not be `null` spec:AlgorithmParameterSpec the optional parameter, can be `null` secureRandom:SecureRandom the source of randomness for encapsulation. If null, a default one from the implementation will be used. Returns:KEM.Encapsulator the encapsulator for this key Exceptions InvalidAlgorithmParameterException: if `spec` is invalid or one is required but `spec` is `null` InvalidKeyException: if `publicKey` is `null` or invalid

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 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:PublicKey: the receiver's public key, must not be null
spec:AlgorithmParameterSpec: the optional parameter, can be null
secureRandom:SecureRandom: the source of randomness for encapsulation. If null, a default one from the implementation will be used.

Returns:KEM.Encapsulator

the encapsulator for this key

Exceptions

InvalidAlgorithmParameterException:: if spec is invalid or one is required but spec is null
InvalidKeyException:: if publicKey is null or invalid

javax.crypto back to summary

public final Class KEM.Decapsulator

Class Inheritance

extends Object

java.lang.Object
javax.crypto.KEM.Decapsulator

A decapsulator, generated by newDecapsulator on the KEM receiver side.

This class represents the key decapsulation function of a KEM. An invocation of the decapsulate method recovers the secret key from the key encapsulation message.

Since: 21

Field Summary

Modifier and Type	Field and Description
private final KEMSpi.DecapsulatorSpi	d
private final Provider	p

Constructor Summary

Access	Constructor and Description
private	Decapsulator(KEMSpi.DecapsulatorSpi d, Provider p)

Method Summary

Modifier and Type	Method and Description
public SecretKey	Returns: the shared secret as a `SecretKey` with an algorithm name of "Generic" decapsulate(byte[] the key encapsulation message from the sender. The size must be equal to the value returned by `encapsulationSize()`, or a `DecapsulateException` will be thrown. encapsulation) The key decapsulation function.
public SecretKey	Returns: a portion of the shared secret as a `SecretKey` containing the bytes of the secret ranging from `from` to `to`, exclusive, and an algorithm name as specified. For example, `decapsulate(encapsulation, secretSize() - 16, secretSize(), "AES")` uses the last 16 bytes of the shared secret as a 128-bit AES key. decapsulate(byte[] the key encapsulation message from the sender. The size must be equal to the value returned by `encapsulationSize()`, or a `DecapsulateException` will be thrown. encapsulation, int the initial index of the shared secret byte array to be returned, inclusive from, int the final index of the shared secret byte array to be returned, exclusive to, String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). algorithm) The key decapsulation function.
public int	Returns: the size of the key encapsulation message encapsulationSize() Returns the size of the key encapsulation message.
public String	Returns: the name of the provider providerName() Returns the name of the provider.
public int	Returns: the size of the shared secret secretSize() Returns the size of the shared secret.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

d	back to summary
private final KEMSpi.DecapsulatorSpi d

p	back to summary
private final Provider p

Constructor Detail

Decapsulator	back to summary
private Decapsulator(KEMSpi.DecapsulatorSpi d, Provider p)

Method Detail

decapsulate back to summary

decapsulate	back to summary
public SecretKey decapsulate(byte[] encapsulation) throws DecapsulateException The key decapsulation function. This method is equivalent to `decapsulate(encapsulation, 0, secretSize(), "Generic")`. This combination of arguments must be supported by every implementation. The generated secret key is usually passed to a key derivation function (KDF) as the input keying material. Parameters encapsulation:byte[] the key encapsulation message from the sender. The size must be equal to the value returned by `encapsulationSize()`, or a `DecapsulateException` will be thrown. Returns:SecretKey the shared secret as a `SecretKey` with an algorithm name of "Generic" Exceptions DecapsulateException: if an error occurs during the decapsulation process NullPointerException: if `encapsulation` is `null`

public SecretKey decapsulate(byte[] encapsulation) throws DecapsulateException

The key decapsulation function.

This method is equivalent to decapsulate(encapsulation, 0, secretSize(), "Generic"). This combination of arguments must be supported by every implementation.

The generated secret key is usually passed to a key derivation function (KDF) as the input keying material.

Parameters

encapsulation:byte[]: the key encapsulation message from the sender. The size must be equal to the value returned by encapsulationSize(), or a DecapsulateException will be thrown.

Returns:SecretKey

the shared secret as a SecretKey with an algorithm name of "Generic"

Exceptions

DecapsulateException:: if an error occurs during the decapsulation process
NullPointerException:: if encapsulation is null

decapsulate back to summary

decapsulate	back to summary
public SecretKey decapsulate(byte[] encapsulation, int from, int to, String algorithm) throws DecapsulateException The key decapsulation function. An invocation of this method recovers the secret key from the key encapsulation message. An implementation may choose to not support arbitrary combinations of `from`, `to`, and `algorithm`. Parameters encapsulation:byte[] the key encapsulation message from the sender. The size must be equal to the value returned by `encapsulationSize()`, or a `DecapsulateException` will be thrown. from:int the initial index of the shared secret byte array to be returned, inclusive to:int the final index of the shared secret byte array to be returned, exclusive algorithm:String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). Returns:SecretKey a portion of the shared secret as a `SecretKey` containing the bytes of the secret ranging from `from` to `to`, exclusive, and an algorithm name as specified. For example, `decapsulate(encapsulation, secretSize() - 16, secretSize(), "AES")` uses the last 16 bytes of the shared secret as a 128-bit AES key. Exceptions DecapsulateException: if an error occurs during the decapsulation process IndexOutOfBoundsException: if `from < 0`, `from > to`, or `to > secretSize()` NullPointerException: if `encapsulation` or `algorithm` is `null` UnsupportedOperationException: if the combination of `from`, `to`, and `algorithm` is not supported by the decapsulator External Specification Java Security Standard Algorithm Names

public SecretKey decapsulate(byte[] encapsulation, int from, int to, String algorithm) throws DecapsulateException

The key decapsulation function.

An invocation of this method recovers the secret key from the key encapsulation message.

An implementation may choose to not support arbitrary combinations of from, to, and algorithm.

Parameters

encapsulation:byte[]: the key encapsulation message from the sender. The size must be equal to the value returned by encapsulationSize(), or a DecapsulateException will be thrown.
from:int: the initial index of the shared secret byte array to be returned, inclusive
to:int: the final index of the shared secret byte array to be returned, exclusive
algorithm:String: the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF).

Returns:SecretKey

a portion of the shared secret as a SecretKey containing the bytes of the secret ranging from from to to, exclusive, and an algorithm name as specified. For example, decapsulate(encapsulation, secretSize() - 16, secretSize(), "AES") uses the last 16 bytes of the shared secret as a 128-bit AES key.

Exceptions

DecapsulateException:: if an error occurs during the decapsulation process
IndexOutOfBoundsException:: if from < 0, from > to, or to > secretSize()
NullPointerException:: if encapsulation or algorithm is null
UnsupportedOperationException:: if the combination of from, to, and algorithm is not supported by the decapsulator

External Specification

Java Security Standard Algorithm Names

encapsulationSize	back to summary
public int encapsulationSize() Returns the size of the key encapsulation message. This method can be used to extract the encapsulation message from a longer byte array if no length information is provided by a higher level protocol. Returns:int the size of the key encapsulation message

encapsulationSize

back to summary

public int encapsulationSize()

Returns the size of the key encapsulation message.

This method can be used to extract the encapsulation message from a longer byte array if no length information is provided by a higher level protocol.

Returns:int: the size of the key encapsulation message

providerName	back to summary
public String providerName() Returns the name of the provider. Returns:String the name of the provider

providerName

back to summary

public String providerName()

Returns the name of the provider.

Returns:String: the name of the provider

secretSize back to summary

secretSize	back to summary
public int secretSize() Returns the size of the shared secret. This method can be called to find out the length of the shared secret before `decapsulate` is called or if the obtained `SecretKey` is not extractable. Returns:int the size of the shared secret

public int secretSize()

Returns the size of the shared secret.

This method can be called to find out the length of the shared secret before decapsulate is called or if the obtained SecretKey is not extractable.

Returns:int: the size of the shared secret

Modifier and Type	Field and Description
private final Provider.Service[]	list

Access	Constructor and Description
private	DelayedKEM(Provider.Service[] list)

Modifier and Type	Method and Description
private static <T extends Exception> T	merge(T e1, T e2)
private KEM.Decapsulator	newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec)
private KEM.Encapsulator	newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom)

list	back to summary
private final Provider.Service[] list

DelayedKEM	back to summary
private DelayedKEM(Provider.Service[] list)

merge	back to summary
private static <T extends Exception> T merge(T e1, T e2)

newDecapsulator	back to summary
private KEM.Decapsulator newDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException

newEncapsulator	back to summary
private KEM.Encapsulator newEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) throws InvalidAlgorithmParameterException, InvalidKeyException

javax.crypto back to summary

public final Class KEM.Encapsulated

Class Inheritance

extends Object

java.lang.Object
javax.crypto.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.

Note

the key encapsulation message can be also referred to as ciphertext.

Since: 21
See Also: newEncapsulator(PublicKey, AlgorithmParameterSpec, SecureRandom), Encapsulator#encapsulate(int, int, String)

Field Summary

Modifier and Type	Field and Description
private final byte[]	encapsulation
private final SecretKey	key
private final byte[]	params

Constructor Summary

Access	Constructor and Description
public	Encapsulated(SecretKey the shared secret as a key, must not be `null`. key, byte[] the key encapsulation message, must not be `null`. The contents of the array are copied to protect against subsequent modification. encapsulation, byte[] optional parameters, can be `null`. The contents of the array are copied to protect against subsequent modification. params) Constructs an `Encapsulated` object.

Method Summary

Modifier and Type	Method and Description
public byte[]	Returns: the key encapsulation message. A new copy of the byte array is returned. encapsulation() Returns the key encapsulation message.
public SecretKey	Returns: the secret key key() Returns the `SecretKey`.
public byte[]	Returns: the optional parameters in a byte array or `null` if not specified. A new copy of the byte array is returned. params() Returns the optional parameters in a byte array.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

encapsulation	back to summary
private final byte[] encapsulation

key	back to summary
private final SecretKey key

params	back to summary
private final byte[] params

Constructor Detail

Encapsulated back to summary

Encapsulated	back to summary
public Encapsulated(SecretKey key, byte[] encapsulation, byte[] params) Constructs an `Encapsulated` object. Parameters key:SecretKey the shared secret as a key, must not be `null`. encapsulation:byte[] the key encapsulation message, must not be `null`. The contents of the array are copied to protect against subsequent modification. params:byte[] optional parameters, can be `null`. The contents of the array are copied to protect against subsequent modification. Exceptions NullPointerException: if `key` or `encapsulation` is `null`

public Encapsulated(SecretKey key, byte[] encapsulation, byte[] params)

Constructs an Encapsulated object.

Parameters

key:SecretKey: the shared secret as a key, must not be null.
encapsulation:byte[]: the key encapsulation message, must not be null. The contents of the array are copied to protect against subsequent modification.
params:byte[]: optional parameters, can be null. The contents of the array are copied to protect against subsequent modification.

Exceptions

NullPointerException:: if key or encapsulation is null

Method Detail

encapsulation	back to summary
public byte[] encapsulation() Returns the key encapsulation message. Returns:byte[] the key encapsulation message. A new copy of the byte array is returned.

encapsulation

back to summary

public byte[] encapsulation()

Returns the key encapsulation message.

Returns:byte[]: the key encapsulation message. A new copy of the byte array is returned.

key back to summary

key	back to summary
public SecretKey key() Returns the `SecretKey`. Returns:SecretKey the secret key

public SecretKey key()

Returns the SecretKey.

Returns:SecretKey: the secret key

params back to summary

params	back to summary
public byte[] params() Returns the optional parameters in a byte array. Returns:byte[] the optional parameters in a byte array or `null` if not specified. A new copy of the byte array is returned.

public byte[] params()

Returns the optional parameters in a byte array.

Returns:byte[]: the optional parameters in a byte array or null if not specified. A new copy of the byte array is returned.

javax.crypto back to summary

public final Class KEM.Encapsulator

Class Inheritance

extends Object

java.lang.Object
javax.crypto.KEM.Encapsulator

An encapsulator, generated by newEncapsulator on the KEM sender side.

This class represents the key encapsulation function of a KEM. Each invocation of the encapsulate method generates a new secret key and key encapsulation message that is returned in an Encapsulated object.

Since: 21

Field Summary

Modifier and Type	Field and Description
private final KEMSpi.EncapsulatorSpi	e
private final Provider	p

Constructor Summary

Access	Constructor and Description
private	Encapsulator(KEMSpi.EncapsulatorSpi e, Provider p)

Method Summary

Modifier and Type	Method and Description
public KEM.Encapsulated	Returns: a `Encapsulated` object containing the shared secret, key encapsulation message, and optional parameters. The shared secret is a `SecretKey` containing all of the bytes of the secret, and an algorithm name of "Generic". encapsulate() The key encapsulation function.
public KEM.Encapsulated	Returns: a `Encapsulated` object containing a portion of the shared secret, key encapsulation message, and optional parameters. The portion of the shared secret is a `SecretKey` containing the bytes of the secret ranging from `from` to `to`, exclusive, and an algorithm name as specified. For example, `encapsulate(0, 16, "AES")` uses the first 16 bytes of the shared secret as a 128-bit AES key. encapsulate(int the initial index of the shared secret byte array to be returned, inclusive from, int the final index of the shared secret byte array to be returned, exclusive to, String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). algorithm) The key encapsulation function.
public int	Returns: the size of the key encapsulation message encapsulationSize() Returns the size of the key encapsulation message.
public String	Returns: the name of the provider providerName() Returns the name of the provider.
public int	Returns: the size of the shared secret secretSize() Returns the size of the shared secret.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

e	back to summary
private final KEMSpi.EncapsulatorSpi e

p	back to summary
private final Provider p

Constructor Detail

Encapsulator	back to summary
private Encapsulator(KEMSpi.EncapsulatorSpi e, Provider p)

Method Detail

encapsulate back to summary

public KEM.Encapsulated encapsulate()

The key encapsulation function.

This method is equivalent to encapsulate(0, secretSize(), "Generic"). This combination of arguments must be supported by every implementation.

The generated secret key is usually passed to a key derivation function (KDF) as the input keying material.

Returns:KEM.Encapsulated: a Encapsulated object containing the shared secret, key encapsulation message, and optional parameters. The shared secret is a SecretKey containing all of the bytes of the secret, and an algorithm name of "Generic".

encapsulate back to summary

public KEM.Encapsulated encapsulate(int from, int to, String algorithm)

The key encapsulation function.

Each invocation of this method generates a new secret key and key encapsulation message that is returned in an Encapsulated object.

An implementation may choose to not support arbitrary combinations of from, to, and algorithm.

Parameters

from:int: the initial index of the shared secret byte array to be returned, inclusive
to:int: the final index of the shared secret byte array to be returned, exclusive
algorithm:String: the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF).

Returns:KEM.Encapsulated

a Encapsulated object containing a portion of the shared secret, key encapsulation message, and optional parameters. The portion of the shared secret is a SecretKey containing the bytes of the secret ranging from from to to, exclusive, and an algorithm name as specified. For example, encapsulate(0, 16, "AES") uses the first 16 bytes of the shared secret as a 128-bit AES key.

Exceptions

IndexOutOfBoundsException:: if from < 0, from > to, or to > secretSize()
NullPointerException:: if algorithm is null
UnsupportedOperationException:: if the combination of from, to, and algorithm is not supported by the encapsulator

External Specification

Java Security Standard Algorithm Names

encapsulationSize back to summary

public int encapsulationSize()

Returns the size of the key encapsulation message.

This method can be called to find out the length of the encapsulation message before encapsulate is called.

Returns:int: the size of the key encapsulation message

providerName

back to summary

public String providerName()

Returns the name of the provider.

Returns:String: the name of the provider

secretSize back to summary

public int secretSize()

Returns the size of the shared secret.

This method can be called to find out the length of the shared secret before encapsulate is called or if the obtained SecretKey is not extractable.

Returns:int: the size of the shared secret

public final Class KEM

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class KEM.Decapsulator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class KEM.DelayedKEM

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class KEM.Encapsulated

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class KEM.Encapsulator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail