ds.ov2.bignat
Interface RSA_exponent_interface

All Known Implementing Classes:

Fake_rsa_exponent, RSA_exponent

public interface RSA_exponent_interface

Common interface of RSA_exponent and Fake_rsa_exponent. RSA_exponent does only run on the card and Fake_rsa_exponent is a compatible drop-in replacement of RSA_exponent that only runs on the host. This interface makes it possible to make some code independent of the implementation used.

Besides the methods specified here, implementing classes must implement two constructors, an allocating and a non-allocating one. Because the allocation functionality is factored out in allocate the allocating constructor calls the non-allocating constructor and allocate.

Classes implementing this interface might internally remember the key size that is set in allocate(short) and the allocating constructor. Certain arguments of the other methods must then match this key size in some way.

For a number of general topics see also the package description.

I would be grateful if somebody could explain me why I cannot specify constructors here. And don't tell me that one cannot call constructors of interfaces. I don't want to do that. I want to specify the constructors here in order to put constraints on implementing classes.

CPP Preprocessing

This class uses the following cpp defines: PACKAGE, PUBLIC

Execution Environment:

host, card

Author:

Hendrik Tews

Version:

$Revision: 1.5 $

Last Commit:

$Date: 2009-05-16 21:43:33 $ by $Author: tews $

Method Summary

void	allocate(short key_byte_size) Allocate internal data structures.
void	fixed_power(Bignat base, Bignat result, short offset) Modular power with preconfigured modulus and exponent.
void	init_key(short key_byte_size) (Re-)Initialize those internal data structures that depend on the key size.
void	power(Bignat base, Bignat exp, Bignat result, short offset) Modular power.
void	set_exponent(Bignat exp, Bignat temp, short offset) Initialize the exponent for subsequent use of this object with fixed_power.
void	set_modulus(Bignat mod, short offset) Set modulus.

Method Detail

init_key

void init_key(short key_byte_size)

(Re-)Initialize those internal data structures that depend on the key size. The key size is the effective size of the numbers, without Montgomery digits, if any. Therefore, if Montgomery multiplication is used the key size must be two less than the size of the base and modulus.

It is not recommended to call this method from the outside, because uncollected garbage might be left.

Parameters:

key_byte_size - the key size in bytes.

allocate

void allocate(short key_byte_size)

Allocate internal data structures. Call init_key internally. The key is initialized to size key_byte_size with init_key. This key size determins the size of the Bignat arguments for all the other methods. The key size is the effective size of the numbers, without Montgomery digits, if any. Therefore, if Montgomery multiplication is used the key size must be two less than the size of the base and modulus.

This method should only used once and only if the non-allocating constructor has been used to create this object. (The allocating constructor calls this method itself.)

Parameters:

key_byte_size - key size in bytes

set_modulus

void set_modulus(Bignat mod,
                 short offset)

Set modulus. Must be called before power or before set_exponent. Once set a modulus is used for all subsequently computed exponents until it is changed via this method. The offset argument specifies the number of ditits that mod is longer than the configured key size. If offset is different from 0 all digits left of offset are assumed to be zero. For a modulus that is used with Montgomery multiplication use an offset of 2.

If fixed_power is used, set_exponent must be called (again) after setting the modulus.

Parameters:

mod - modulus

offset - starting index of the most significant digit of the modulus

Throws:

ISOException - with reason Response_status.OV_RSA_MOD_FAILURE if the modulus has the wrong size

set_exponent

void set_exponent(Bignat exp,
                  Bignat temp,
                  short offset)

Initialize the exponent for subsequent use of this object with fixed_power. This is advantageous if more than one power is computed with the same exponent, because exponent initializtion amounts for about 60% (for short keys sizes) to 30% (for long key sizes) of the total computation time.

The modulus must have been set with set_modulus before calling this method.

The temporary is used here to permit exponents which are shorter than the configured key size of the underlying cipher. The offset argument specifies the number of digits that temp is larger then the configured key size. For a temporary that is used with Montgomery multiplication use an offset of 2.

Parameters:

exp - exponent

temp - temporary

offset - number of digits temp is longer than the configured key size of the underlying cipher object

Throws:

ISOException - with reason Response_status.OV_RSA_EXP_FAILURE if setting the exponent fails (which I believe happens for invalid key sizes that are not reported as such when initiliazing the key)

fixed_power

void fixed_power(Bignat base,
                 Bignat result,
                 short offset)

Modular power with preconfigured modulus and exponent. Sets result to base^exp mod modulus, where the modulus and exp must have been configured before with set_modulus and set_exponent, respectively. Note that set_modulus must always be called before set_exponent.

Using this method makes sense when more than one power is computed with the same modulus and exponent. Measurements show that initializing the modulus and the exponent amounts for about 60% (for short keys sizes) to 30% (for long key sizes) of the total computation time. This method is merely a wrapper around doFinal.

The argument offset specifies the number of digits that the base and the result are longer than the configured key size. For bases and results that are used with Montgomery multiplication use an offset of 2.

base and result must not be the same reference, otherwise the cipher may produce incorrect results.

Parameters:

base -

result - reference for storing the result

offset - number of digits base and result is longer than the configured key size

power

void power(Bignat base,
           Bignat exp,
           Bignat result,
           short offset)

Modular power. Sets result to base^exp mod modulus, where the modulus must have been configured before with set_modulus.

The argument offset specifies the index of the most significant digits of base and result. If base and result are used with Montgomery multiplication the offset should be 2.

The exponent must fit into key size many bytes but can otherwise be arbitrarily long.

base and result must not be the same reference, because result the exponent is first copied into result to permit exponents shorter than key size. Moreover the cipher on the card does not permit them to be the same reference.

Parameters:

base -

exp - exponent

result - reference for storing the result