iaik.security.kem

Class KeyEncapsulationMechanismSpi

java.lang.Object

iaik.security.kem.KeyEncapsulationMechanismSpi

Direct Known Subclasses:

RsaKem

public abstract class KeyEncapsulationMechanismSpi
extends java.lang.Object

This class defines the Service Provider Interface (SPI) for the KeyEncapsulationMechanism (KEM) class. All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular KEM algorithm.

In order to create a KEM object, the application has to make a call to one of the KeyEncapsulationMechanism.getInstance(String) methods. DO NOT initiate such objects on their own.

The KeyEncapsulationMechanism class will instantiate the corresponding SPI class accordingly, depending on the requested algorithm.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.security.Key	key

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	KeyEncapsulationMechanismSpi() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract void	engineDecapsule(byte[] c, byte[] k) SPI: Uses the key encapsulation mechanism to decapsulate a session key k from the provided ciphertext c with the given private key.
protected abstract void	engineDeriveKey(byte[] output, java.util.List input) SPI: Derives the session key from the provided input.
protected abstract byte[]	engineEncapsule(byte[] k) SPI: Uses the key encapsulation mechanism to generate a new session key k.
protected abstract java.security.AlgorithmParameters	engineGetParameters() SPI: Gets the algorithm parameters required by this KEM engine.
protected abstract void	engineInit(java.security.Key key) Initializes this KEM with a key.
protected abstract void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec spec) Initializes this KEM with a key and a set of algorithm parameters.
protected abstract void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec spec, java.security.SecureRandom secureRandom) Initializes this KEM with a key, a set of algorithm parameters, and a secure source of randomness.
protected abstract void	engineInit(java.security.Key key, java.security.SecureRandom secureRandom) Initializes this KEM with a key and a secure source of randomness.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

key

protected java.security.Key key

Constructor Detail

KeyEncapsulationMechanismSpi

protected KeyEncapsulationMechanismSpi()

Default constructor.

Method Detail

engineInit

protected abstract void engineInit(java.security.Key key)
                            throws java.security.InvalidKeyException

Initializes this KEM with a key.

Implementations may decide which keys are applicable for their classes.

Parameters:

key - either a PublicKey or a PrivateKey depending on the wanted use-case.

Throws:

java.security.InvalidKeyException - if the given key is inappropriate for initializing this KEM, or requires algorithm parameters that cannot be determined from the given key,

engineInit

protected abstract void engineInit(java.security.Key key,
              java.security.SecureRandom secureRandom)
                            throws java.security.InvalidKeyException

Initializes this KEM with a key and a secure source of randomness.

Implementations may decide which keys are applicable for their classes. The implementation has to use the provided source of randomness for sampling random octets.

Parameters:

key - either a PublicKey or a PrivateKey depending on the wanted use-case.

secureRandom - a secure source of random

Throws:

java.security.InvalidKeyException - if the given key is inappropriate for initializing this KEM, or requires algorithm parameters that cannot be determined from the given key,

engineInit

protected abstract void engineInit(java.security.Key key,
              java.security.spec.AlgorithmParameterSpec spec)
                            throws java.security.InvalidKeyException,
                                   java.security.InvalidAlgorithmParameterException

Initializes this KEM with a key and a set of algorithm parameters.

Implementations may decide which keys and algorithm parameters are applicable for their classes.

Parameters:

key - either a PublicKey or a PrivateKey depending on the wanted use-case.

spec - a set of algorithm parameters able to initialize the KEM

Throws:

java.security.InvalidKeyException - if the given key is inappropriate for initializing this KEM, or requires algorithm parameters that cannot be determined from the given key,

java.security.InvalidAlgorithmParameterException - if the provided algorithm parameters are not capable of initializing the KEM

engineInit

protected abstract void engineInit(java.security.Key key,
              java.security.spec.AlgorithmParameterSpec spec,
              java.security.SecureRandom secureRandom)
                            throws java.security.InvalidKeyException,
                                   java.security.InvalidAlgorithmParameterException

Initializes this KEM with a key, a set of algorithm parameters, and a secure source of randomness.

Implementations may decide which keys and algorithm parameters are applicable for their classes. The implementation has to use the provided source of randomness for sampling random octets.

Parameters:

key - either a PublicKey or a PrivateKey depending on the wanted use-case.

spec - a set of algorithm parameters able to initialize the KEM

secureRandom - a secure source of random

Throws:

java.security.InvalidKeyException - if the given key is inappropriate for initializing this KEM, or requires algorithm parameters that cannot be determined from the given key,

java.security.InvalidAlgorithmParameterException - if the provided algorithm parameters are not capable of initializing the KEM

engineGetParameters

protected abstract java.security.AlgorithmParameters engineGetParameters()

SPI: Gets the algorithm parameters required by this KEM engine.

Returns:

the parameters used by this engine

engineDeriveKey

protected abstract void engineDeriveKey(byte[] output,
                   java.util.List input)
                                 throws java.security.DigestException

SPI: Derives the session key from the provided input.

Parameters:

input - the input to the key derivation function

Throws:

java.security.DigestException

engineEncapsule

protected abstract byte[] engineEncapsule(byte[] k)
                                   throws java.security.InvalidKeyException,
                                          java.security.DigestException

SPI: Uses the key encapsulation mechanism to generate a new session key k. The algorithm uses the provided public key to encapsulate the session key and returns the corresponding ciphertext. A subsequent call to engineDecapsule(byte[], byte[]) with the corresponding private key and the resulting ciphertext of this method will yield the session key.

The method will derive the random octets of the session key with the specified Key Derivation Function. Implementations may implement new classes for each Key Derivation Function or use more generic classes.

Parameters:

k - the destination of the session key k

Returns:

the ciphertext of the encapsulated key as byte array

Throws:

java.security.InvalidKeyException

java.security.DigestException

See Also:

engineDecapsule(byte[], byte[])

engineDecapsule

protected abstract void engineDecapsule(byte[] c,
                   byte[] k)
                                 throws java.security.InvalidKeyException,
                                        java.security.DigestException,
                                        java.security.InvalidParameterException

SPI: Uses the key encapsulation mechanism to decapsulate a session key k from the provided ciphertext c with the given private key.

This method should be used after another party called engineEncapsule(byte[]) with the public key associated with this private key. The method will regenerate the octets of the session key k depending on the specified Key Derivation Function.

Parameters:

c - the ciphertext of the encapsulated key as byte array

k - the destination of the session key k

Throws:

java.security.InvalidKeyException

java.security.DigestException

java.security.InvalidParameterException