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 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.
Since:
21

  • Nested Class Summary

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

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
    Creates and returns a copy of this object.
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Finalization is deprecated and subject to removal in a future release.
    final Class<?>
    getClass()
    Returns the runtime class of this Object.
    int
    hashCode()
    Returns a hash code value for this object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    String
    toString()
    Returns a string representation of the object.
    final void
    wait()
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
    final void
    wait(long timeoutMillis)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
    final void
    wait(long timeoutMillis, int nanos)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.