iaik.security.rsa

Class RsaKem

java.lang.Object

iaik.security.kem.KeyEncapsulationMechanismSpi

iaik.security.rsa.RsaKem

public class RsaKem
extends KeyEncapsulationMechanismSpi

This class implements the RSA-KEM through the KeyEncapsulationMechanism (KEM) interface. For an explanation on the workflow of a KEM, see KeyEncapsulationMechanism.

An application may use this class to perform the necessary steps for the RSA-KEM. The RSA-KEM, given e.g., in rfc 5990 [1], or ISO/IEC 18033-2, is based on the RSA cryptosystem.

Two parties can use the RSA-KEM to transmit keying material in a confidential way. The sender has to perform the following steps:

1. Generate a random integer z between 0 and n-1, where n is the RSA modulus of the public key.
2. Encrypt the integer z with the receiver's RSA public key:

   c = z^e mod n

3. Derive a random octet string k from the integer z, with some Key Derivation Function.
4. Output c and k.

The random octet string k may be used as key to encrypt any arbitrary data. The sender then sends c (along with any encrypted data) to the receiver, where they are able to decrypt c, retrieve z, and re-compute k.

Virtually any strong enough Key Derivation Function may be used to the derive the k. This implementation supports the following Key Derivation Functions:

• KDF1
• KDF2
• KDF3

To obtain an instance of the RSA-KEM and configure it with the KDF3, using SHA2-256, perform the following steps:

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

Note that the methods engineInit(Key) and engineInit(Key, SecureRandom) will throw an UnsupportedOperationException, because the implementation has to have access to the Algorithm Parameters, to derive the desired session key length and the KDF.

Version:

File Revision 62 //TODO

Field Summary

Fields inherited from class iaik.security.kem.KeyEncapsulationMechanismSpi

key

Constructor Summary

Constructors

Constructor and Description
RsaKem()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	engineDecapsule(byte[] c, byte[] k) Performs the decapsule operation of the RSA-KEM (the receiver's side) as follows: Decrypt the integer z with the receiver's RSA private key:
protected void	engineDeriveKey(byte[] output, java.util.List input) Derives the key according to the transformation.
protected byte[]	engineEncapsule(byte[] k) Performs the encapsule operation of the RSA-KEM (the sender's side) as follows: Generate a random integer z between 0 and n-1, where n is the RSA modulus of the public key. Encrypt the integer z with the receiver's RSA public key:
protected java.security.AlgorithmParameters	engineGetParameters() SPI: Gets the algorithm parameters required by this KEM engine.
protected void	engineInit(java.security.Key key) Throws an UnsupportedOperationException
protected void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec spec) Initializes the KEM instance accordingly.
protected void	engineInit(java.security.Key key, java.security.spec.AlgorithmParameterSpec spec, java.security.SecureRandom secureRandom) Initializes the KEM instance accordingly.
protected void	engineInit(java.security.Key key, java.security.SecureRandom secureRandom) Throws an UnsupportedOperationException

Methods inherited from class java.lang.Object

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

Constructor Detail

RsaKem

public RsaKem()

Method Detail

engineInit

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

Throws an UnsupportedOperationException

Specified by:

engineInit in class KeyEncapsulationMechanismSpi

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 void engineInit(java.security.Key key,
              java.security.SecureRandom secureRandom)
                   throws java.security.InvalidKeyException

Throws an UnsupportedOperationException

Specified by:

engineInit in class KeyEncapsulationMechanismSpi

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 void engineInit(java.security.Key key,
              java.security.spec.AlgorithmParameterSpec spec)
                   throws java.security.InvalidKeyException,
                          java.security.InvalidAlgorithmParameterException

Initializes the KEM instance accordingly.

Specified by:

engineInit in class KeyEncapsulationMechanismSpi

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

java.security.InvalidAlgorithmParameterException

engineInit

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

Initializes the KEM instance accordingly.

Specified by:

engineInit in class KeyEncapsulationMechanismSpi

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

java.security.InvalidAlgorithmParameterException

engineGetParameters

protected java.security.AlgorithmParameters engineGetParameters()

Description copied from class: KeyEncapsulationMechanismSpi

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

Specified by:

engineGetParameters in class KeyEncapsulationMechanismSpi

Returns:

the parameters used by this engine

engineDeriveKey

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

Derives the key according to the transformation.

Specified by:

engineDeriveKey in class KeyEncapsulationMechanismSpi

Parameters:

output - a large enough byte array depending on used kdf

input - the input to the key derivation function

Throws:

java.security.DigestException - if the byte array has not the correct size

engineEncapsule

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

Performs the encapsule operation of the RSA-KEM (the sender's side) as follows:

1. Generate a random integer z between 0 and n-1, where n is the RSA modulus of the public key.
2. Encrypt the integer z with the receiver's RSA public key:

   c = z^e mod n

3. Derive a key-encrypting key k from the integer z, with some pseudorandom function.
4. Output c and k.

Specified by:

engineEncapsule in class KeyEncapsulationMechanismSpi

Parameters:

k - the destination of the session key k

Returns:

the ciphertext c

Throws:

java.security.InvalidKeyException - if a wrong key is used

java.security.DigestException - if the byte array k has not the correct size for the used transformation

java.lang.IllegalStateException - if the caller provided a wrong key, e.g., a private key

See Also:

KeyEncapsulationMechanismSpi.engineDecapsule(byte[], byte[])

engineDecapsule

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

Performs the decapsule operation of the RSA-KEM (the receiver's side) as follows:

1. Decrypt the integer z with the receiver's RSA private key:

   z = c^d mod n

2. Derive a key-encrypting key k from the integer z, with some KDF.
3. Output k.

Specified by:

engineDecapsule in class KeyEncapsulationMechanismSpi

Parameters:

c - the ciphertext obtained from encap

k - the destination of the session key k

Throws:

java.security.InvalidKeyException - if a wrong key is used

java.security.DigestException - if the byte array k has not the correct size for the used transformation

java.lang.IllegalStateException - if the caller provided a wrong key, e.g., a private key

java.security.InvalidParameterException