ds.ov2.front
Class RSA_host_card

java.lang.Object
  ds.ov2.front.RSA_host_card

public class RSA_host_card
extends Object

Host driver for all RSA applets. This class contains methods for all tasks for these applets. These methods run the host side of the protocols. This class only covers the normal protocols. Additional host driver code for the debug protcol is in RSA_card_debug.

The code in this class can deal with both, the plain RSA applet and the montgomerizing RSA applet.

There are two different channels where the methods here can show their progress. First, there is PrintWriter object out, initialized in the constructor, which will receive progress and debug messages if it is non-null.

Alternatively one can use an instance of RSA_protocol_messages. This interface specifies about 15 methods that are if specific points are reached in the protocol.

CPP Preprocessing

This class uses the following cpp defines: APPLET_TESTFRAME, TESTFRAME, RSA_CARD_PROTOCOL_STUBS

Execution Environment:

host

Author:

Hendrik Tews

Version:

$Revision: 1.46 $

Last Commit:

$Date: 2010-09-20 11:20:15 $ by $Author: tews $

Field Summary

private Front_protocols	front_protocols Instance with the protocol description classes.
private PrintWriter	out Message output channel.
private Random	rand Randomness source.
private RSA_card_protocol_stubs	stubs IDL compiler generated stubs.
private int	verbosity Requested verbosity of the messages on out.

Constructor Summary

RSA_host_card(Front_protocols front_protocols, RSA_card_protocol_stubs stubs, PrintWriter out, int verbosity)
Constructor.

Method Summary

boolean	check_gate(PTLS_rsa_parameters params, CardChannel card_channel, RSA_protocol_messages messages, boolean check_signature) Run the gate protocol with the card.
short	get_montgomery_correction_length(PTLS_rsa_parameters params, Applet_type applet_type) The length of the array for the Montgomery correction factors.
void	host_side_init(PTLS_rsa_parameters params, Applet_type applet_type) Initialize the host-driver copy of the protocols.
void	initialize_card(PTLS_rsa_parameters params, CardChannel card_channel, RSA_protocol_messages messages, Applet_type applet_type) Basic applet initialization.
boolean	issue_card(PTLS_rsa_parameters params, CardChannel card_channel, RSA_protocol_messages messages, Applet_type applet_type) Combined card initialization and personalization.
boolean	resign(BigInteger[] updates_bi, boolean check_signature, PTLS_rsa_parameters params, CardChannel card_channel, RSA_protocol_messages messages) Run the resign protocol.

Methods inherited from class java.lang.Object

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

Field Detail

front_protocols

private final Front_protocols front_protocols

Instance with the protocol description classes. Needed to perform some operations directly in the host driver copy of the protocol descriptions.

stubs

private final RSA_card_protocol_stubs stubs

IDL compiler generated stubs. Used to invoke the applet methods. Declared as RSA_CARD_PROTOCOL_STUBS, which expands to either RSA_card_protocol_stubs or RSA_card_protocol_test_stubs.

rand

private final Random rand

Randomness source.

out

private final PrintWriter out

Message output channel.

verbosity

private final int verbosity

Requested verbosity of the messages on out. The code currently distinguishes the verbosity levels 0, 5, 10, and 15. Level 0 prints only protocol error messages. Higher values print more.

Constructor Detail

RSA_host_card

public RSA_host_card(Front_protocols front_protocols,
                     RSA_card_protocol_stubs stubs,
                     PrintWriter out,
                     int verbosity)

Constructor. Initializes the fields front_protocols, stubs, out, and verbosity from its arguments.

Parameters:

front_protocols - instance with the protocol description classes

stubs - delcared of type RSA_CARD_PROTOCOL_STUBS, the step method stubs

out - the channel for debug and error messages, pass null to disable such messages

verbosity - verbosity level on out, see verbosity

Method Detail

get_montgomery_correction_length

public short get_montgomery_correction_length(PTLS_rsa_parameters params,
                                              Applet_type applet_type)

The length of the array for the Montgomery correction factors. On the Montgomerizing, the squareing and the squared 4 RSA applet no correction factors are needed, therefore return 1 there (there are not 0-length Bignat_arrays). On the plain RSA applet numbers are not montgomerized because of the use of the RSA cipher there. When multiplying any two such numbers one needs to multiply an correction factor, see . The plain applet needs correction factors for 2,3,4,5 as well as for n + 1 and n + 2 factors, where n is the number of attributes (see PTLS_rsa_parameters.attribute_number).

In the array of the correction factors index 0 stores the correction for two factors. Therefore the length of the array is one less than the maximal needed factor.

Parameters:

applet_type - the applet type

Returns:

length of the array of Montgomery correction factors

host_side_init

public void host_side_init(PTLS_rsa_parameters params,
                           Applet_type applet_type)

Initialize the host-driver copy of the protocols. This is needed on the host side after the allocate protocol, because the remaining protocols get valid only after the allocate protocol has been run. This methods calls RSA_data.allocate with the same parameter on the card, to fill argument and result arrays of the remaining protocol steps. Then the delayed protocols and stubs are initialized.

The debug protocol does also depend on this kind of delayed initialization, see RSA_card_debug.host_side_init.

In order to have matching protocl description we have to use the same applet type here as we installed on the card.

Parameters:

params - the PTLS system parameters

applet_type - what applet type we have been talking to on the card

initialize_card

public void initialize_card(PTLS_rsa_parameters params,
                            CardChannel card_channel,
                            RSA_protocol_messages messages,
                            Applet_type applet_type)
                     throws CardException

Basic applet initialization. Assumes a freshly installed RSA applet behind card_channel. Runs the allocate and init_data protocols to finish allocation on the applet and download key material, attributes and whatelse is needed on the applet. During this initialization the blinding of the card is set to 1. The signature remains uninitialized and invalid.

The initialization steps are replicated in the host driver as necessary to bring the protocol layer here into the same state as on the card.

This method can initialize both, the plain RSA applet and the Montgomerizing RSA applet.

Parameters:

params - the PTLS system parameters

card_channel - communication channel to the applet, an applet of type applet_type must have been selected on that channel before

messages - progress message instance, can be null

applet_type - what applet type to initialize

Throws:

CardException - in case of an communication error with the card

To Do:

pass attributes as arguments instead of choosing them randomly

resign

public boolean resign(BigInteger[] updates_bi,
                      boolean check_signature,
                      PTLS_rsa_parameters params,
                      CardChannel card_channel,
                      RSA_protocol_messages messages)
               throws CardException

Run the resign protocol. The attributes of the card are thereby updated with updates_bi. Positive values are added to the card attribute, negative subtracted.

The addition or subtraction of the update to the current attribute value must not cause an over- or underflow. Otherwise the attribute expression computed here (without knowing the attribute values) will not equal the one on the card and the signature creation will fail.

Normally the signature on the card is checked. The check can be ommitted, with check_signature. This is necessary in the first resign step, which belongs to the card initialization, because then, the card does not have a valid signature yet.

The source code of this method is affected by Brand's patents on selective disclosure protocols that are now in the posession of Microsoft. Microsoft lawyers are still pondering our request from January 2009 for making the full source code publically available. The source code of this method is therefore currently not publically available. The detailed operations of this method are:

XXXXXXXXXXXXXX

Parameters:

updates_bi - the updates in the range between -PTLS_rsa_parameters.v + 1 and PTLS_rsa_parameters.v -1, inclusive.

check_signature - whether to check the signature of the card

params - the PTLS system parameters

card_channel - communication channel to the applet

messages - progress message instance

Returns:

true if the card accepted the attribute updates and the new signature, false if not. Note, that there is a very small chance that a communication error occors after the card has finished the transaction for updating attribute values and signature. In this case this method will return false or throw an CardException, although the card accepted the new signature.

Throws:

CardException - in case of communication errors with the card

issue_card

public boolean issue_card(PTLS_rsa_parameters params,
                          CardChannel card_channel,
                          RSA_protocol_messages messages,
                          Applet_type applet_type)
                   throws CardException

Combined card initialization and personalization. Calls initialize_card and performs resign step right afterwards. As a result the card is initialized with an unknown blinding and valid signature.

This method can issue both, a plain RSA applet and an Montgomerizing RSA applet.

Parameters:

params - the PTLS system parameters

card_channel - communication channel to the applet, an applet of type applet_id must have been selected on that channel before

messages - the progress message instance

applet_type - what applet type to initialize

Returns:

true if the resign step succeeded

Throws:

CardException - in case of communication errors with the card

check_gate

public boolean check_gate(PTLS_rsa_parameters params,
                          CardChannel card_channel,
                          RSA_protocol_messages messages,
                          boolean check_signature)
                   throws CardException

Run the gate protocol with the card. Let the card proof knowledge of all its attributes. Selective disclosure is not yet implemented. The signature check can be ommitted, but that is only there to permit performance mesurements of the MONTGOMERY_MULT_SHORTCUT optimization, in which all Montgomery multiplications on the card are skipped (and therefore all data the card produces is just garbage.

The source code of this method is affected by Brand's patents on selective disclosure protocols that are now in the posession of Microsoft. Microsoft lawyers are still pondering our request from January 2009 for making the full source code publically available. The source code of this method is therefore currently not publically available. The detailed operations of this method are:

XXXXXXXXXXXXXX

Parameters:

params - the PTLS system parameters

card_channel - communication channel to the applet

messages - the progress message instance

check_signature - whether to check the signature of the card (should never be false)

Returns:

true if the card could correctly answer our challenge

Throws:

CardException - in case a communication error occors