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()
    Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
    boolean
    equals(Object o)
    Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    May cause performance issues, deadlocks and hangs.
    final Class<? extends Object>
    getClass()
    Answers the unique instance of java.lang.Class which represents the class of the receiver.
    int
    hashCode()
    Answers an integer hash code for the receiver.
    final void
    notify()
    Causes one thread which is waiting on the receiver to be made ready to run.
    final void
    notifyAll()
    Causes all threads which are waiting on the receiver to be made ready to run.
    String
    toString()
    Answers a string containing a concise, human-readable description of the receiver.
    final void
    wait()
    Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by notify or notifyAll).
    final void
    wait(long time)
    Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.
    final void
    wait(long time, int frac)
    Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.