# Interface KEMSpi.EncapsulatorSpi

Enclosing interface:
  `KEMSpi`

public static interface KEMSpi.EncapsulatorSpi
The KEM encapsulator implementation, generated by `KEMSpi.engineNewEncapsulator(PublicKey, AlgorithmParameterSpec, SecureRandom)` on the KEM sender side.

Since:
  21
See Also:
  - `KEM.Encapsulator`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `KEM.Encapsulated`
  `engineEncapsulate(int from, int to, String algorithm)`
  The key encapsulation function.
  `int`
  `engineEncapsulationSize()`
  Returns the size of the key encapsulation message.
  `int`
  `engineSecretSize()`
  Returns the size of the shared secret.

- ## Method Details

  - ### engineEncapsulate

    KEM.Encapsulated engineEncapsulate(int from, int to, String algorithm)
    The key encapsulation function.

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

    An implementation must support the case where `from` is 0, `to` is the same as the return value of `secretSize()`, and `algorithm` is "Generic".

    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. 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:
      an `KEM.Encapsulated` object containing a portion of the shared secret as a key with the specified algorithm, key encapsulation message, and optional parameters.
    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
    External Specifications
      - Java Security Standard Algorithm Names
    See Also:
      - `KEM.Encapsulated`
      - `KEM.Encapsulator.encapsulate(int, int, String)`

  - ### engineSecretSize

    int engineSecretSize()
    Returns the size of the shared secret.
    Returns:
      the size of the shared secret as a finite non-negative integer
    See Also:
      - `KEM.Encapsulator.secretSize()`

  - ### engineEncapsulationSize

    int engineEncapsulationSize()
    Returns the size of the key encapsulation message.
    Returns:
      the size of the key encapsulation message as a finite non-negative integer
    See Also:
      - `KEM.Encapsulator.encapsulationSize()`