Internal (private) documentation of the OV-chip 2.0 sources.

See:
Description

Packages

ds.ov2.bignat	Big integer library for Java Card, including a test frame.
ds.ov2.front	Frontoffice code for applet and host side, including a test frame.
ds.ov2.gui	Demonstrator with GUI.
ds.ov2.test	Test applet for OV-chip protocol layer and for ds.ov2.bignat functionality.
ds.ov2.util	OV-chip protocol layer, general APDU data types and other miscellaneous code.

Internal (private) documentation of the OV-chip 2.0 sources.

Overview

This is the API documentation of the OV-chip specific java sources that have been developed during the OV-chip 2.0 project.

The OV-chip 2.0 project is sponsored by the NLnet foundation, see the NLnet website and the project web pages.

For an introduction into the sources on a more general level see the OV-Chip 2.0 Hacker's Guide.

This page contains

1. The list of all currently used cpp preprocessor directives
2. The list of all currently used assert tags
3. The list of all currently used OV_TEST_FAILED_00 tags

CPP preprocessor directives

To achieve some level of platform independence many files in this source tree must be processed with the C preprocessor cpp, see the hackers guide for more details. Here is a list of all preprocessor directives that are used.

APDU_DOUBLE_DIGIT_TYPE

APDU_Serializable wrapper around DOUBLE_DIGIT_TYPE

APPLET_TESTFRAME

Defined in the IDL-compiler supported testframe that runs the applet code on a normal JVM. Enables special debug code that should only run in this test frame.

ASSERT

On the host, it behaves like a normal assertion, because it expands to assert. On the card, expands to Misc.myassert, which throws an ISOException with response status Response_status.OV_ASSERTION_00 if the condition is false.

On the card assertion evaluation can be disabled with NO_CARD_ASSERT. In the bignat test frame with NO_ASSERT.

ASSERT(x) expands to ASSERT_TAG(x, 0), which does the job.

ASSERT_TAG(condition, tag)

Same as ASSERT, except that on the card the tag is or-ed into the lower byte of the response status. A number of assert tags are already used, see the list below.

BIGNAT_TESTFRAME

When defined (inside the bignat testframe Testbignat) printing of debug info to System.out is enabled.

BIGNAT_USE_BYTE

when defined selects the byte/short configuration, when undefined selects the int/long configuration

BIGNAT_USE_INT

currently not used. However, for compatibility with future relases it is defined precisely when BIGNAT_USE_BYTE is undefined.

CARD_SIGNATURE_ALWAYS_ACCEPT

If defined, the resign protocol in the plain RSA applet does always accept the new signature without checking the acceptance condition. This is useful, for instance, when all computations yield wrong results, because for instance MONTGOMERY_MULT_SHORTCUT is defined.

CARD_TESTFRAME

Defined in all test applets. Enables test code to be run on the card. Implies that TESTFRAME and JAVACARD_APPLET is defined.

CREF_INSTALL_ARG_HACK

Enables workaround code to obtain applet-installation arguments inside the buggy sun emulators cref and jcwde.

DIGIT_TYPE

Expands to the type for one digit, byte for the byte/short configuration and int for the int/long configuration.

DOUBLE_DIGIT_TYPE

Expands to the type for a double digit, short for the byte/short configuration and long for the int/long configuration.

HOST_TESTFRAME

When defined enables code to be run inside a host test frame, such as printing intermediate values. Implies that TESTFRAME is defined and that JAVACARD_APPLET is undefined.

JAVACARD_APPLET

Switches between code variants for Java Card (when defined) and for the host (when undefiend).

JAVADOC

When defined, enables all methods. Used to ensure the documentation contains everything.

MESSAGE_DIGEST

Expands to either MessageDigest or Message_digest_wrapper. The former provides the SHA hash function on Java Card. The latter provides a drop-in replacement for the APPLET_TESTFRAME.

MONT_APPLET_TESTFRAME

Selects the configuration for the host test frame (linking applet and host code into one program) of the montgomerizing RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

MONTGOMERY_MULT_SHORTCUT

Incorrect optimization for Montgomery multiplication. When defined, the multiplication immediately returns one, regardless of the arguments. Useful for performance only tests ...

NO_ASSERT

When defined, disables assertion checking. Used only in the config file for the bignat test frame.

NO_CARD_ASSERT

When defined, disables assertion checking on the card. Used for larger assertion blocks, that cannot be packed into an expression. Apart from that it appears in several config files for disabling assertions.

OPT_DOUBLE_ADD

When enabled, the two additions inside montgomery_mult are combined in one loop. In my tests this apparent optimization slows down the code in the bignat test frame.

OPT_SKIP_DEVIDE

Optimization. When defined, the final division inside montgomery_mult is sometimes skipped.

OPT_SPECIAL_SQUARE

Optimization. When defined makes a specially optimized method for modular squaring, montgomery_square, available.

OV_MONT_RSA_APPLET

Selects the configuration for the montgomerizing RSA applet in the ds.ov2.front package. Only used in the cpp config file there.

OV_MONT_RSA_TEST_APPLET

Selects the configuration for the test version of the montgomerizing RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

OV_PLAIN_RSA_APPLET

Selects the configuration for the plain RSA applet in the ds.ov2.front package. Only used in the cpp config file there.

OV_PLAIN_RSA_TEST_APPLET

Selects the configuration for the test version of the plain RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

OV_SQUARE_RSA_APPLET

Selects the configuration for the squaring RSA applet in the ds.ov2.front package. Only used in the cpp config file there.

OV_SQUARE_RSA_TEST_APPLET

Selects the configuration for the test version of the squaring RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

OV_SQUARE4_RSA_APPLET

Selects the configuration for the square 4 RSA applet in the ds.ov2.front package. Only used in the cpp config file there.

OV_SQUARE4_RSA_TEST_APPLET

Selects the configuration for the test version of the square 4 RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

OV_TEST_APPLET

Selects the configuration for the test applet code in the ds.ov2.test package. Only used in the Makefile and the cpp config file there.

PACKAGE

When defined, expands to the package name. Used on the card to let classes be part of different applets and packages.

PLAIN_APPLET_TESTFRAME

Selects the configuration for the host test frame (linking applet and host code into one program) of the plain RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

PUBLIC

Expands to public on the host and to nothing on the card, to hide the class on the card but make it visible to different packages on the host.

RANDOM

Type of the random number source. RandomData on the card and Random on the host.

RSA_CARD

Expands to either RSA_plain_card or RSA_mont_card. This makes it possible to share all except one file between the plain and the Montgomerizing RSA applet.

RSA_CARD_PROTOCOL_STUBS

Expands to either RSA_card_protocol_stubs or RSA_card_protocol_test_stubs. The former talks directly to cards or emulators via the javax.smartcardio library. The latter invokes the step methods directly, see also APPLET_TESTFRAME

RSA_DEBUG_PROTOCOL_STUBS

Expands to either RSA_card_debug_stubs or RSA_card_debug_test_stubs. The former talks directly to cards or emulators via the javax.smartcardio library. The latter invokes the step methods directly, see also APPLET_TESTFRAME

RSA_EXPONENT

Expands to either RSA_exponent or Fake_rsa_exponent. The former computes exponents on the card with the help of the RSA cipher, the latter is a drop-in replacement for the APPLET_TESTFRAME. Only used in type declararations and constructor statements, where RSA_exponent_interface cannot be used.

SHIFT_LESSER

Used internally to use shift_lesser_debug or shift_lesser inside remainder_divide.

SHORT_SQUARED_RSA_MULT

Name of the method used for short squaring multiplication in the squaring applets. Expands to either Bignat.short_squared_rsa_mult_2 or Bignat.short_squared_rsa_mult_4

SQUARE_APPLET_TESTFRAME

Selects the configuration for the host test frame (linking applet and host code into one program) of the squaring RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

SQUARED_RSA_MULT

Name of the method used for squaring multiplication in the squaring applets. Expands to either squared_rsa_mult_2 or squared_rsa_mult_4.

SQUARE4_APPLET_TESTFRAME

Selects the configuration for the host test frame (linking applet and host code into one program) of the square 4 RSA applet in the ds.ov2.front package. Only used in the Makefile and the cpp config file there.

TESTFRAME

Defined whenever one of CARD_TESTFRAME or HOST_TESTFRAME is defined for code that has to go into each testframe.

USE_SQUARED_RSA_MULT_4

Defined for the square 4 applet and host test frame, undefined for the squaring applet and host test frame. Distinguishes between these two squaring applets, see also SQUARE_RSA_MULT, SHORT_SQUARED_RSA_MULT

VARIABLE_SIZE_BIGNATS

When defined enables code for resizing Bignats, and changing the length of bignat arrays and vecors.

Currently used assert tags

There is no assert on Java Card, therefore the ASSERT macro is used, which eventually throws an ISOException on the card. The ISOException yields the special response status Response_status.OV_ASSERTION_00, where the lower 8 bit of the response status may carry additional information about the assertion. These lower 8 bits are called the assert tag.

For the ASSERT macro the assert tag is always zero. The ASSERT_TAG macro takes an extra argument for the assert tag. The assert tags uniquely identify an assertion statement. The following list shows the currently used assert tag values and the classes in which they appear.

0x01-0x10

Card_protocol

0x20-0x3F

Bignat

0xF0-0xFF

reserved for ad-hoc debugging

Currently used OV_TEST_FAILED_00 tags

If the test applet detects an error it may throw an ISOException with the respose status Response_status.OV_TEST_FAILED_00, where the lower byte provides additional information about which test failed. The following list shows the currently used tags.

0x01

Data transmission problem detected in the tests of the OV-chip protocol layer. See test/Data_protocol.check_buffer.