Module java.base
Package javax.crypto

# Interface KEMSpi.DecapsulatorSpi

Enclosing interface:
  KEMSpi

public static interface KEMSpi.DecapsulatorSpi
The KEM decapsulator implementation, generated by `KEMSpi.engineNewDecapsulator(java.security.PrivateKey, java.security.spec.AlgorithmParameterSpec)` on the KEM receiver side.

API Note:
  This interface is defined in Java SE 17 Maintenance Release 1.
Since:
  17
See Also:
  - `KEM.Decapsulator`

## Method Summary

Modifier and Type
Method
Description
`SecretKey`
`engineDecapsulate(byte[] encapsulation, int from, int to, String algorithm)`
The key decapsulation function.
`int`
`engineEncapsulationSize()`
Returns the size of the key encapsulation message.
`int`
`engineSecretSize()`
Returns the size of the shared secret.

## Method Details

### engineDecapsulate

SecretKey engineDecapsulate(byte[] encapsulation, int from, int to, String algorithm) throws DecapsulateException
The key decapsulation function.

An invocation of this method recovers the secret key from the key encapsulation message.

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:
  `encapsulation` - the key encapsulation message from the sender. The size must be equal to the value returned by `engineEncapsulationSize()` ()}, or a `DecapsulateException` must be thrown.
  `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 portion of the shared secret as a `SecretKey` with the specified algorithm
Throws:
  `DecapsulateException` - if an error occurs during the decapsulation process
  `IndexOutOfBoundsException` - if `from < 0`, `from > to`, or `to > secretSize()`
  `NullPointerException` - if `encapsulation` or `algorithm` is `null`
  `UnsupportedOperationException` - if the combination of `from`, `to`, and `algorithm` is not supported by the decapsulator
See Also:
  - `KEM.Decapsulator.decapsulate(byte[], 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.Decapsulator.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.Decapsulator.encapsulationSize()`