ds.ov2.bignat
Class Modulus

java.lang.Object
  ds.ov2.util.Serializable_array
      ds.ov2.bignat.Modulus

All Implemented Interfaces:

APDU_Serializable

public class Modulus
extends Serializable_array
implements APDU_Serializable

Division modulus for Java Card. Contains the modulus itself and the negated inverse of its last digit. The latter is needed inside Montgomery multiplication.

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

This is a card data type. It is compatible with

• Moduli of the same size
• Host_moduli, configured to the same size

CPP Preprocessing

This class uses the following cpp defines: PACKAGE, PUBLIC, VARIABLE_SIZE_BIGNATS, DOUBLE_DIGIT_TYPE, APDU_DOUBLE_DIGIT_TYPE, JAVACARD_APPLET, BIGNAT_USE_BYTE

Execution Environment:

host, card

Author:

Hendrik Tews

Version:

$Revision: 1.21 $

Last Commit:

$Date: 2010-02-12 10:59:31 $ by $Author: tews $

Field Summary

short	last_digit_inverse Negated modular inverse of the last digit.
private APDU_short	last_digit_inverse_box APDU wrapper for last_digit_inverse.
Bignat	m The modulus itself.
Bignat	mod_x_2 Modulus times 2.
Bignat	mod_x_3 Modulus times 3.
private APDU_Serializable[]	serializable_contents Serializable array for the Serializable_array base class.
(package private) static short	serializable_contents_length Length of the underlying serializable array.

Constructor Summary

Modulus(short bignat_size, boolean in_ram)
Allocating constructor.

Method Summary

void	allocate_multiples() Allocate the space for the multiples mod_x_2 and mod_x_3 of the modulus m.
short	from_byte_array(short len, short this_index, byte[] byte_array, short byte_index) Deserialization of this object for the OV-chip protocol layer.
protected APDU_Serializable[]	get_array() Return serializable_contents in support for abstract Serializable_array.
short	get_length() Return serializable_contents_length as effective size in support for abstract Serializable_array.
private void	initialize_multiples() (Re-)Initialize the multiples mod_x_2 and mod_x_3 if they have been allocated before with allocate_multiples().
boolean	is_compatible_with(Object o) Compatibility check for the OV-chip protocol layer.
void	register_long_bignats() Register the modulus and the multiples (if allocated) in Resize for resizing.
short	to_byte_array(short len, short this_index, byte[] byte_array, short byte_index) Serialization of this object for the OV-chip protocol layer.

Methods inherited from class ds.ov2.util.Serializable_array

size

Methods inherited from class java.lang.Object

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

Methods inherited from interface ds.ov2.util.APDU_Serializable

size

Field Detail

m

public Bignat m

The modulus itself.

mod_x_2

public Bignat mod_x_2

Modulus times 2. Allocated and initialized explicitely in allocate_multiples only when needed for squared_rsa_mult_4.

mod_x_3

public Bignat mod_x_3

Modulus times 3. Allocated and initialized explicitely in allocate_multiples only when needed for squared_rsa_mult_4.

last_digit_inverse

public short last_digit_inverse

Negated modular inverse of the last digit. Has type DOUBLE_DIGIT_TYPE. This is needed inside Montgomery multiplication.

Conveniently computed by the initializing Host_modulus constructor, see Host_modulus.last_digit_inverse.

Must fulfill the following property: m * last_digit_inverse + 1 == 0 (modulo Bignat.bignat_base), where bignat_base is 256 for the byte/short configuration and 2^32 for the int/long configuration.

To compute one takes the inverse of the last digit of m with respect to Bignat.bignat_base and multiplies it with -1, i.e., Bignat.bignat_base -1, again modulo Bignat.bignat_base. Because Bignat.bignat_base is a power of 2, the modular inverse exists only for odd moduli.

last_digit_inverse_box

private APDU_short last_digit_inverse_box

APDU wrapper for last_digit_inverse. Used for (de-)serialization of last_digit_inverse.

serializable_contents_length

static final short serializable_contents_length

Length of the underlying serializable array. It is currently 2.

See Also:

Constant Field Values

serializable_contents

private APDU_Serializable[] serializable_contents

Serializable array for the Serializable_array base class. Will contain serializable_contents_length length elements, currently the modulus m and last_digit_inverse_box in this order. Must be compatible with Host_modulus.serializable_array.

Constructor Detail

Modulus

public Modulus(short bignat_size,
               boolean in_ram)

Allocating constructor. Allocates a Bignat of size bignat_size for the modulus and allocates and fills the remaining fields, in particular serializable_contents. The argument in_ram is passed through to the Bignat constructor, that is, if in_ram is true then the modulus is allocated in transient RAM.

Parameters:

bignat_size - size of the modulus

in_ram - allocate modulus in transient ram if true

Method Detail

register_long_bignats

public void register_long_bignats()

Register the modulus and the multiples (if allocated) in Resize for resizing. Only available if VARIABLE_SIZE_BIGNATS is defined. The internal Bignat, containing the modulus, is registered as a long Bignat.

allocate_multiples

public void allocate_multiples()

Allocate the space for the multiples mod_x_2 and mod_x_3 of the modulus m. They are needed only inside squared_rsa_mult_4, so only call this method if squared_rsa_mult_4 is used with this modulus.

If VARIABLE_SIZE_BIGNATS is defined this method must be called before register_long_bignats() (and thus before the first resize) otherwise the multiples will not be resized.

Once allocated the multiples are automatically initialized when the modulus is initialized inside from_byte_array. This requires of course that the first two bits of the modulus are empty, because otherwise an overflow will occur inside add. Asserts that that mod_x_2 and mod_x_3 are null, ie. that this method has not been called before.

initialize_multiples

private void initialize_multiples()

(Re-)Initialize the multiples mod_x_2 and mod_x_3 if they have been allocated before with allocate_multiples(). Automatically called from from_byte_array.

Requires that the first two bits of the just received modulus are zero, because otherwise add will overflow.

get_array

protected APDU_Serializable[] get_array()

Return serializable_contents in support for abstract Serializable_array.

Specified by:

get_array in class Serializable_array

Returns:

array of objects to (de-)serialize

get_length

public short get_length()

Return serializable_contents_length as effective size in support for abstract Serializable_array.

Overrides:

get_length in class Serializable_array

Returns:

serializable_contents_length

is_compatible_with

public boolean is_compatible_with(Object o)

Compatibility check for the OV-chip protocol layer. See the compatibility check explanations and also APDU_Serializable.is_compatible_with.

An object of this class is compatible with instances of Modulus or Host_modulus if the internal modulus has the same size.

Specified by:

is_compatible_with in interface APDU_Serializable

Overrides:

is_compatible_with in class Serializable_array

Parameters:

o - actual argument or result

Returns:

true if this (the declared argument or result) is considered binary compatible with o.

to_byte_array

public short to_byte_array(short len,
                           short this_index,
                           byte[] byte_array,
                           short byte_index)

Serialization of this object for the OV-chip protocol layer. See APDU_Serializable.to_byte_array. Overridden here to update last_digit_inverse_box before serialization.

Specified by:

to_byte_array in interface APDU_Serializable

Overrides:

to_byte_array in class Serializable_array

Parameters:

len - available space in byte_array

this_index - number of bytes that have already been written in preceeding calls

byte_array - data array to serialize the state into

byte_index - index in byte_array

Returns:

the number of bytes actually written, except for the case where serialization finished by writing precisely len bytes, in this case len + 1 is returned.

from_byte_array

public short from_byte_array(short len,
                             short this_index,
                             byte[] byte_array,
                             short byte_index)

Deserialization of this object for the OV-chip protocol layer. See APDU_Serializable.from_byte_array. Overridden here to update last_digit_inverse after deserialization.

Specified by:

from_byte_array in interface APDU_Serializable

Overrides:

from_byte_array in class Serializable_array

Parameters:

len - available data in byte_array

this_index - number of bytes that have already been read in preceeding calls

byte_array - data array to deserialize from

byte_index - index in byte_array

Returns:

the number of bytes actually read, except for the case where deserialization finished by reading precisely len bytes, in this case len + 1 is returned.