Module java.base
Package javax.crypto

# Class KEM.Encapsulator

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

Enclosing class:
  `KEM`

public static final class KEM.Encapsulator extends Object
An encapsulator, generated by `KEM.newEncapsulator(java.security.PublicKey)` 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 `KEM.Encapsulated` object.

Since:
  21

- ## Method Summary

  Modifier and Type
  Method
  Description
  `KEM.Encapsulated`
  `encapsulate()`
  The key encapsulation function.
  `KEM.Encapsulated`
  `encapsulate(int from, int to, String algorithm)`
  The key encapsulation function.
  `int`
  `encapsulationSize()`
  Returns the size of the key encapsulation message.
  `String`
  `providerName()`
  Returns the name of the provider.
  `int`
  `secretSize()`
  Returns the size of the shared secret.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### providerName

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

  - ### encapsulate

    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:
      a `KEM.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

    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 `KEM.Encapsulated` object.

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

    Parameters:
      `from` - the initial index of the shared secret byte array to be returned, inclusive
      `to` - the final index of the shared secret byte array to be returned, exclusive
      `algorithm` - the algorithm name for the secret key that is returned
    Returns:
      a `KEM.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.
    Throws:
      `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

  - ### secretSize

    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:
      the size of the shared secret

  - ### encapsulationSize

    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:
      the size of the key encapsulation message