Module java.base
Package javax.crypto

# Interface KEMSpi

public interface KEMSpi
This class defines the Service Provider Interface (SPI) for the `KEM` class. A security provider implements this interface to provide an implementation of a Key Encapsulation Mechanism (KEM) algorithm.

A KEM algorithm may support a family of configurations. Each configuration may accept different types of keys, cryptographic primitives, and sizes of shared secrets and key encapsulation messages. A configuration is defined by the KEM algorithm name, the key it uses, and an optional `AlgorithmParameterSpec` argument that is specified when creating an encapsulator or decapsulator. The result of calling `engineNewEncapsulator(java.security.PublicKey, java.security.spec.AlgorithmParameterSpec, java.security.SecureRandom)` or `engineNewDecapsulator(java.security.PrivateKey, java.security.spec.AlgorithmParameterSpec)` must return an encapsulator or decapsulator that maps to a single configuration, where its `engineSecretSize()` and `engineEncapsulationSize()` methods return constant values.

A `KEMSpi` implementation must be immutable. It must be safe to call multiple `engineNewEncapsulator` and `engineNewDecapsulator` methods at the same time.

`EncapsulatorSpi` and `DecapsulatorSpi` implementations must also be immutable. It must be safe to invoke multiple `encapsulate` and `decapsulate` methods at the same time. Each invocation of `encapsulate` should generate a new shared secret and key encapsulation message.

For example,

    public static class MyKEMImpl implements KEMSpi {

        @Override
        public KEMSpi.EncapsulatorSpi engineNewEncapsulator(PublicKey publicKey,
                AlgorithmParameterSpec spec, SecureRandom secureRandom)
                throws InvalidAlgorithmParameterException, InvalidKeyException {
            if (!checkPublicKey(publicKey)) {
                throw new InvalidKeyException("unsupported key");
            }
            if (!checkParameters(spec)) {
                throw new InvalidAlgorithmParameterException("unsupported params");
            }
            return new MyEncapsulator(publicKey, spec, secureRandom);
        }

        class MyEncapsulator implements KEMSpi.EncapsulatorSpi {
            MyEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec,
                    SecureRandom secureRandom){
                this.spec = spec != null ? spec : getDefaultParameters();
                this.secureRandom = secureRandom != null
                        ? secureRandom
                        : getDefaultSecureRandom();
                this.publicKey = publicKey;
            }

            @Override
            public KEM.Encapsulated encapsulate(int from, int to, String algorithm) {
                byte[] encapsulation;
                byte[] secret;
                // calculating...
                return new KEM.Encapsulated(
                        new SecretKeySpec(secret, from, to - from, algorithm),
                        encapsulation, null);
            }

            // ...
        }

        // ...
    }

Since:
  21
See Also:
  - `KEM`

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static interface`
`KEMSpi.DecapsulatorSpi`
The KEM decapsulator implementation, generated by `engineNewDecapsulator(java.security.PrivateKey, java.security.spec.AlgorithmParameterSpec)` on the KEM receiver side.
`static interface`
`KEMSpi.EncapsulatorSpi`
The KEM encapsulator implementation, generated by `engineNewEncapsulator(java.security.PublicKey, java.security.spec.AlgorithmParameterSpec, java.security.SecureRandom)` on the KEM sender side.

## Method Summary

Modifier and Type
Method
Description
`KEMSpi.DecapsulatorSpi`
`engineNewDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec)`
Creates a KEM decapsulator on the KEM receiver side.
`KEMSpi.EncapsulatorSpi`
`engineNewEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom)`
Creates a KEM encapsulator on the KEM sender side.

## Method Details

### engineNewEncapsulator

KEMSpi.EncapsulatorSpi engineNewEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) throws InvalidAlgorithmParameterException, InvalidKeyException
Creates a KEM encapsulator on the KEM sender side.

Parameters:
  `publicKey` - the receiver's public key, must not be `null`
  `spec` - the optional parameter, can be `null`
  `secureRandom` - the source of randomness for encapsulation. If `null`, the implementation must provide a default one.
Returns:
  the encapsulator for this key
Throws:
  `InvalidAlgorithmParameterException` - if `spec` is invalid or one is required but `spec` is `null`
  `InvalidKeyException` - if `publicKey` is `null` or invalid
See Also:
  - `KEM.newEncapsulator(PublicKey, AlgorithmParameterSpec, SecureRandom)`

### engineNewDecapsulator

KEMSpi.DecapsulatorSpi engineNewDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException
Creates a KEM decapsulator on the KEM receiver side.

Parameters:
  `privateKey` - the receiver's private key, must not be `null`
  `spec` - the optional parameter, can be `null`
Returns:
  the decapsulator for this key
Throws:
  `InvalidAlgorithmParameterException` - if `spec` is invalid or one is required but `spec` is `null`
  `InvalidKeyException` - if `privateKey` is `null` or invalid
See Also:
  - `KEM.newDecapsulator(PrivateKey, AlgorithmParameterSpec)`