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 or engineNewDecapsulator 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);
        }

        // ...
    }

    // ...
}

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	KEMSpi.DecapsulatorSpi The KEM decapsulator implementation, generated by `engineNewDecapsulator` on the KEM receiver side.
public static interface	KEMSpi.EncapsulatorSpi The KEM encapsulator implementation, generated by `engineNewEncapsulator` on the KEM sender side.

Method Summary

Modifier and Type	Method and Description
public KEMSpi.DecapsulatorSpi	Returns: the decapsulator for this key engineNewDecapsulator(PrivateKey the receiver's private key, must not be `null` privateKey, AlgorithmParameterSpec the optional parameter, can be `null` spec) Creates a KEM decapsulator on the KEM receiver side.
public KEMSpi.EncapsulatorSpi	Returns: the encapsulator for this key engineNewEncapsulator(PublicKey the receiver's public key, must not be `null` publicKey, AlgorithmParameterSpec the optional parameter, can be `null` spec, SecureRandom the source of randomness for encapsulation. If `null`, the implementation must provide a default one. secureRandom) Creates a KEM encapsulator on the KEM sender side.

Method Detail

engineNewDecapsulator back to summary

engineNewDecapsulator	back to summary
public KEMSpi.DecapsulatorSpi engineNewDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException Creates a KEM decapsulator on the KEM receiver side. Parameters privateKey:PrivateKey the receiver's private key, must not be `null` spec:AlgorithmParameterSpec the optional parameter, can be `null` Returns:KEMSpi.DecapsulatorSpi the decapsulator for this key Exceptions 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)`

public KEMSpi.DecapsulatorSpi engineNewDecapsulator(PrivateKey privateKey, AlgorithmParameterSpec spec) throws InvalidAlgorithmParameterException, InvalidKeyException

Creates a KEM decapsulator on the KEM receiver side.

Parameters

privateKey:PrivateKey: the receiver's private key, must not be null
spec:AlgorithmParameterSpec: the optional parameter, can be null

Returns:KEMSpi.DecapsulatorSpi

the decapsulator for this key

Exceptions

InvalidAlgorithmParameterException:: if spec is invalid or one is required but spec is null
InvalidKeyException:: if privateKey is null or invalid

engineNewEncapsulator back to summary

engineNewEncapsulator	back to summary
public KEMSpi.EncapsulatorSpi engineNewEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) throws InvalidAlgorithmParameterException, InvalidKeyException Creates a KEM encapsulator on the KEM sender side. Parameters publicKey:PublicKey the receiver's public key, must not be `null` spec:AlgorithmParameterSpec the optional parameter, can be `null` secureRandom:SecureRandom the source of randomness for encapsulation. If `null`, the implementation must provide a default one. Returns:KEMSpi.EncapsulatorSpi the encapsulator for this key Exceptions 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)`

public KEMSpi.EncapsulatorSpi engineNewEncapsulator(PublicKey publicKey, AlgorithmParameterSpec spec, SecureRandom secureRandom) throws InvalidAlgorithmParameterException, InvalidKeyException

Creates a KEM encapsulator on the KEM sender side.

Parameters

publicKey:PublicKey: the receiver's public key, must not be null
spec:AlgorithmParameterSpec: the optional parameter, can be null
secureRandom:SecureRandom: the source of randomness for encapsulation. If null, the implementation must provide a default one.

Returns:KEMSpi.EncapsulatorSpi

the encapsulator for this key

Exceptions

InvalidAlgorithmParameterException:: if spec is invalid or one is required but spec is null
InvalidKeyException:: if publicKey is null or invalid

javax.crypto back to summary

public Interface KEMSpi.DecapsulatorSpi

Known Direct Implementers: com.sun.crypto.provider.DHKEM.Handler, sun.security.provider.NamedKEM.KeyConsumerImpl, sun.security.ssl.DHasKEM.Handler, sun.security.ssl.Hybrid.Handler

The KEM decapsulator implementation, generated by engineNewDecapsulator on the KEM receiver side.

Since: 21
See Also: KEM.Decapsulator

Method Summary

Modifier and Type	Method and Description
public SecretKey	Returns: a portion of the shared secret as a `SecretKey` with the specified algorithm engineDecapsulate(byte[] the key encapsulation message from the sender. The size must be equal to the value returned by `engineEncapsulationSize()` ()}, or a `DecapsulateException` must be thrown. encapsulation, int the initial index of the shared secret byte array to be returned, inclusive from, int the final index of the shared secret byte array to be returned, exclusive to, String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). algorithm) The key decapsulation function.
public int	Returns: the size of the key encapsulation message as a finite non-negative integer engineEncapsulationSize() Returns the size of the key encapsulation message.
public int	Returns: the size of the shared secret as a finite non-negative integer engineSecretSize() Returns the size of the shared secret.

Method Detail

engineDecapsulate back to summary

engineDecapsulate	back to summary
public 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:byte[] 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:int the initial index of the shared secret byte array to be returned, inclusive to:int the final index of the shared secret byte array to be returned, exclusive algorithm:String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). Returns:SecretKey a portion of the shared secret as a `SecretKey` with the specified algorithm Exceptions 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 External Specification Java Security Standard Algorithm Names See Also `KEM.Decapsulator#decapsulate(byte[], int, int, String)`

public 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:byte[]: 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:int: the initial index of the shared secret byte array to be returned, inclusive
to:int: the final index of the shared secret byte array to be returned, exclusive
algorithm:String: the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF).

Returns:SecretKey

a portion of the shared secret as a SecretKey with the specified algorithm

Exceptions

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

External Specification

Java Security Standard Algorithm Names

engineEncapsulationSize back to summary

engineEncapsulationSize	back to summary
public int engineEncapsulationSize() Returns the size of the key encapsulation message. Returns:int the size of the key encapsulation message as a finite non-negative integer See Also `KEM.Decapsulator#encapsulationSize()`

public int engineEncapsulationSize()

Returns the size of the key encapsulation message.

Returns:int: the size of the key encapsulation message as a finite non-negative integer
See Also: KEM.Decapsulator#encapsulationSize()

engineSecretSize back to summary

engineSecretSize	back to summary
public int engineSecretSize() Returns the size of the shared secret. Returns:int the size of the shared secret as a finite non-negative integer See Also `KEM.Decapsulator#secretSize()`

public int engineSecretSize()

Returns the size of the shared secret.

Returns:int: the size of the shared secret as a finite non-negative integer
See Also: KEM.Decapsulator#secretSize()

javax.crypto back to summary

public Interface KEMSpi.EncapsulatorSpi

Known Direct Implementers: com.sun.crypto.provider.DHKEM.Handler, sun.security.provider.NamedKEM.KeyConsumerImpl, sun.security.ssl.DHasKEM.Handler, sun.security.ssl.Hybrid.Handler

The KEM encapsulator implementation, generated by engineNewEncapsulator on the KEM sender side.

Since: 21
See Also: KEM.Encapsulator

Method Summary

Modifier and Type	Method and Description
public KEM.Encapsulated	Returns: an `KEM.Encapsulated` object containing a portion of the shared secret as a key with the specified algorithm, key encapsulation message, and optional parameters. engineEncapsulate(int the initial index of the shared secret byte array to be returned, inclusive from, int the final index of the shared secret byte array to be returned, exclusive to, String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). algorithm) The key encapsulation function.
public int	Returns: the size of the key encapsulation message as a finite non-negative integer engineEncapsulationSize() Returns the size of the key encapsulation message.
public int	Returns: the size of the shared secret as a finite non-negative integer engineSecretSize() Returns the size of the shared secret.

Method Detail

engineEncapsulate back to summary

engineEncapsulate	back to summary
public KEM.Encapsulated engineEncapsulate(int from, int to, String algorithm) The key encapsulation function. Each invocation of this method must generate a new secret key and key encapsulation message that is returned in an `KEM.Encapsulated` object. 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 from:int the initial index of the shared secret byte array to be returned, inclusive to:int the final index of the shared secret byte array to be returned, exclusive algorithm:String the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF). Returns:KEM.Encapsulated an `KEM.Encapsulated` object containing a portion of the shared secret as a key with the specified algorithm, key encapsulation message, and optional parameters. Exceptions 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 External Specification Java Security Standard Algorithm Names See Also `KEM.Encapsulated`, `KEM.Encapsulator#encapsulate(int, int, String)`

public KEM.Encapsulated engineEncapsulate(int from, int to, String algorithm)

The key encapsulation function.

Each invocation of this method must generate a new secret key and key encapsulation message that is returned in an KEM.Encapsulated object.

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

from:int: the initial index of the shared secret byte array to be returned, inclusive
to:int: the final index of the shared secret byte array to be returned, exclusive
algorithm:String: the algorithm name for the secret key that is returned. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF).

Returns:KEM.Encapsulated

an KEM.Encapsulated object containing a portion of the shared secret as a key with the specified algorithm, key encapsulation message, and optional parameters.

Exceptions

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

External Specification

Java Security Standard Algorithm Names

engineEncapsulationSize back to summary

engineEncapsulationSize	back to summary
public int engineEncapsulationSize() Returns the size of the key encapsulation message. Returns:int the size of the key encapsulation message as a finite non-negative integer See Also `KEM.Encapsulator#encapsulationSize()`

public int engineEncapsulationSize()

Returns the size of the key encapsulation message.

Returns:int: the size of the key encapsulation message as a finite non-negative integer
See Also: KEM.Encapsulator#encapsulationSize()

engineSecretSize back to summary

engineSecretSize	back to summary
public int engineSecretSize() Returns the size of the shared secret. Returns:int the size of the shared secret as a finite non-negative integer See Also `KEM.Encapsulator#secretSize()`

public int engineSecretSize()

Returns the size of the shared secret.

Returns:int: the size of the shared secret as a finite non-negative integer
See Also: KEM.Encapsulator#secretSize()