|C H A P T E R 10|
Using the Reference Implementation
The Java Card platform reference implementation is written in the C programming language and is called the C-language Java Card Runtime Environment ("C-language Java Card RE") or cref. 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, simulating the interaction with a card reader implementing T=1, T=CL, or T=0 communications with the card reader (CAD).
The C-language Java Card RE supports the following:
In version 2.2.2 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 version 2.2.2 release does provide a 16-bit version of the C-language Java Card RE for backward compatibility with older applications.
Also in version 2.2.2, the C-language Java Card RE can be built to support a variety of protocols. It can be built to support T=0 and T=1 in single interface mode, or T=1/T=CL in dual concurrent interface mode.
The 32-bit implementation of the C-language Java Card RE, cref, featuring the T=1/T=CL dual concurrent interface is supplied as a prebuilt executable.
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.
Command line usage of C-language Java Card RE is the same on the Solaris, Linux, and Microsoft Windows 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.
The options are case-sensitive.
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.
Java Card platform version 2.2.2 C Reference Implementation Simulator (version 0.41)
32-bit Address Space implementation - no cryptography support
Copyright 2005 Sun Microsystems, Inc. All rights reserved.
T=1 / T=CL Dual interface APDU protocol (ISO 7816-3)
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.2.
The C-language Java Card RE performs I/O via a socket interface, simulating the interaction with a card reader implementing T=1, T=CL, or T=0 communications with the card reader.
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.
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.
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.
cref -i e2save
The C-language Java Card RE attempts to initialize simulated EEPROM from the EEPROM image file named e2save. No output file will be created.
cref -o e2save
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.
cref -i e2save -o e2save
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 are persistent.
cref -i e2save_in -o e2save_out
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.
Note - Be careful naming your EEPROM image files. The C-language Java Card RE will overwrite an existing file specified as an output EEPROM image file. This can, of course, cause a problem if there is already an identically named file with a different purpose in the same directory.
Version 2.2.2 of the Java Card platform reference implementation provides a 32-bit version of the C-language Java Card RE executable: cref.exe for the Microsoft Windows platform, and cref for the Solaris or Linux platform. These executables contain only the Java Card RE packages and an installer applet.