W3cubDocs

/OpenJDK 21

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:

Nested Class Summary

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

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:

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:

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/KEMSpi.html