Working With CAP Files

C H A P T E R 7

One of the files generated by the Converter is the CAP file. The CAP file utilizes the JAR file format, and contains a set of components that describes a Java language package. In addition to the components, the CAP file also contains the manifest file META-INF/MANIFEST.MF, which can be used to improve distribution.

This chapter also describes how you can generate a CAP file from a given Java Card Assembly file using the capgen tool, and how you can produce an ASCII representation of a CAP file using the capdump tool.

Note - The capgen and capdump tools work only with CAP files generated with versions 2.2.2 and earlier of the Java Card development kit. This chapter contains a sample of the syntax used in CAP files as they apply to version 2.2.2 CAP files and related tools. The CAP file syntax has been updated in the Development Kit version 3.0.2 and this chapter deals primarily with the capgen and capdump tools and the earlier manifest file format that is still valid and supported with the 3.0.2 Classic Edition, but with these caveats in mind regarding using capgen and capdump.

CAP File v2.2.2 Manifest File Syntax

A CAP file utilizes the JAR file format, and contains a set of components that describe a Java language package. In addition to the components, the CAP file also contains the manifest file META-INF/MANIFEST.MF. The manifest file provides additional human-readable information regarding the contents of the CAP file and the package that it represents. This information can be used to facilitate the distribution and processing of the CAP file.

The information in the manifest file is presented in name:value pairs. These name:value pairs are described in TABLE 7-7.

TABLE 7-7 Name:Value Pairs in the `MANIFEST.MF` File
Name	Value
Java-Card-CAP-Creation-Time	Creation time of CAP file. For example: Tue Jan 15 11:07:55 PST 2006 The format of the time stamp is operating system-dependent.
Java-Card-Converter-Version	The version of the converter tool. For example: `1.3`.
Java-Card-Converter-Provider	Provider of the converter tool. For example: Sun Microsystems, Inc.
Java-Card-CAP-File-Version	CAP file major.minor version. For example: 2.1.
Java-Card-Package-Version	The major.minor version of package. For example: 1.0
Java-Card-Package-AID	AID for the package. For example: 0xa0:0x00:0x00:0x00:0x62: 0x03:0x01:0x0c:0x07
Java-Card-Package-Name	The fully-qualified package name in dot (.) format. For example: javacard.framework
Java-Card-Applet-<n>-AID	The AID for applet n. For example: 0xa0:0x00:0x00:0x00:0x62: 0x03:0x01:0x0c:0x07:0x05
Java-Card-Applet-<n>-Name	Simple class name for applet n. For example: MyApplet
Java-Card-Import-Package-<n>-AID	The AID for imported package n. For example: 0xa0:0x00:0x00:0x00:0x62: 0x00:0x01
Java-Card-Import-Package-<n>-Version	The major.minor version of imported package n. For example: 1.0
Java-Card-Integer-Support-Required	Can be `TRUE` or `FALSE`. The value is `TRUE` if the package requires integer support.

The properties in the manifest file include:

The names Java-Card-Applet-<n>-AID and Java-Card-Applet-<n>-Name refer to the same applet.

The converter assigns numbers for the Java-Card-Applet-<n>-NAME and Java-Card-Applet-<n>-AID names in sequential order, beginning with 1.

The names Java-Card-Imported-Package-<n>-AID and Java-Card-Imported-Package-<n>-Version refer to the same package.

The converter assigns numbers for the Java-Card-Imported-Package-<n>-AID and Java-Card-Imported-Package-<n>-AID names in sequential order, beginning with 1.

Sample Manifest File

The following code sample illustrates the manifest file that the Converter generates when it converts package jcard.applications. This package contains two applets, MyClass1 and MyClass2.

Manifest-Version: 1.0
Created-By: 1.3.1 (Sun Microsystems Inc.)
 
Java-Card-CAP-Creation-Time: Tue Jan 15 11:07:55 PST 2006
Java-Card-Converter-Version: 1.3
Java-Card-Converter-Provider: Sun Microsystems, Inc.
Java-Card-CAP-File-Version: 2.1
Java-Card-Package-Version: 1.0
Java-Card-Package-Name: jcard.applications
Java-Card-Package-AID: 0xa0:0x00:0x00:0x00:0x62:0x03:0x01:0x0c:0x07
Java-Card-Applet-1-Name: MyClass1
Java-Card-Applet-1-AID: 0xa0:0x00:0x00:0x00:0x62:0x03:0x01:0x0c:0x07:0x05
Java-Card-Applet-2-Name: MyClass2
Java-Card-Applet-2-AID: 0xa0:0x00:0x00:0x00:0x62:0x03:0x01:0x0c:0x07:0x06
Java-Card-Imported-Package-1-AID: 0xa0:0x00:0x00:0x00:0x62:0x00:0x01
Java-Card-Imported-Package-1-Version: 1.0
Java-Card-Imported-Package-2-AID: 0xa0:0x00:0x00:0x00:0x62:0x01:0x01
Java-Card-Imported-Package-2-Version: 1.1
Java-Card-Integer-Support-Required: TRUE

Generating a CAP File From a Java Card Assembly File

Use the capgen tool to generate a CAP file from a given Java Card Assembly file. The CAP file that is generated has the same contents as a CAP file produced by the Converter. The capgen tool is a backend to the Converter.

Running `capgen`

Command line syntax for capgen is as follows (see TABLE 7-8 for a description of the options):

capgen.bat [options] filename

Note - The file to invoke capgen is a batch file (capgen.bat) that must be run from a working directory of JC_CLASSIC_HOME\bin in order for the code to execute properly.

TABLE 7-8 `capgen` Command Line Options
Option	Description
`-help`	Prints a help message.
`-nobanner`	Suppresses all banner messages.
filename	Specifies the Java Card Assembly file.
`-o` filename	Allows you to specify an output file. If the output file is not specified with the `-o` flag, output defaults to the file `a.jar` in the current directory.
`-version`	Outputs the version information.

Producing a Text Representation of a CAP File

Use the capdump tool to produce an ASCII representation of a CAP file.

If you have a source release, you can localize locale-specific data associated with the capdump tool. For more information, see Chapter 14.

Running `capdump`

Command line usage of capdump is as follows where filename is the CAP file and there are no command line options, and output from the command is always written to standard output:

capdump.bat filename

Note - The file to invoke capdump is a batch file (capdump.bat) that must be run from a working directory of JC_CLASSIC_HOME\bin in order for the code to execute properly.