Running the Converter

To run the Converter:

For the compact mode, enter either of the following commands at the command line to invoke the Converter:

converter.bat [options] package-name package-aid major-version.minor-version

Or

converter.bat -config <filename>
For the extended mode, enter the following command at the command line to invoke the Converter:

converter.bat -config <filename.json>
For showing the usage, enter either of the following commands at the command line to invoke the Converter:

converter.bat -help

Or

converter.bat -help JSON

Note:

The converter.bat file used to invoke the Converter is a batch file that you must run from a working directory of JC_HOME_TOOLS\bin in order for the code to execute properly.

The Converter command line options described in Table 5-2 allow you to:

Specify the root directory where the Converter looks for classes.
Specify the root directories where the Converter looks for export files.
Use the token mapping from pre-defined export files of the packages being converted. The Converter looks for the export files in the export path.
Set the applet AID and the class that defines the install method for the applet.
Specify the root directories where the Converter outputs files.
Specify that the Converter outputs one or more of the following files:
- CAP file
- JCA file
- EXP export file
Identify that a package is used as a mask.

When a package is used as a mask, restrictions on native methods are relaxed.
Specify support for the 32-bit integer type.
Enable generation of debugging information.
Turn off verification (the default of input and output files. Verification is the default.).
Specify a list of file paths from where the static resources are loaded by the Converter, if any.
Specify the target Java Card platform version on which the CAP file generated should be loaded, if it is not the newest released version of the Java Card platform.

When the Converter runs, it performs the conversion process in the following sequence:

Loads the packages - If the exportmap option is set for any of the packages, the Converter loads that package from the export path (see Specifying an Export Map). It loads the class files of the Java packages and creates a data structures to represent these packages.
Subset checking - Checks for unsupported Java features in class files.
Conversion - Checks for consistency between the applet AIDs, package AIDs, CAP file AID (if present), and the imported package AIDs.
Reference Checking - Checks that all references are valid, internal referenced items are defined in the packages belonging to the CAP file, and import items are declared in the export files (see Using Export Files).

The Converter creates the JcImportTokenTable to store tokens for import items (class, methods, and fields). If the Converter only generates export files, it does not check private APIs and byte code. Also included is a second round of subset checking that operations do not exceed the limitations set by the JCVM specification.
Optimization - Optimizes the byte code.
Generates output - Builds and outputs one EXP export file for each package and one JCA file for each package, checks for each package version in the export file against the version specified in the command line or in the config file. If the -exportmap option is used for a specific package in the command line or config file, the export file specified in the command line for that package must represent the same version as that of the package. The converter does not support upgrading the export file version.

Before writing the export files and JCA files, the Converter determines the output file path. The Converter assumes the output files are written into the directory:

root_dir\package_dir\javacard

By default, the root_dir is the class root directory specified by the -classdir option. You can specify a different root_dir by using the -d option.

The Converter generates only one CAP file. In the compact mode, the CAP file contains only one package and it is written to the path mentioned into the preceding example (root_dir\package_dir\javacard). In the extended mode, the CAP file contains one or more packages and it is written into the following directory:

output_dir\CAP_name\javacard

By default, the output_dir is the directory where the JSON configuration file, which used in the extended mode, is located. You can specify a different output_dir by defining a value for the outputDir field in the JSON configuration file.

Table 5-2 Converter Command Line Arguments

Option	Description
`-help`	Prints help message.
`-help JSON`	Prints a JSON definition file (schema), for the JSON configuration file to be used in extended mode. The JSON schema contains all of the fields that can be defined, the hierarchy of fields, field types, field descriptions, optionality, sample values, default values, and descriptions. The schema can be used (using various tools) for validating configuration files used for generating extended CAP files.
package-name	Fully-qualified name of the package to convert.
package-aid	5- to 16-decimal, hex or octal numbers separated by colons. Each of the numbers must be byte-length.
major-version minor-version	User-defined version of the package.
`-applet` AID class_name	Sets the default applet AID and the name of the class that defines the applet. If the package contains multiple applet classes, this option must be specified for each class.
`-classdir` root-directory-of-class hierarchy	Sets the root directory where the Converter looks for classes. If this option is not specified, the Converter uses the current user directory as the root.
`-d` root-directory-for-output	Sets the root directory for output.
`-debug`	Generates the optional debug component of a CAP file. If the `-mask` option is also specified, the file `debug.msk` is generated in the output directory. Note: To generate the debug component, you must first compile your class files with the Java compiler's `-g` option.
`-exportmap`	Uses the token mapping from the pre-defined export file of the package being converted. The Converter looks for the export file in the `exportpath`.
`-exportpath` list-of-directories	Specifies the root directories in which the Converter looks for export files. The separator character for multiple paths is the semicolon (`;`). If this option is not specified, the Converter sets the export path to the Java `classpath`.
`-i`	Instructs the Converter to support the 32-bit integer type.
`-mask`	Indicates that the converted code is intended to be used to create a binary mask, so restrictions on native methods are relaxed. If you have a source release, you can specify this option to generate a mask out of this package using maskgen. This option can be used in conjunction with `-out CAP`, only if `-debug` is selected, to typically generate a CAP with debug component and use it to debug platform classes. Such CAP is not intended to be loaded on a platform and will fail verification if it contains native methods.
`-nobanner`	Suppresses all banner messages.
`-noverify`	Suppresses the verification of input and output files. For more information on file verification, see Verification of Input and Output Files .
`-nowarn`	Instructs the Converter not to report warning messages.
`-out` [CAP] [EXP] [JCA]	Instructs the Converter to output the CAP file, and/or the export file, and/or the Java Card Assembly file. By default (if this option is not specified), the Converter outputs a CAP file and an export file.
`-v`, `-verbose`	Enables verbose output. Verbose output includes progress messages, such as "opening file", "closing file", and whether the package requires integer data type support.
`-V`, `-version`	Prints the Converter version string.
`-sign`	Specifies to sign the output CAP file
`-keystore` value	Keystore to use in signing
`-storepass` value	Keystore password
`-alias` value	Keystore alias to use in signing
`-passkey` value	Alias password
`-useproxyclass`	Cannot be specified with `keepproxysource`. Builds CAP files as usual in the specified output directory using the existing class files of the application and existing class files of the associated proxy sub-package. New proxy classes are not created. Provides a way for the application developer to build a CAP file with customized proxy files. This option requests the converter to take the class files of the application package and the class files of the co-located proxy sub-package to build a new CAP file. The classes in the application package are converted into new`.cap` components. New descriptors are created. Dynamically-loaded-classes attributes need to be recomputed based on the new Proxy class file names.
`-usecapcomponents`	Specifies that the converter retain the specified user supplied CAP components instead of generating them in the final CAP bundle. The input format is as follows: application-classes-dir`/`application-classes`/javacard/*.cap`
`-keepproxysource` directory	Cannot be used with `-useproxyclass`. Creates the proxy source files and other stub files in the specified directory. The converter also builds CAP files as usual in the specified output directory. Supports customizing the proxy files generated by the converter. Requests the converter retain the intermediate proxy class source code in the specified directory and the source code of the associated stub classes representing the dependent external classes using the hierarchical directory structure of the Java package name(s).
`-resourcepath` <id1>`:`<resource_path1>`,`<id2>`:`<resource_path2>`,...`	Specifies the list of static resources that can be loaded into the CAP file that is generated by the Converter (in the compact mode). The entries in the list are delimited by the "`,`" character. Each entry in the list contains two parameters delimited by the "`:`" character. The first parameter is an integer representing the id of the static resource and the second parameter is the path to the file, which has the actual binary content for the static resource. The path must be a valid path to a file on the disk for which the Converter should have read access.
`- target` <platform version>	Specifies the Java Card platform version on which the CAP file that is generated by the Converter (in the compact mode) is loaded. If the target is not specified in the converter, the default value would be the latest release version, that is, 3.1.0. Other valid values for the current release are, 3.0.4 and 3.0.5. If you are not using the target option or if you are using a target greater than 3.0.5, the 2.3 version CAP files are generated. Else, 2.2 or 2.1 version CAP files are generated, depending on the features (debugging or RMI). Also, for the current release, the platform api_export_files directory is not required in the `-exportpath` option. The directory for the platform API export files is chosen based on the `-target` option as follows: JC_HOME_TOOLS`\`api_export_files_<platform version>.

Using Delimiters with Command Line Options

To use delimiters with command line options:

Add a double quote (") around command line option arguments that contain a space symbol.

In the following sample command line, the converter checks for export files in the.\export files, JC_HOME_TOOLS\api_export_files_3.0.5, and current directories.

converter -target 3.0.5 -exportpath ".\export files";.

MyWallet 0xa0:0x00:0x00:0x00:0x62:0x12:0x34 1.0

Using a Command Configuration File in Compact Mode

Instead of entering all of the command line arguments and options on the command line, you can include them in a text-format configuration file. This is convenient if you frequently use the same set of arguments and options.

To use a command configuration file:

Enter the command line arguments and options in a text-format configuration file.
Use double quote (") delimiters for the command line options that require arguments in the configuration file.

You must use double quote (") delimiters for the command line options that require arguments in the configuration file. For example, if the options from the command line example used in Using Delimiters with Command Line Options were placed in a configuration file, the result would look like this:

converter -target 3.0.5 -exportpath ".\export files";.

MyWallet 0xa0:0x00:0x00:0x00:0x62:0x12:0x34 1.0
Specify the configuration file in the command line when you run the Converter.

The syntax to specify a configuration file is:

converter –config configurationfile name

The configurationfile name argument contains the file path and file name of the configuration file.

If the name of the configuration file has the .json extension, the extended mode is activated, else the compact mode is used.

Using a JSON Configuration File for Converter in the Extended Mode

In the extended mode, the Converter tool generates extended CAP files from one or multiple Java packages.

To run the Converter in the extended mode, use a JSON configuration file with the -config option. The JSON file includes fields and options that are used in the compact mode, however most of these fields and options are associated with each package contained in the CAP file.

The configuration in the JSON file is a JSON object with a single field, inputConfig. All other fields are defined inside this field at different levels of hierarchy. The description of levels follow:

CAP file - Includes options for the entire CAP file.
Package - Includes options specific to each package in the CAP file.
Applet - Includes options specific to each applet in a package.
Static resource - Includes options specific to each static resource in the CAP file.
Sign - Includes options specific to the signing feature of the CAP file.

Table 5-3 JSON File Options for Converter

Option	Level	Description
`CAP_AID`	CAP file	The AID of the CAP file available as an executable load module.
`CAP_name`	CAP file	The name of the CAP file generated by the Converter. On the disk, the name of the CAP file would look like <CAP_name>`.cap` and all the components inside the CAP file will be located in the <CAP_name>`/javacard` directory.
`CAP_version`	CAP file	The user-defined version of the CAP file as an executable load module.
`debug`	CAP file	Generates the optional debug component of a CAP file. The same rules apply to the compact mode.
`noverify`	CAP file	Suppresses the verification of input and output files. The same rules apply to the compact mode.
`verbose`	CAP file	Enables verbose output.
`outputDir`	CAP file	Sets the root directory for output of the CAP file.
`nowarn`	CAP file	Instructs the Converter not to report warning messages.
`nobanner`	CAP file	Suppresses all banner messages.
`useCapComponents`	CAP file	Instructs the Converter to retain the user-defined CAP components instead of generating them in the final CAP bundle. The input format is as follows: <CAP_name>`/javacard/*.cap`
`CAP`	CAP file	Instructs the Converter to write or not to write the CAP file to the disk.
`integer`	CAP file	Instructs the Converter to support the 32-bit integer type.
`exportPath`	CAP file	Specifies the root directories in which the Converter looks for the export files. The same rules apply for the compact mode. Note that the Java Card API framework export files directory is not required and `-traget 3.1.0` option is used automatically in the extended mode.
`inputPackages`	CAP file	An array of JSON objects, each representing the configuration for the Java package to be converted and added to the CAP file.
`staticResources`	CAP file	An array of JSON objects. Each representing the configuration for a static resource to be loaded on the CAP file.
`sign`	CAP file	A JSON object representing the configuration for signing the CAP file, which is generated by the Converter.
`PackageAID`	Package	The AID of the package as defined in the compact mode.
`PackageName`	Package	The fully-qualified name of the package as defined in the compact mode.
`baseDir`	Package	Sets the root directory from where the Converter looks for the classes in the package. If this option is not specified, the Converter uses the location of the configuration file as the root directory.
`outputDir`	Package	Sets the root directory for output of the JCA and EXP files generated for this package. The same rules apply for the compact mode. If this option is not set, the `baseDir` value is taken.
`public`	Package	Specifies if a package is exported or not. The values and its description follow: If the value is set to `true`, and the package is a library, then all the public classes and interfaces are exported. If the value is set to `true`, and the package is an applet package, then only shareable interfaces are exported. If the value is set to `false`, nothing from the package is exported. Also, the AID field of the package will not appear in the header component of the CAP file and the AID field is ignored. Because of this, in the generated JCA files, the AID of a private package will have a random value. For a private package, the EXP file is not generated and the value of the EXP file is ignored.
`version`	Package	The user-defined version of the package as defined in the compact mode. If the package is private and the `exportmap` field is set to `false`, the `version` field is ignored.
`JCA`	Package	Instructs the Converter to write or not to write the JCA file to the disk for the package.
`EXP`	Package	Instructs the Converter to write or not to write the EXP file to the disk for the package. If the package doesn't have an export component (if the package is private or an applet package with no shareable interfaces), the EXP file is not generated. Therefore, the `EXP` field is ignored.
`exportmap`	Package	Uses the token mapping from the predefined export file of the package. The Converter looks for the export file in the given `exportpath` at the CAP file level. If this field is set to `false` and the package is private, the `version` field is ignored.
`applets`	Package	An array of JSON objects. Each representing the configuration for a Java Card applet contained in this package.
`ClassAID`	Applet	Specifies the AID of the applet.
`ClassName`	Applet	Specifies the fully-qualified Java class name for this applet.
`id`	Static Resource	An integer representing the identification number for the static resource. The static resource IDs must be unique across the CAP file.
`file`	Static Resource	A valid system path to an existent and accessible file on the disk. The contents of this file is loaded as binary data in the CAP file for the static resource.
`keystore`	Sign	The keystore used in signing.
`storepass`	Sign	The keystore password.
`alias`	Sign	The keystore alias used in signing.
`passkey`	Sign	The alias password.

Handling Relative Paths

In the JSON configuration file, all the fields that have values for the paths to directories or files on disk, support relative paths.

These fields include: outputDir, baseDir, exportPath, and file. All the relative paths are defined relative to the directory in which the JSON configuration file is located.

For example, the static resources are defined as follows:

"staticResources":[{
			"id" : 1,
			"file" : "staticres\\static1.res"
		}, {
			"id" : 2,
			"file" : "staticres\\static2.res"
		}]

If the JSON configuration file is in the following location:

C:\Users\Test

Then the Converter finds the data for the static resources in the following locations:

C:\Users\Test\staticres\static1.res

C:\Users\Test\staticres\static2.res

This applies for any input or output relative path directory. In case of a list of paths, like the exportPath field, the preceding statements apply for each path in the list.

Converter JSON Configuration File Sample

The Converter JSON configuration file sample follows:

{
	"inputConfig": {
		"CAP_AID": "01:02:03:04:05:10",
		"CAP_name": "hellosample",
		"CAP_version": "1.0",
		"debug": true,
		"noverify": false,
		"verbose": true,
		"outputDir": "thecapfile",
		"exportPath": ".;.\\package1",
		"inputPackages": [{
			"baseDir": "package1",
			"PackageName": "com.lib",
			"PackageAID": "01:02:03:04:05:06",
			"public": true,
			"JCA": true,
			"EXP": true,
			"exportmap": true,
			"version": "1.1"
		}, {
			"PackageName": "com.mine",
			"baseDir": "package2",
			"public": false,
			"JCA": true,
			"EXP": false,
			"exportmap": false,
		}, {
			"PackageName": "com.sample",
			"PackageAID": "01:02:03:04:05:07",
			"baseDir": "package3",
			"public": true,
			"version": "1.0",
			"JCA": true,
			"EXP": true,
			"exportmap": false,
			"applets": [{
				"ClassAID": "01:02:03:04:05:07:01",
				"ClassName": "com.sample.MyApplet"
			}]
		}],
		"staticResources":[{
			"id" : 1,
			"file" : "staticres\\static1.res"
		}, {
			"id" : 2,
			"file" : "staticres\\static2.res"
		}]
	}
}

Validating a JSON Configuration File

To validate a JSON configuration file, a JSON schema file must be generated using the -help JSON option.

To save the schema file, use the following command for the Microsoft Windows operating system:

converter.bat -help JSON > converter_schema.json

The saved schema file can be used as an input to the validation tools for validating the actual JSON configuration files that are passed to the Converter. See https://json-schema.org, for more information on JSON schema and validation.