iaik.security.kem

Class KeyEncapsulationMechanism

java.lang.Object

iaik.security.kem.KeyEncapsulationMechanism

public class KeyEncapsulationMechanism
extends java.lang.Object

JCA compliant engine that provides the functionality of a Key Encapsulation Mechanism (KEM).

A KEM usually incorporates an already existing Public-Key-Encryption (PKE) scheme to exchange secrets between a sender and a receiver. Most commonly, the sender and the receiver use the secret as symmetric key. A KEM scheme consists of the following three operations:

1. key-gen
2. encapusle
3. decapsule

This class provides an interface for Service Providers to enable the encapusle and decapsule methods for such schemes. As one usually uses already existing PKEs, the corresponding KeyPairGenerator implements the corresponding key-generation (e.g., for the RSA-KEM, use an appropriate generator class, which allows the creation of large enough RSA-keys).

The encapusle method outputs a ciphertext c and a session key k. The ciphertext is a valid ciphertext from the underlying PKE and the session key k is a stream of octets.

The decapsule method takes the ciphertext c obtained from encapusle and outputs either a session key k or an error symbol (which is not k) on failure. This method must be deterministic.

Internally, the algorithm samples a random element m, using a secure source of randomness with negligible bias, from the message space of the PKE. The encapusle method then proceeds by encrypting the random element m, which yields the ciphertext c. Furthermore, the KEM derives the session key k by using m as input for a key-derivation function (KDF), like KDF2. Every strong enough KDF may be used to derive k.

In order to create a KEM object, the application has to make a call to one of the getInstance(String) methods. This class will instantiate the corresponding engine class accordingly, depending on the requested function, e.g.:

 KeyEncapsulationMechanism kem =
           KeyEncapsulationMechanism.getInstance("RsaKem", "IAIK");
 

The caller would get an instance of this class, which holds the engine class of the RSA-KEM implementation. Similar to the Cipher classes, the caller has to initialize the KEM with either a PublicKey or a PrivateKey. The provided key will determine the used parameter set and the mode of operation. Don't reuse the class, because this results in undefined behaviour.

Using the example of the RSA-KEM with KDF-3, and an existing RSA keypair (rsaPub, rsaPriv) usage may look like this:

 KeyEncapsulationMechanism kemEncap =
           KeyEncapsulationMechanism.getInstance("RsaKem", "IAIK");
 final int sessionKeyLength = ...;
 RsaKemAlgorithmParameterSpec kemSpec = new RsaKemAlgorithmParameterSpec(
                      new KDF3ParameterSpec(AlgorithmID.sha256, sessionKeyLength));

 kem.init(rsaPub, kemSpec);
 byte[] sessionKeyEncap = new byte[sessionKeyLength];
 byte[] cipher = rsaKem.encapsulate(sessionKeyEncap);
 byte[] sessionKeyDecap = new byte[sessionKeyEncap.length];

 KeyEncapsulationMechanism kemDecap =
           KeyEncapsulationMechanism.getInstance("RsaKem", "IAIK");
 kem.init(rsaPriv, kemSpec);
 byte[] sessionKeyDecap = new byte[sessionKeyLength];
 rsaKem.decapsule(cipher, sessionKeyDecap);
 

If the above code finishes, the contents of sessionKeyDecap and sessionKeyEncap are the same.

Version:

File Revision 17 //TODO What Revision

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	KeyEncapsulationMechanism(KeyEncapsulationMechanismSpi engine, java.security.Provider provider, java.lang.String kemAlgorithm) Internal constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	decapsule(byte[] c, byte[] k) The decapsule method of the KEM.
byte[]	encapsule(byte[] k) The encapusle method of the KEM.
java.lang.String	getAlgorithm() Returns the algorithm name of this KEM object.
static KeyEncapsulationMechanism	getInstance(java.lang.String kem) Creates a Key Encapsulation Mechanism engine depending on the provided String.
static KeyEncapsulationMechanism	getInstance(java.lang.String kem, java.security.Provider provider) Creates a provider-specific Key Encapsulation Mechanism engine for the given kem.
static KeyEncapsulationMechanism	getInstance(java.lang.String kem, java.lang.String providerName) Creates a provider-specific Key Encapsulation Mechanism engine for the given kem.
java.security.AlgorithmParameters	getParameters() Returns the parameters used by this KEM.
java.security.Provider	getProvider() Returns the provider of this KEM object.
void	init(java.security.Key key) Initializes this KEM with a key.
void	init(java.security.Key key, java.security.spec.AlgorithmParameterSpec algorithmParameterSpec) Initializes this KEM with a key and a set of algorithm parameters.
void	init(java.security.Key key, java.security.spec.AlgorithmParameterSpec algorithmParameterSpec, java.security.SecureRandom secureRandom) Initializes this KEM with a key, a set of algorithm parameters, and a secure source of random.
void	init(java.security.Key key, java.security.SecureRandom random) Initializes this KEM with a key and a secure source of randomness.
java.lang.String	toString() Returns a string representation of the KEM in the form of:

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyEncapsulationMechanism

protected KeyEncapsulationMechanism(KeyEncapsulationMechanismSpi engine,
                         java.security.Provider provider,
                         java.lang.String kemAlgorithm)

Internal constructor. Applications shall not call this constructor. If you want to instantiate a KeyEncapsulationMechanism, make a call to getInstance(String).

Parameters:

engine - the spi implementation

provider - the used provider

kemAlgorithm - the KEM algorithm as string

Method Detail

getInstance

public static KeyEncapsulationMechanism getInstance(java.lang.String kem)
                                             throws java.security.NoSuchAlgorithmException

Creates a Key Encapsulation Mechanism engine depending on the provided String.

Parameters:

kem - the kem for which an engine should be created

Throws:

java.security.NoSuchAlgorithmException - if no implementation for the requested algorithm is available

getInstance

public static KeyEncapsulationMechanism getInstance(java.lang.String kem,
                                    java.lang.String providerName)
                                             throws java.security.NoSuchAlgorithmException,
                                                    java.security.NoSuchProviderException

Creates a provider-specific Key Encapsulation Mechanism engine for the given kem.

Parameters:

kem - the kem kem for which an engine should be created

providerName - the name of the provider whose KEM implementation is requested

Throws:

java.security.NoSuchAlgorithmException - if no implementation for the requested algorithm is available

java.security.NoSuchProviderException - if the requested provider is not available

getInstance

public static KeyEncapsulationMechanism getInstance(java.lang.String kem,
                                    java.security.Provider provider)
                                             throws java.security.NoSuchAlgorithmException,
                                                    java.security.NoSuchProviderException

Creates a provider-specific Key Encapsulation Mechanism engine for the given kem.

Parameters:

kem - the kem kem for which an engine should be created

provider - the provider whose KEM implementation is requested

Throws:

java.security.NoSuchAlgorithmException - if no implementation for the requested algorithm is available

java.lang.IllegalArgumentException - if provider is null

java.security.NoSuchProviderException

getAlgorithm

public java.lang.String getAlgorithm()

Returns the algorithm name of this KEM object.

This is the same name that was specified in one of the getInstance calls that created this KEM object.

Returns:

the algorithm name of this KEM object.

getProvider

public java.security.Provider getProvider()

Returns the provider of this KEM object.

Returns:

the provider of this KEM object

init

public void init(java.security.Key key)
          throws java.security.InvalidKeyException

Initializes this KEM with a key.

The underlying implementation will derive the algorithm parameters from the provided key. Furthermore, the class can call either the encapsule(byte[]) or the decapsule(byte[], byte[]) method, depending on the type of key (PublicKey or PrivateKey).

Note: do not call this method multiple times as it results in undefined behaviour.

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,

init

public void init(java.security.Key key,
        java.security.SecureRandom random)
          throws java.security.InvalidKeyException

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

The underlying implementation will derive the algorithm parameters from the provided key. Furthermore, the class can call either the encapsule(byte[]) or the decapsule(byte[], byte[]) method, depending on the type of key (PublicKey or PrivateKey).

The implementation will use the source of randomness to create any random octets.

Note: do not call this method multiple times as it results in undefined behaviour.

Parameters:

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

random - 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,

init

public void init(java.security.Key key,
        java.security.spec.AlgorithmParameterSpec algorithmParameterSpec)
          throws java.security.InvalidKeyException,
                 java.security.InvalidAlgorithmParameterException

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

The class can call either the encapsule(byte[]) or the decapsule(byte[], byte[]) method, depending on the type of key (PublicKey or PrivateKey).

Note: do not call this method multiple times as it results in undefined behaviour.

Parameters:

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

algorithmParameterSpec - 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

init

public void init(java.security.Key key,
        java.security.spec.AlgorithmParameterSpec algorithmParameterSpec,
        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 random.

The class can call either the encapsule(byte[]) or the decapsule(byte[], byte[]) method, depending on the type of key (PublicKey or PrivateKey).

Note: do not call this method multiple times as it results in undefined behaviour.

Parameters:

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

algorithmParameterSpec - 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

encapsule

public byte[] encapsule(byte[] k)
                 throws java.security.InvalidKeyException,
                        java.security.DigestException

The encapusle method of the KEM.

This method performs the encapusle operation of the KEM with the key provided in one of the init() methods, generating a new session key k which is written to the provided byte array. The caller has to ensure that the byte array is large enough for the requested key size.

The method returns a ciphertext which can be fed to decapsule(byte[], byte[]) to obtain the same session key.

Parameters:

k - a byte array large enough to hold the session key. Size depends on configured KDF.

Returns:

a ciphertext. When calling decapsule(byte[], byte[]) with the correct PrivateKey and the ciphertext, it is possible to obtain the session key.

Throws:

java.security.InvalidKeyException - if caller provides a corrupt or wrong key

java.security.DigestException - if the byte array has not the appropriate size for the KDF

See Also:

decapsule(byte[], byte[])

getParameters

public java.security.AlgorithmParameters getParameters()

Returns the parameters used by this KEM.

The returned parameters are derived by the key provided in one of the init() methods.

Returns:

the parameters used with this KEM, or null if this cipher does not use any parameters.

decapsule

public void decapsule(byte[] c,
             byte[] k)
               throws java.security.InvalidKeyException,
                      java.security.DigestException

The decapsule method of the KEM.

The method performs the decapsule operation of the KEM, taking the ciphertext obtained from a call to encapsule(byte[]), reconstructing the encrypted session key k which is written to the provided byte array. The caller has to ensure that the byte array is large enough for the requested key size. The implementation uses the key provided in one of the init() method.

Parameters:

c - a ciphertext that was created from calling encapsule(byte[]) and the PublicKey associated with the private key provided in init()

k - a byte array large enough to hold the session key.

Throws:

java.security.InvalidKeyException - if caller provides a corrupt or wrong key

java.security.DigestException - if the byte array has not the appropriate size for the KDF

See Also:

encapsule(byte[])

toString

public java.lang.String toString()

Returns a string representation of the KEM in the form of:

"Key Encapsulation Mechanism: ALGORITHM_NAME"

Overrides:

toString in class java.lang.Object

Returns:

a string representation