Using the Java Card Reference Implementation

The Java Card reference implementation is written in the C programming language and is called the C-language Java Card Runtime Environment (“C-language Java Card RE”). It is a simulator that can be built with a ROM mask, much like a real Java Card technology-based implementation. It has the ability to simulate persistent memory (EEPROM), and to save and restore the contents of EEPROM to and from disk files. Applets can be installed in the C-language Java Card RE. The C-language Java Card RE performs I/O via a socket interface, using the TLP-224 protocol, simulating a Java Card technology-compliant smart card in a card reader (CAD).

In version 2.2.1 of the Development Kit, the C-language Java Card RE is available as a 32-bit implementation. The 32-bit implementation gives you the ability to go beyond the 64KB memory access limitation that was present in previous releases. The 2.2.1 release does provide a 16-bit version of the C-language Java Card RE for backward compatibility with older applications.

Running the Java Card Runtime Environment

The 32-bit implementation of the C-language Java Card RE is supplied as prebuilt executables.

TABLE 17 – Name and Location of cref Executables
File Name	Description
`%JC_HOME%/bin/cref.exe`	32-bit implementation of `cref` for the Microsoft Windows 2000 platform.
`$JC_HOME\bin\cref`	32-bit implementation of `cref` for the Solaris or Linux platform.

Installer Mask

The Development Kit Installer, the Java Card virtual machine interpreter, and the Java Card platform framework are built into the installer mask. It can be used as-is to load and run applets. Other than the Installer, it does not contain any applets.

The C-language Java Card RE requires no other files to start proper interpretation and execution of the mask image’s Java Card bytecode.

Runtime Environment Command Line

Command line usage of C-language Java Card RE is the same on the Solaris, Linux, and Microsoft Windows 2000 platforms. The syntax is:

The output of the simulation is logged to standard output, which can be redirected to any desired file. The output stream can range from nothing, to very verbose, depending on the command line options selected.

Command-line Options

TABLE 18 – Runtime Environment Command Line Options
Option	Description
`-b`	Dumps a Byte Code Histogram at the end of the execution.
`-e`	Displays the program counter and stack when an exception occurs.
`-h`, `-help`	Prints a help screen.
`-i` <input filename>	Specifies a file to initialize EEPROM. Under the Solaris, Linux, and Microsoft Windows 2000 operating systems, file names must be single part--that is, there can be no spaces in the file name.
`-n`	Performs a trace display of the native methods that are invoked.
`-nobanner`	Suppresses the printing of a program banner.
`-nomeminfo`	Suppresses the printing of memory statistics when execution starts.
`-o` <output filename>	Saves the EEPROM contents to the named file. Under the Solaris, Linux, and Microsoft Windows 2000 operating systems, file names must be single part—that is, there can be no spaces in the file name.
`-p` <port number>	Connects to a TCP/IP port using the specified port number.
`-s`	Suppresses output. Does not create any output unless followed by other flag options.
`-t`	Performs a line-by-line trace display of the mask’s execution.
`-version`	Prints only the program’s version number. Do not execute.
`-z`	Prints the resource consumption statistics.

Obtaining Resource Consumption Statistics

The C-language Java Card RE provides a command line option (-z) for printing resource consumption statistics. This option enables the C-language Java Card RE to print statistics regarding memory usage once at startup and once at shutdown. Although memory usage statistics will vary among Java Card RE implementations, this option provides the applet developer with a general idea of the amount of memory needed to install and execute an applet.

The following output is obtained by running the demo2 demonstration program with the -z command line option.

cref -z 
Java Card platform version 2.2.1 C Reference Implementation Simulator (version 0.41) 
32-bit Address Space implementation - no cryptography support 
Copyright 2003 Sun Microsystems, Inc. All rights reserved. 
 
Memory configuration 
        Type    Base    Size    Max Addr 
        RAM     0x0     0x500   0x4ff 
        ROM     0x2000  0xa000  0xbfff 
        E2P     0x10020 0xffe0  0x1ffff 
 
        ROM Mask size =                 0x566b =        22123 bytes 
        Highest ROM address in mask =   0x766a =        30314 bytes 
        Space available in ROM =        0x4995 =        18837 bytes 
Mask has now been initialized for use 
        0 bytecodes executed. 
        Stack size: 00384 (0x0180) bytes,          00000 (0x0000) maximum used 
        EEPROM use: 05935 (0x172f) bytes consumed, 59569 (0xe8b1) available 
Transaction buffer: 00000 (0x0000) bytes consumed, 02560 (0x0a00) available 
Clear-On-Reset RAM: 00000 (0x0000) bytes consumed, 00256 (0x0100) available 
Clear-On-Dsel. RAM: 00000 (0x0000) bytes consumed, 00128 (0x0080) available 
C-language Java Card RE was powered down. 
   891495 bytecodes executed. 
       Stack size: 00384 (0x0180) bytes,          00244 (0x00f4) maximum used 
        EEPROM use: 14839 (0x39f7) bytes consumed, 50665 (0xc5e9) available 
Transaction buffer: 00000 (0x0000) bytes consumed, 02560 (0x0a00) available 
Clear-On-Reset RAM: 00168 (0x00a8) bytes consumed, 00088 (0x0058) available 
Clear-On-Dsel. RAM: 00026 (0x001a) bytes consumed, 00102 (0x0066) available

The demo2 demonstration program downloads and installs several applets and performs several transactions using a subset of the installed applets. Statistics are provided regarding the following resources: EEPROM, transaction buffer, stack usage, clear-on-reset RAM, and clear-on-deselect RAM. The statistics are printed twice, once at C-language Java Card RE start up and once when it shuts down.

This particular example shows the resources used to download and install a set of applications and execute several transactions. More fine-grained statistics could be obtained by limiting the actions during a single session. For example, using a single session to download one application would provide information regarding the resources needed to process the application download. The EEPROM contents at the end of the session could be saved using the -o option, and subsequent sessions could be used to measure resource usage for other actions, such as applet installation and execution.

In addition to the command line option, the Java Card API provides programmatic mechanisms for determining resource usage. For more information on these mechanisms, see the javacard.framework.JCSystem.getAvailableMemory() method in the Application Programming Interface for the Java Card™ Platform, Version 2.2.1 .

Reference Implementation Limitations

Input and Output

The C-language Java Card RE performs I/O via a socket interface, using the TLP-224 protocol, simulating a Java Card technology-compliant smart card in a card reader (CAD). Use apdutool to read script files and send APDUs via a socket to the C-language Java Card RE. See "apdutool Examples" for details. Note that you can have the C-language Java Card RE running on one workstation and run apdutool on another workstation.

Working with EEPROM Image Files

You can save the state of EEPROM contents, then load it in a later invocation of the C-language Java Card RE. To do this, specify an EEPROM image or “store” file to save the EEPROM contents.

Use the -i and -o flags to manipulate EEPROM image files at the cref command line:

The -i and -o flags do not conflict with the performance of other option flags. File names used with the -i and -o flags flags must not contain spaces.

The commit of EEPROM memory changes during the execution of the C-language Java Card RE is not affected by the -o flag. Neither standard nor error output is written to the output file named with the -o option.

The following examples show how the -i and -o option flags can be used in a variety of useful execution scenarios.

Input EEPROM Image File

The C-language Java Card RE attempts to initialize simulated EEPROM from the EEPROM image file named e2save. No output file will be created.

Output EEPROM Image File

The C-language Java Card RE writes EEPROM data to the file e2save. The file will be created if it does not currently exist. Any existing EEPROM image file named e2save is overwritten.

Same Input and Output EEPROM Image File

The C-language Java Card RE attempts to initialize simulated EEPROM from the EEPROM image file named e2save, and during processing, saves the contents of EEPROM to e2save, overwriting the contents. This behavior is much like a real Java Card technology-compliant smart card in that the contents of EEPROM is persistent.

Different Input and Output EEPROM Image Files

The C-language Java Card RE attempts to initialize simulated EEPROM from the EEPROM image file named e2save_in, and during C-language Java Card RE processing, writes EEPROM updates to a EEPROM image file named e2save_out. The output file will be created if it does not exist. Using different names for input and output EEPROM image files eliminates much potential confusion. This command line can be executed multiple times with the same results.

The Default ROM Mask

Version 2.2.1 of the Java Card reference implementation provides a 32-bit version of the C-language Java Card RE executable: cref.exe for the Microsoft Windows 2000 platform, and cref for the Solaris or Linux platform. These executables contain only the Java Card RE packages, and an installer applet.

Chapter 11