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-versionOr
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:
Theconverter.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:
Table 5-2 Converter Command Line Arguments
Option | Description |
---|---|
|
Prints help message. |
|
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. |
|
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. |
|
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. |
|
Sets the root directory for output. |
|
Generates the optional debug component of a CAP file. If the Note: To generate the debug component, you must first compile your class files with the Java compiler's |
|
Uses the token mapping from the pre-defined export file of the package being converted. The Converter looks for the export file in the |
|
Specifies the root directories in which the Converter looks for export files. The separator character for multiple paths is the semicolon ( |
|
Instructs the Converter to support the 32-bit integer type. |
|
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 |
|
Suppresses all banner messages. |
|
Suppresses the verification of input and output files. For more information on file verification, see Verification of Input and Output Files . |
|
Instructs the Converter not to report warning messages. |
|
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. |
|
Enables verbose output. Verbose output includes progress messages, such as "opening file", "closing file", and whether the package requires integer data type support. |
|
Prints the Converter version string. |
|
Specifies to sign the output CAP file |
|
Keystore to use in signing |
|
Keystore password |
|
Keystore alias to use in signing |
|
Alias password |
|
Cannot be specified with 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 |
|
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 |
|
Cannot be used with 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). |
|
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 " |
- 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 |
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:
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> |
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:
|
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 |
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.
"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.