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
- The list of all currently used cpp
preprocessor directives
- The list of all currently used assert
tags
- 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
- {@link ds.ov2.util.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 {@code assert}.
On the card, expands to {@link ds.ov2.util.Misc#myassert
Misc.myassert}, which throws an {@link
javacard.framework.ISOException} with response
status {@link ds.ov2.util.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.
{@code ASSERT(x)} expands to {@code 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
{@link ds.ov2.bignat.Testbignat 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 {@link javacard.security.MessageDigest} or
{@link ds.ov2.util.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 {@link 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 {@link
ds.ov2.bignat.Bignat#montgomery_mult
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
{@link ds.ov2.bignat.Bignat#montgomery_mult montgomery_mult}
is sometimes skipped.
- OPT_SPECIAL_SQUARE
- Optimization. When defined makes a specially optimized method
for modular squaring, {@link
ds.ov2.bignat.Bignat#montgomery_square montgomery_square},
available.
- OV_MONT_RSA_APPLET
- Selects the configuration for the montgomerizing
RSA applet in the {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link 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
{@link 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 {@link 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.
{@link javacard.security.RandomData} on the card
and {@link java.util.Random} on the host.
- RSA_CARD
- Expands to either {@link ds.ov2.front.RSA_plain_card} or
{@link ds.ov2.front.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 {@link ds.ov2.front.RSA_card_protocol_stubs} or
{@link ds.ov2.front.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 {@link ds.ov2.front.RSA_card_debug_stubs} or
{@link ds.ov2.front.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 {@link ds.ov2.bignat.RSA_exponent} or
{@link ds.ov2.bignat.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
{@link ds.ov2.bignat.RSA_exponent_interface} cannot be used.
- SHIFT_LESSER
- Used internally to use {@link ds.ov2.bignat.Bignat#shift_lesser_debug
shift_lesser_debug} or
{@link ds.ov2.bignat.Bignat#shift_lesser shift_lesser}
inside {@link ds.ov2.bignat.Bignat#remainder_divide remainder_divide}.
- SHORT_SQUARED_RSA_MULT
- Name of the method used for short squaring multiplication in
the squaring applets. Expands to either {@link
ds.ov2.bignat.Bignat#short_squared_rsa_mult_2
Bignat.short_squared_rsa_mult_2} or {@link
ds.ov2.bignat.Bignat#short_squared_rsa_mult_4
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 {@link 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 {@link
ds.ov2.bignat.Bignat#squared_rsa_mult_2 squared_rsa_mult_2} or {@link
ds.ov2.bignat.Bignat#squared_rsa_mult_4 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 {@link 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 {@link ds.ov2.bignat.Bignat_array bignat arrays} and
{@link ds.ov2.bignat.Vector vecors}.
Currently used assert tags
There is no assert on Java Card, therefore the ASSERT macro is used, which eventually throws an {@link
javacard.framework.ISOException} on the card. The {@link
javacard.framework.ISOException} yields the special response
status {@link ds.ov2.util.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
- {@link ds.ov2.util.Card_protocol}
- 0x20-0x3F
- {@link ds.ov2.bignat.Bignat}
- 0xF0-0xFF
- reserved for ad-hoc debugging
Currently used {@link
ds.ov2.util.Response_status#OV_TEST_FAILED_00 OV_TEST_FAILED_00} tags
If the test applet detects an error it may throw an {@link
javacard.framework.ISOException} with the respose status {@link
ds.ov2.util.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 {@link
ds.ov2.test.Data_protocol_card#check_buffer
test/Data_protocol.check_buffer}.