ds.ov2.test
Class Test_host

java.lang.Object
  ds.ov2.test.Test_host

public class Test_host
extends Object

Main class of the host driver for the test applet that gives access to all the functionality of the test applet. This host driver automatically (re-)installs the applet if it is not found or not up-to-date. The driver can talk to real cards or to the jcop emulator, see the options -c and -r. (It can also talk to the SUN emulators cref and jcwde, however, applet installation fails there because of the absense of the RSA cipher.)

The test host driver is a non-interactive terminal program that can run several tests and performance measurements. What test and measurments are run depends on the command line options. As default nothing is run. The measurements results are printed in gnuplot compatible way. For examples on how to produce nice charts out of the performance data, see the gnuplot scripts in the subdirectory test/Measurments.

Some parts of the command line that is necessary to start this program depend on the configuration. Therefore the makefile generates the test_host shell script for a convenient invocation.

There are two different kinds of command line options for this program: The task selection options that enable one of the checks or measurements and the configuration options that change some more or less common behavior (for instance to talk to a card or an emulator). The complete list of options is printed for the options -h, -help and --help.

Checks and Measurments

The *-check options enable checks while the *-perf options enable performance measurements. With the exception of -data-perf all measurements do also check the results of the card and do immediately stop the program on any error encountered.

The checks perform their computations with numbers of the long (base) size, which can be set with -size. Except for -data-perf all performance measurements measure the time for different sizes. That is, the measurements run in a loop with increasing sizes. Except -data-perf all measurements recognize the -start-size option to set the starting size.

The possible tests and measurements and the corresponding task selection options are as follows:

-ping

Run the ping protocol: Send an empty APDU to the applet.

-data-check

Checks the OV-chip protocol layer by running protocols with various argument and result sizes. The bytes of the APDU's have successive values from 0 to 255 to perform integrity checks.

-data-perf

Performance measurement of the communication time, including the OV-chip protocol overhead. Performs only transmission time measurements, the payload of the APDU's is not checked for integrity.

-mont-mult-check

Check Montgomery multiplication and demongomerization.

-mont-mult-perf

Measure Montgomery multiplication and demongomerization performance.

-div-check

Check division/remainder.

-div-perf

Measure Divison/remainder performance.

-vec-exp-check

Check multi-exponent computation (simultaneous squaring version).

-vec-exp-perf

Measure multi-exponent computation (simultaneous squaring version).

-rsa-vec-exp-check

Check RSA multi-exponent computation.

-rsa-vec-exp-perf

Measure RSA multi-exponent computation.

-squared-vec-exp-check

Check squared or square 4 RSA multi-exponent computation.

-squared-vec-exp-perf

Measure squared or squared 4 RSA multi-exponent computation.

-rsa-exp-check

Check single RSA exponent computation.

-rsa-exp-perf

Measure single RSA exponent computation.

-squared-mult-check

Check Bignat.squared_rsa_mult.

-squared-mult-perf

Measure Bignat.squared_rsa_mult.

-short-squared-mult-perf

Measure Bignat.short_squared_rsa_mult.

-squared-mult-4-check

Check Bignat.squared_rsa_mult_4.

-squared-mult-4-perf

Measure Bignat.squared_rsa_mult_4.

-short-square-mult-4-perf

Measure Bignat.short_squared_rsa_mult_4.

-add-perf

Measure Bignat.add.

-normal-mult-perf

Measure Bignat.mult.

-subtract-perf

Measure Bignat.subtract.

-list-readers

List all connected PC/SC readers and exit immediately afterwards.

-all-checks

Enables all checks: ping, data transmission, Montgomery multiplication/demongomerization, divison, multi-exponent in both version, RSA single exponent, squared multiplication and squared 4 multiplication. If a size has been specified with -size that size is used for all check. Otherwise the size is adjusted so that the check do not take too long.

-check-all

Synonym for -all-checks

Configuration Options

The configuration options change aspects of one or several checks and measurements.

-size n

Set the size of the long (base) bignats to n bytes. Adjust the short (exponent) size according to Lenstras key length estimation (see Security_parameter) if no exponent size has been set before. All checks perform their computaitions with the long bignat size. Many tests and measurements need to take care of Montgomery digits. This means that the numbers that are used in these computations are two digits (i.e., two bytes for the byte/short configuration of the bignat library) shorter than what specified with this option.

-exp-size n

Set the size of the short (exponent) bignats to n bits.

-fixed-exponent e

Use exponent e. Currently only supported by the RSA exponent checks (-rsa-exp-check and -rsa-exp-perf). The exponent size must be set independently.

-start-size n

For performance measurements: Set the starting size of the performance loop.

-div-length n

Set the divisor length to n percent of the divident length. Only used for the division check and measurement. To measure division with dividents twice as big as divisors use -div-length 50

-vec-len n

Set the length of the vectors used in the multi-exponent checks and measurements to n.

-pre-base-fac n

Set the number of bases for which all their factors are precomputed. Only used for the simultaneous squaring tasks. There precomputed factor tables of the bases make a big performance difference.

-keep-mod

Run a number of consequtive tests/measurements with the same modulus. This simulates the OV-chip application case where the modulus stays constant. Should be beneficial for the RSA multi-exponent tasks, because there modulus must installed in the RSA key.

-rounds n

Run n rounds of every enabled check. For performance measurements run n rounds for every measured size.

-i n

Supply the fixed argument n, which must be in decimal BigInteger string. If enough fixed arguments have been supplied, all tests and measurements take their numbers form the fixed arguments.

-hex n

Same as -i, except that n is a hexadicimal number string, which can contain dots to separate digit groups.

-jcop

Connect to the jcop emulator. This is the default if the necessary libraries are in the class path at runtime.

-sun

Connect to a SUN emulator. Pretty much useless option, because applet installation does always fail on these emulators because of the lacking RSA support.

-c

Connect to the first PC/SC terminal that is reported to us. This is the default if not all necessary librarie for the jcop emulator are present.

-r n

Connect to the PC/SC reader with index n. To get an idea about the choice, use -list-reader.

-jcop-port p

Set the port number for the jcop emulator (default 8015).

-list-applets

Output the list of applets that are present on the card during applet installation.

-reinstall

Force applet reinstallation.

-keep-applet

Keep installed applet, even if its timestamp is different from the current cap file.

-mem-size

Query the amount of available memory on the card.

-check-corner-cases

Check programmed corner cases. Currently only supported by squared multiplication, short squared multiplication and squared 4 multiplication.

-h, -help, --help

Display online help for all available options.

-d, -dd, -ddd

Set verbosity level to 5, 10, and 15, respectively. Higher numbers mean more output. See State.verbosity for explanations about these levels.

-apdutool

If the verbosity is high enough to print APSU's then print also apdutool script lines.

This class

This class contains the command line parsing, the logic to invoke the enables tests and measurements and applet installation. The methods that implement the tests and measurements are in different classes.

Static class.

CPP Preprocessing

no cpp preprocessing needed

Execution Environment:

host

Author:

Hendrik Tews

Version:

$Revision: 1.56 $

Last Commit:

$Date: 2010-02-18 11:42:49 $ by $Author: tews $

Field Summary

private static int	all_checks_rounds Number of rounds to run all checks for the -all-checks option.
private static Reference<Integer>	card_reader_number The index of the card reader to connect to.
private static SimpleDateFormat	date_format Date formatter used here at various places.
private static Reference<Integer>	jcop_port_number The port number used for the jcop emulator.
private static Reference<Boolean>	keep_applet Controls applet reinstallation.
static String	long_application_name Long application name.
static Option[]	options Array declaring all recognized command line options.
private static Reference<Boolean>	reinstall_applet Controls applet (re-)installation.
private static Reference<Boolean>	run_add_perf Controls addition performance.
private static Reference<Boolean>	run_all_checks Controls running all checks.
private static Reference<Boolean>	run_data_check Controls the data transfer check.
private static Reference<Boolean>	run_data_perf Controls the data transfer measurement.
private static Reference<Boolean>	run_div_check Controls the division check.
private static Reference<Boolean>	run_div_perf Controls the division performance.
private static Reference<Boolean>	run_list_applets Controls applet listing.
private static Reference<Boolean>	run_list_readers Controls whether to list all connected readers.
private static Reference<Boolean>	run_mem_size Crontrols whether to query the memory size.
private static Reference<Boolean>	run_mont_mult_check Controls the Montgomery multiplication check.
private static Reference<Boolean>	run_mont_mult_perf Controls the Montgomery multiplication measurement.
private static Reference<Boolean>	run_normal_mult_perf Controls normal multiplication performance.
private static Reference<Boolean>	run_ping Controls running ping.
private static Reference<Boolean>	run_rsa_exp_check Controls the RSA exponent check.
private static Reference<Boolean>	run_rsa_exp_perf Controls the RSA exponent performance.
private static Reference<Boolean>	run_rsa_vec_exp_check Controls the RSA vector exponent check.
private static Reference<Boolean>	run_rsa_vec_exp_perf Controls the RSA vector exponent performance.
private static Reference<Boolean>	run_short_square_4_mult_perf Controls the short squared 4 multiplication performance measurements.
private static Reference<Boolean>	run_short_squared_mult_perf Controls the short squared multiplication performance measurements.
private static Reference<Boolean>	run_squared_mult_4_check Controls the squared 4 multiplication check.
private static Reference<Boolean>	run_squared_mult_4_perf Controls the squared 4 multiplication performance.
private static Reference<Boolean>	run_squared_mult_check Controls the squared multiplication check.
private static Reference<Boolean>	run_squared_mult_perf Controls the squared multiplication performance.
private static Reference<Boolean>	run_squared_rsa_vec_exp_check Controls the squared/squared 4 RSA vector exponent check.
private static Reference<Boolean>	run_squared_rsa_vec_exp_perf Controls the squared/squared 4 RSA vector exponent performance.
private static Reference<Boolean>	run_subtract_perf Controls subtraction perfomrance Set by option -subtract-perf.
private static Reference<Boolean>	run_vec_exp_check Controls the vector exponent check.
private static Reference<Boolean>	run_vec_exp_perf Controls the vector exponent performance.
static String	short_application_name Short application name.
private static Reference<Card_terminal.Terminal_type>	terminal_type Terminal type to connect to.
private static Card_terminal.Terminal_type	terminal_type_default Default terminal type.
private static Charset	us_ascii US-ASCII charset for string-to-applet-ID conversion.

Constructor Summary

protected

Test_host() Static class, object creation disabled.

Method Summary

static void	list_applets(CardChannel channel, PrintWriter out) List all applets.
static void	main_ex(String[] args) Real main method.
static void	main(String[] args) Entry point.
static APDU_Serializable[]	make_installation_arguments(String cap_file_name) Create the array of installation arguments for the test applet, see Test_applet.install.
static void	open_test_applet(CardChannel card_channel, Test_protocols test_protocols, PrintWriter out) Select the test applet on the card.
static void	print_applet_status(PrintWriter out, Misc_protocols_stubs.Status_result stat) Print applet status to out.
static void	reinstall_applet(CardChannel channel, PrintWriter out) (Re-)Install the test applet.
static void	run_tests(String[] args, Test_protocols test_protocols, CardChannel card_channel) Run all requested tests and performance measurements.

Methods inherited from class java.lang.Object

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

Field Detail

short_application_name

public static final String short_application_name

Short application name. Printed on fatal errors.

See Also:

Constant Field Values

long_application_name

public static final String long_application_name

Long application name. Printed in the usage message.

See Also:

Constant Field Values

all_checks_rounds

private static final int all_checks_rounds

Number of rounds to run all checks for the -all-checks option.

See Also:

Constant Field Values

run_all_checks

private static Reference<Boolean> run_all_checks

Controls running all checks. Set by option -all-checks.

run_ping

private static Reference<Boolean> run_ping

Controls running ping. Set by option -ping.

run_data_check

private static Reference<Boolean> run_data_check

Controls the data transfer check. Set by option -data-check.

run_data_perf

private static Reference<Boolean> run_data_perf

Controls the data transfer measurement. Set by option -data-perf.

run_mont_mult_check

private static Reference<Boolean> run_mont_mult_check

Controls the Montgomery multiplication check. Set by option -mont-mult-check.

run_mont_mult_perf

private static Reference<Boolean> run_mont_mult_perf

Controls the Montgomery multiplication measurement. Set by option -mont-mult-perf.

run_div_check

private static Reference<Boolean> run_div_check

Controls the division check. Set by option -div.

run_div_perf

private static Reference<Boolean> run_div_perf

Controls the division performance. Set by option -div-perf.

run_vec_exp_check

private static Reference<Boolean> run_vec_exp_check

Controls the vector exponent check. Set by option -vec-exp-check.

run_vec_exp_perf

private static Reference<Boolean> run_vec_exp_perf

Controls the vector exponent performance. Set by option -vec-exp-perf.

run_rsa_vec_exp_check

private static Reference<Boolean> run_rsa_vec_exp_check

Controls the RSA vector exponent check. Set by option -rsa-vec-exp-check.

run_rsa_vec_exp_perf

private static Reference<Boolean> run_rsa_vec_exp_perf

Controls the RSA vector exponent performance. Set by option -rsa-vec-exp-perf.

run_squared_rsa_vec_exp_check

private static Reference<Boolean> run_squared_rsa_vec_exp_check

Controls the squared/squared 4 RSA vector exponent check. Set by option -squared-vec-exp-check.

run_squared_rsa_vec_exp_perf

private static Reference<Boolean> run_squared_rsa_vec_exp_perf

Controls the squared/squared 4 RSA vector exponent performance. Set by option -squared-vec-exp-perf.

run_rsa_exp_check

private static Reference<Boolean> run_rsa_exp_check

Controls the RSA exponent check. Set by option -rsa-exp-check.

run_rsa_exp_perf

private static Reference<Boolean> run_rsa_exp_perf

Controls the RSA exponent performance. Set by option -rsa-exp-perf.

run_squared_mult_check

private static Reference<Boolean> run_squared_mult_check

Controls the squared multiplication check. Set by option -squared-mult-check.

run_squared_mult_perf

private static Reference<Boolean> run_squared_mult_perf

Controls the squared multiplication performance. Set by option -squared-mult-perf.

run_short_squared_mult_perf

private static Reference<Boolean> run_short_squared_mult_perf

Controls the short squared multiplication performance measurements. Set by option -short-squared-mult-perf.

run_squared_mult_4_check

private static Reference<Boolean> run_squared_mult_4_check

Controls the squared 4 multiplication check. Set by option -squared-mult-4-check.

run_squared_mult_4_perf

private static Reference<Boolean> run_squared_mult_4_perf

Controls the squared 4 multiplication performance. Set by option -squared-mult-4-perf.

run_short_square_4_mult_perf

private static Reference<Boolean> run_short_square_4_mult_perf

Controls the short squared 4 multiplication performance measurements. Set by option -short-square-4-mult-perf.

run_add_perf

private static Reference<Boolean> run_add_perf

Controls addition performance. Set by option -add-perf.

run_normal_mult_perf

private static Reference<Boolean> run_normal_mult_perf

Controls normal multiplication performance. Set by option -normal-mult-perf.

run_subtract_perf

private static Reference<Boolean> run_subtract_perf

Controls subtraction perfomrance Set by option -subtract-perf.

run_mem_size

private static Reference<Boolean> run_mem_size

Crontrols whether to query the memory size. Set by option -mem-size.

run_list_readers

private static Reference<Boolean> run_list_readers

Controls whether to list all connected readers. Set by option -list-readers.

run_list_applets

private static Reference<Boolean> run_list_applets

Controls applet listing. Set by option -list-applets.

reinstall_applet

private static Reference<Boolean> reinstall_applet

Controls applet (re-)installation. Set by option -reinstall.

keep_applet

private static Reference<Boolean> keep_applet

Controls applet reinstallation. Set by option -keep-applet.

us_ascii

private static final Charset us_ascii

US-ASCII charset for string-to-applet-ID conversion.

terminal_type_default

private static final Card_terminal.Terminal_type terminal_type_default

Default terminal type. Initialized to Card_terminal.Terminal_type.JCOP_EMULATOR if the necessary libraries for connecting to the jcop emulator are available. Initialized to Card_terminal.Terminal_type.PCSC_TERMINAL otherwise.

terminal_type

private static Reference<Card_terminal.Terminal_type> terminal_type

Terminal type to connect to. Changed by the options -jcop, -sun, -c and -r.

jcop_port_number

private static Reference<Integer> jcop_port_number

The port number used for the jcop emulator.

card_reader_number

private static Reference<Integer> card_reader_number

The index of the card reader to connect to. Set by the option -r.

date_format

private static SimpleDateFormat date_format

Date formatter used here at various places.

options

public static Option[] options

Array declaring all recognized command line options.

Constructor Detail

Test_host

protected Test_host()

Static class, object creation disabled.

Method Detail

run_tests

public static void run_tests(String[] args,
                             Test_protocols test_protocols,
                             CardChannel card_channel)

Run all requested tests and performance measurements. Runs all those tests and measurments whose corresponding run_* field is true, that is, which have been enabled via their command line option.

Parameters:

args - the complete command line, as received in main

test_protocols - instance with all test protocols

card_channel - communicaion channel to the test applet (which must have been selected before)

list_applets

public static void list_applets(CardChannel channel,
                                PrintWriter out)
                         throws CardException

List all applets. Retrieves the names of all applets from the card or emulator with the help of the global platform manager. They are then printed to out.

Parameters:

channel - communication channel to the card

out - output channel for progress and the applet list

Throws:

CardException - for communication problems

make_installation_arguments

public static APDU_Serializable[] make_installation_arguments(String cap_file_name)

Create the array of installation arguments for the test applet, see Test_applet.install. The installation arguments are the short bignat size (State.short_bignat_max_size), the long bignat size (State.long_bignat_max_size), the double-sized bignat size (State.double_bignat_max_size), the base/exponent vector length (State.max_vector_length), and the creation time of the applet cap file as 8-byte byte array, which carries the long value as returned by File.lastModified().

Parameters:

cap_file_name - applet cap file name

Returns:

the installation arguments as serializable array

reinstall_applet

public static void reinstall_applet(CardChannel channel,
                                    PrintWriter out)
                             throws CardException,
                                    IOException

(Re-)Install the test applet. Uses the global platform manager to install the applet in the file State.test_card_applet_file on the card. If a package with name State.test_card_package_name is on the card, it is deleted before. If applet listing has been enabled, the installed applets are printed to out at the end.

Parameters:

channel - communication channel to the card

out - output channel for progress and status messages

Throws:

CardException - for communication errors

IOException - if the cap file cannot be opened

print_applet_status

public static void print_applet_status(PrintWriter out,
                                       Misc_protocols_stubs.Status_result stat)

Print applet status to out.

Parameters:

out - output channel

stat - applet status record

open_test_applet

public static void open_test_applet(CardChannel card_channel,
                                    Test_protocols test_protocols,
                                    PrintWriter out)
                             throws CardException,
                                    IOException

Select the test applet on the card. (Re)Install the applet if it cannot be selected or if its timestamp (from the status protocol) differs from the cap-file's last modification date.

Parameters:

card_channel - channel to the card

test_protocols - the protocol array instance

out - progress and debug channel, if null, only minimalistic messages are printed on System.out.

Throws:

CardException - on communication errors

IOException - if the cap file cannot be accessed

main_ex

public static void main_ex(String[] args)
                    throws CardException,
                           IOException

Real main method. Performs all the following actions:

• parses the command line
• initializes the host instance of the protocols
• establishes a connection to the card or emulator
• reinstalls the applet if requested
• runs the requested test and measurments

Parameters:

args - the complete command line options

Throws:

CardException - for card communication errors

IOException - on IO errors (eg, for the applet cap file)

main

public static void main(String[] args)
                 throws CardException,
                        IOException

Entry point. Does nothing but calling main_ex.

Parameters:

args - the complete command line options

Throws:

IOException - on IO errors (eg, for the applet cap file)

CardException - for communication errors