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.

API Note:
  This class is defined in Java SE 17 Maintenance Release 1.
Since:
  17

## 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