Building the RI From Sources

C H A P T E R 13

This chapter describes how to build a customized Java Card 3 platform RI. This chapter is useful only if you have a source release of the develoment kit. The src folder under JC_CONNECTED_HOME contains all of the source files for the RI including VM code, and all tools (such as the packager and installer). You can modify or add to these files and build a cutomized Java Card 3 platform RI according to their specific requirements. The following actions are possible reasons a licensee might have for building a custom RI:

Add additional classes or packages if a proprietary API or other implementation classes are used.
Fine tune the existing sources.
Update tools to work with target platform.
ROMize the applications. ROMizing masks the applications into the cjcre.exe .

This chapter contains the following sections:

Prerequisites to Building the RI

Before building the RI, the following software must be installed on the system:

MinGW
JDK 6
ANT

See Chapter 2 for more details on the pre-requisites.

Contents of JC_CONNECTED_HOME `/src` Folder

The following describes the contents of the src folder.

api - Contains all of the .java files required to build a custom RI. If a new package must be added, it is added under this folder.
tools - Contains the source code of all shipped tools organized in separate folders. To make a tool to work with a target platform, edit the code of the corresponding tool.
romized_apps - Contains the source files for the CardManager.
vm/c - Contains the source files of core VM.
vm/h - Contains the header files of core VM.
vm/lib - Contains configuration files config.properties and system . See Chapter 12 for additional details.
vm/ignore.list - If a class must be excluded from ROMization, add its name in this file.
build.xml - The main file used to build the tools and cjcre.exe in a single step.

Running the ROMizer Tool

When building a custom RI, the ROMizer tool takes system class files and application modules as input and creates a ROM image of these in an output ROM image file. The ROMizer tool converts the class files into C code, which is often called a ROM mask or simply a mask. For applications, the ROMizer tool stores non-class files in appropriate directories in the internal Java Card 3 platform filesystem, so that these files are available during the execution of the application. See Building a Custom cjcre.exe for detailed description of using the ROMizer tool.

Either of the following commands will run the Romizer tool:

romizer.bat -o ROM-output- filename -e EEPROM- filename -a apps-filename

romizer.bat --out ROM-output- filename --e2pfile EEPROM -filename --apps apps-filename

In the previous format examples, the following parameters are used:

-o (or --out) - Must be followed by the path to output file where the mask is written . For example:

--out MyROMJava.c

See Romizer Tool Output for a description of the ROM output file.

-e (or --e2pfile) - Must be followed by the path to the initial eeprom file . For example:

--e2pfile myeeprom.eeprom

-a (or --apps) - Must be followed by the path to the applications list file which contains the list of applications to be masked. For example:

--apps myapps.list
.

See Example Contents of Apps List File for a description of the configuration file.

Apps list File Contents

The apps list file contains information about applications that needs to be romized. All system classes and applications must be provided as input to the romizer in compressed files ( .jar , .war , or .zip files).

Each application file must be specified in the apps list file on a new line. Each application module entry in the configuration file must provide additional information as noted in the following format example:

application-module -t <web|classic-applet|extended-applet|classic-lib|extension-lib> -s signature-file -n module-name

In the previous example, the following parameters are used:

application-module is the .jar , .war , or .zip application module file.
-t followed by web , classic_applet, extended_applet, classic-lib , or extension-lib to identify the type of application being romized.
-s followed by the name of the properties file that contains the BASE64 encoded certificate and signature, where signature-file represents the file name.

This file is a simple properties file containing the following properties as name-value pairs:

signature = base64 encoded signature
certificate = certificate to validate this group and digest

-n followed by the module name that will be referenced by cjcre.exe for this application module.

The following is an example of an entry in the configuration file:

HelloWorld.war -t web 	-s mykey1.txt -n helloapp

Example Contents of Apps List File

The following is an example of the contents of an apps list file:

HelloWorld.war -t web 	-s key1.txt -n helloapp

GCFClient.war -t web -s key2.txt -n gcfapp

Romizer Tool Output

The output created by running the Romizer tool is a preliminary EEPROM file and a C language source file that contains the ROM image of the input file including the following:

Java class files that contain the API implementation
Implementation of containers
Applications selected by the user for romization

Building a Custom `cjcre.exe`

The build.xml provided in the src folder build everything including tools and cjcre.exe . This section gives details on how the cjcre.exe is generated.

Developers can modify the RI by adding or modifying the reference implementation code and using the ROMizer tool. RI consists of . java and C source files. The core VM is written in C programming language and rest of the API and supported implementation is written in the Java programming language. The ROMizer tool converts the class files into C code, which is often called the ROM mask or simply the mask. Then all the C source code is compiled to an executable to generate cjcre.exe.

The ROM image can include any supported application files (web, extended-applet, classic-applet, extension library, and classic library). ROMized applications can be instantiated without requiring download after the runtime environment starts up. The ROMizer tool takes system class files and application module as input and creates a ROM image of these in an output ROM image file.

For applications, the ROMizer tool stores the non-class files in appropriate directories in the internal Java Card 3 platform filesystem, so that these files are available during the execution of the application.

The following diagram illustrates the procedure of building the cjcre.exe from sources.

EXAMPLE 13-1 Building cjcre.exe From Sources

Java files are compiled into class files using the javac compiler. Details of applications to be ROMized are listed in a text file. The class files and the list file are given as input to the romizer.bat tool (see Preprocessor Symbols to Customize the VM). By default romizer.bat generates ROMJava.c , a C file that contains the information about all classes and applications.

The GNU C compiler ( gcc ) is used to build the final executable. The generated ROMJava.c and the rest of the C files are compiled using gcc , which generates cjcre.exe . Use the provided ANT build file to build custom cjcre.exe . See Build a Custom RI.

Preprocessor Symbols to Customize the VM

The following preprocessor symbols can be used to customize the Java Card VM:

INCLUDEDEBUGCODE=0
TRACE_EXCEPTIONS_NATIVE=1
INCLUDE_FIREWALL_DEBUG_CODE=0
ENABLE_JAVA_DEBUGGER=1

Enables the kdwp code. Default is 1. If set to 0, then cjcre can not be used to debug the applications.

APDU_PROTOCOL_T=0

Controls the protocol that will be supported by cjcre. default is t=0. Valid values are 0, 1 for T=0, T=1 respectively.

APDU_INTERFACE=0

Contacted or contactless or both. Valid values are 0, 1, 2 for contacted, contactless and Dual respectively

Build a Custom RI

1. Edit the files or add more files.

2. Update the tools source code if required.

3. From command line navigate to the src folder and run the ant command.

If there is a apps list file that contains the list of applications for ROMization, set the property apps_file_for_romizer while running the ant as shown below.

	ant -Dapps_file_for_romizer=path-to-apps-file

The ant command creates the JC_CONNECTED_HOME\custom_build folder with a bin and lib folder under it.

The bin directory contains the new cjcre.exe and all of the other tool’s .bat files.
The lib folder contains the . jar files and config files.

JC_CONNECTED_HOME\custom_build\bin and JC_CONNECTED_HOME\custom_build\lib are similar to JC_CONNECTED_HOME\bin and JC_CONNECTED_HOME\lib , except that custom_build contains the binaries from the updated source code.

Test the Custom RI

Use the following command to run the new cjcre.exe file stored in JC_CONNECTED_HOME\custom_build\bin .

JC_CONNECTED_HOME\custom_build\bin\cjcre.exe [options]

See Chapter 5 for a description of the available options.

Files created as a result of running or building the custom RI are stored in the JC_CONNECTED_HOME \custom_build\bin and JC_CONNECTED_HOME \custom_build\lib directories. These directories are created the first time the RI is built and will be over written every time the RI is built.