C H A P T E R  5

Starting the Java Card Runtime Environment

The Connected Edition reference implementation is written in the Java and C programming languages and is called the C Java Card Runtime Environment (Java Card runtime environment). It is a simulator that can be built with a pre-built ROM mask, much as a Java Card technology-based implementation. It has the ability to simulate persistent memory (EEPROM) as well as to save and restore the contents of EEPROM to and from disk files. The Java Card runtime environment performs I/O via a socket interface, simulating the interaction with a card reader or host machine implementing HTTP(S) communication with the card reader or host machine.

The Java Card runtime environment is supplied by the development kit as the pre-built executable, cjcre.exe. The executable, cjcre.exe, is run from the command line.

This chapter includes the following sections:


Starting cjcre.exe from the Command Line

The Java Card runtime environment can be run from the command line by using the following command and options:

JC_CONNECTED_HOME\bin\cjcre.exe [options]

cjcre.exe Command Line Options

The following command line options are listed in order of their expected frequency of use (most frequently used to less frequently used):

Sets a new configuration file. The default is lib\config.properties.

Sets the port used to simulate the contacted interface for APDU. The default value for -contactedport is 9025.

Sets the APDU protocol on this port, either T=0 or T=1. The default value for the -contactedprotocol is T=1.

Port number used to simulate contactless interface. Default is 9026. The protocol, T=CL, cannot be changed.

Sets the Clear On Reset (COR) memory size in which a portion of RAM is dedicated to COR memory. The range of values that the Java Card runtime environment can accept from the command line is 2K to 8K. The default value is 4K. size is set as a value in bytes (2345) or kilobytes (2K).

Supplies a system property (such as -Dmyproperty=myvalue). System properties set in this manner can be retrieved using the API’s System.getProperty("myproperty") method. A maximum of 50 -D properties can be passed in the command line.

Runs cjcre in debug mode if you specify yes or true. Otherwise, the default is no and cjcre will not be run in debug mode. The values yes and true are equivalent. The values no and false are equivalent.

Sets the debug port where the Debug proxy communicates. Valid only when -debug is set to yes. The default value for -debugport is 7019.

Supplies the file name in which the EEPROM image is stored.

Configures the amount of EEPROM used. size is set as a value in bytes (2345), kilobytes (32K), or megabytes (4M). The specified size is rounded up to a multiple of 4. For example, a size specified at 253, is rounded up to 256.

The range of values that the Java Card runtime environment can accept from the command line is 1M to 32M. The default value used is 4M. The value required to run the samples is between 2M and 32M.

Enables Java code assertions (the assert keyword in Java code).

Displays only the log messages that match the level set by the -loggerlevel option.

Prints help and copyright messages.

Sets the HTTP port number on which cjcre will be listening. The default value for -httpport is 8019.

Sets the type of log messages output. All log messages up to the specified level are displayed.

Configures the amount of RAM used. size is set as a value in bytes (2345), kilobytes (32K), or megabytes (4M).

The range of values that the Java Card runtime environment can accept from the command line is 64K to 32M. The default value used is 1M. The value required to run the samples is between 128K and 32M.

Restores the VM state from the previously saved EEPROM image and continues VM execution. When -resume is specified, other options such as -ramsize and -e2psize are ignored and the corresponding values are obtained from the EEPROM image. However, the debug related options (-debug, -debugport, and -suspend) must be specified along with -resume to resume the VM in debug mode. The range is 256 bytes to 8K.

Suspends the threads at cjcre startup if set to yes or true. The default is yes. The values yes and true are equivalent. However, yes and true are valid only when -debug is also set to yes or true. The values no and false are equivalent.

Displays version information.

Sets a single configuration property such as:
-Xmyproperty=myvalue

System properties set in this manner can be retrieved using the API’s System.getProperty("myproperty") method. A maximum of 50 -D properties can be passed in the command line. These are visible using JCRuntime.getConfigProperty().


Java Card Runtime Environment Configuration Files

If you installed the development kit source bundle, the configuration files for the Java Card runtime environment (config.properties and system.config) files are located in the lib folder. These configuration files contain internal configuration information that must not be changed unless specified. Java Card runtime environment execution requires properly configured config.properties and system.config files. Incorrect changes to these files will prevent execution of the Java Card runtime environment. See Chapter 12 for details on configuring the Java Card runtime environment.

If you installed the development kit binary bundle, you cannot change the configuration files for the Java Card runtime environment.


Adding Proprietary Packages

If you installed the development kit source bundle, you can add proprietary packages to the ROM mask for the Java Card runtime environment by building a custom cjcre.exe. See Chapter 13 for additional information and procedures.

If you installed the development kit binary bundle, you cannot add proprietary packages.