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)`