[Java Card - SmartCard] Developing a Java Card Applet

http://www.oracle.com/technetwork/java/javacard/applet-136808.html

Developing a Java Card Applet

By Ed Ort, Release 2.1.2, August 2001

Source: Wallet.java

The January 2001 article Writing a Java Card Applet introduced smart cards, gave a brief overview of Java Card technology, and showed how to use that technology to write a Java Card applet. After you write a Java Card applet, you're ready to prepare it for execution in a Smart Card that implements the Java Card runtime environment. Preparing a Java Card applet for execution involves a number of steps, such as converting it to a runtime format and testing it in various simulated environments. This article refers to these steps collectively as "developing a Java Card applet," and shows you how to perform each step in the process.

Here are the topics covered in this article:

Using the Java Card Development Kit 
Setting Up Your Environment 
Compiling a Java Card Applet 
Testing a Java Card Applet in the JCWDE 
     Starting the JCWDE 
     Running the APDUTool Utility 
     Debugging a Java Card Applet 
Converting a Java Card Applet 
     What Happens During Conversion? 
     The CAP File 
     The Export File 
     Verifying the Integrity of CAP and Export Files 
     The JCA File 
Generating a Mask File 
Installing a CAP file 
     Running the Off-Card Installer 
     The Script File Produced by the Off-Card Installer 
     Tailoring the Script File 
What Next? 
Reference 
     jcwde Command Syntax 
     apdutool Command Syntax 
     converter Command Syntax 
     verifycap Command Syntax 
     verifyexp Command Syntax 
     verifyrev Command Syntax 
     capgen Command Syntax 
     maskgen Command Syntax 
     scriptgen Command Syntax 
For More Information

Using the Java Card Development Kit

Use the Java Card 2.1.2 Development Kit to develop a Java Card applet. You can use the Java Card 2.1.2 Development Kit to develop an applet for masking. Masking means embedding the applet into the read-only memory of a smart card when the card is manufactured. Alternatively, you can use the Java Card 2.1.2 Development Kit to develop an applet for installation onto a smart card after the card is manufactured.

The Java Card 2.1.2 Development Kit provides components and tools that you need to develop applets for masking or installation. This includes:

• Java Card Framework classes that are essential for developing Java Card applets.
• A Java Card Workstation Development Environment (JCWDE) that simulates the Java Card runtime environment on a Java virtual machine ¹ .
• An APDUTool utility that sends command APDUs to the JCWDE or to a Java Card runtime environment. Command APDUs are the way operational requests are made to a smart card.
• A Converter tool that converts a Java Card applet into a format required for masking or for installation.
• Off-card verification tools that check the integrity of files produced by the Converter.
• A mask generator that generates a mask file for incorporation into a mask in a Java Card runtime environment.
• An off-card installer for installing a Java Card applet onto a smart card.

Using these classes and tools, you develop a Java Card applet on your workstation or PC. Specifically, you:

• Compile the applet.
• Optionally, test the applet in the JCWDE, and debug the applet.
• Convert the applet. If you develop an applet that will be masked, you convert the applet class and all the classes in its package to a Java Card Assembly (JCA) file. If you develop an applet for installation, you convert the applet and all the classes in its package to a Converted Applet (CAP) file, and possibly an export file. An export file is used to convert another package if that package imports classes from this package.

The next step depends on whether you develop an applet for masking or for installation. For masking, you run the mask generator to produce a mask file. For installation, you run the off-card installer; this produces a script file that contains command APDUs -- you then use the file as input to the APDUTool. The APDUTool works in conjunction with the installer on the smart card to download the CAP file and instantiate the Java Card applet in the CAP file.

The Java Card 2.1.2 Development Kit also includes a reference implementation of the Java Card runtime environment. The implementation is written in the C language, so it is referred to as the C-JCRE. The reference implementation simulates the read-only memory of an actual Java Card runtime environment. The simulation can incorporate a mask. You can also install applets into the C-JCRE. As a result, you can use the C-JCRE to test the mask for an applet or to test an applet designed for installation onto a smart card.

The steps in the development process are illustrated in the following figure.

The Java Card 2.1.2 Development Kit includes sample Java Card applets. To demonstrate how to develop a Java Card applet, this article uses the Wallet sample Java Card applet. The Walletapplet is also used for demonstration purposes in the article Writing a Java Card Applet. You can find the source code file, Wallet.java, in the samples subdirectory of the Java Card 2.1.2 Development Kit. Or click here to see the source code for the Wallet applet.

Setting Up Your Environment

You can use the Java Card 2.1.2 Development Kit in the Solaris Operating Environment (versions 2.6, 2.7, and 2.8) or the Windows NT Platform (with Service Pack 4). In either of these environments, you need to ensure that you have the Java 2 Platform, Standard Edition SDK version 1.2.2, 1.3 (or above) installed.

You also need to install the javax.comm package that is part of the Java Communications API 2.0 (or above). You can download the API from the Java Communications API page. Follow the instructions provided with the download to install the API.

The tools in the Java Card 2.1.2 Development Kit require that you set certain environment variables. Set the JC21_HOME environment variable to the location of the Java Card 2.1.2 Development Kit. When you download the Java Card 2.1.2 Development Kit, a ZIP file is downloaded. When you unzip the file, the contents of the Java Card 2.1.2 Development Kit are placed in a subdirectory named java_card_kit-2_1_2. Suppose, for example, you downloaded the Java Card 2.1.2 Development Kit in the Solaris Operating Environment in directory /home/ed, and then unzipped it. In this case, set JC21_HOME as follows:

setenv JC21_HOME /home/ed/java_card_kit-2_1_2

Or suppose you downloaded the Java Card 2.1.2 Development Kit to the root directory of your C drive on the Windows NT platform, and then unzipped it. In this case, set JC21_HOME as follows:

set JC21_HOME=c:\java_card_kit-2_1_2

Also set the JAVA_HOME environment variable (if it is not already set) to the location of the Java 2 SDK. For example, in the Solaris Operating Environment:

setenv JAVA_HOME /home/ed/jdk13/j2sdk1_3_0

In the Windows platform:

set JAVA_HOME=c:\jdk13\j2sdk1_3_0

Although optional, it's also a good idea to set the PATH environment variable so that you can run the Java Card tools from any directory. To do this in the Solaris Operating Environment, set the PATHenvironment variable as follows:

setenv PATH .:$JC21_HOME/bin:$PATH

In the Windows platform:

SET PATH=%JC21_HOME%\bin;%PATH%

Remember to set up your environment before you run any tool provided by the Java Card 2.1.2 Development Kit.

One final note about setting up your environment: Java card applets depend on API classes in theapi21.jar file (the api21.jar file is in the lib directory of the installed Java Card 2.1.2 Development Kit). Because of this, you should ensure that api21.jar is in your class path. To do this in the Solaris Operating Environment, set the CLASSPATH environment variable as follows:

setenv CLASSPATH $JC21_HOME/lib/api21.jar:$CLASSPATH

In the Windows platform:

SET CLASSPATH=%JC21_HOME%\lib\api21.jar;%CLASSPATH%

If you don't include api21.jar in your class path, you might get errors when you compile a Java Card applet.

Compiling a Java Card Applet

You write Java Card applets in the Java programming language. However because applets are designed to run in the very small memory space of a smart card, they're coded using an appropriate subset of the Java programming language. As you do for a Java application or applet, you compile Java Card applets on your workstation or PC. You can use any Java compiler that supports Java 2 Platform, Standard Edition version 1.2.2, 1.3 (or above), such as the javac compiler in Java 2 SDK version 1.3. Remember to include api21.jar in your class path before you compile.

For example, assuming that you're in the samples subdirectory of the Java Card 2.1.2 Development Kit, you can compile the Wallet applet like this (in the following and in subsequent examples of commands in the Solaris Operating Environment, the backslash character indicates continuation of the command):

javac -g \
samples/com/sun/javacard/samples/wallet/Wallet.java

In Windows NT, enter the following (on one line):

javac -g
samples\com\sun\javacard\samples\wallet\Wallet.java

Notice that the javac compiler is invoked with the -g option. This tells the compiler to generate debugging information. You need to specify this option in preparation for running the Converter tool. That's because the Converter tool requires information about local variable types within the applet, information that it gets from the LocalVariableTable attribute. The attribute is generated only if the -g option is specified when you compile the applet.

Testing a Java Card Applet in the JCWDE

This step is optional. You can wait to test your applet until a later step in the development process, for instance, when you convert it to a format for masking or for installation. However if you want to do an early test of your applet, you can test it in the JCWDE. This gives you a way of testing a Java Card applet on your workstation or PC, that is, in a Java virtual machine, without having to convert the applet.

To test a Java Card applet in the JCWDE, you:

• Start the JCWDE
• Run the APDUTool Utility
• Debug the Applet

Starting the JCWDE

The JCWDE, which runs on your workstation or PC, simulates the Java Card runtime environment on a Java virtual machine. It's not a complete simulation, for example, the JCWDE does not simulate the applet firewall of a Java Card virtual machine. However the JCWDE does provide a simulation that allows a good initial test of your Java Card applet. It allows you to run your applet as though it was masked in the the read-only memory of a smart card. And importantly, it allows you to run the test in your workstation or PC, without having to convert the applet, generate a mask file, or install the applet.

To start the JCWDE, issue the jcdwe command. (This runs a script file in the Solaris Operating Environment, and a batch file in the Windows NT platform.) The primary input to the command is aconfiguration file that identifies one or more applets. There are other inputs that you can optionally specify, such as a TCP/IP port for communication to the JCWDE -- if you don't specify a port, it defaults to port 9025. For a description of all the inputs to the jcwde command, see jcwde Command Syntax in the Reference section.

The applets identified in the configuration file are masked into the JCWDE, as though the applets were stored in the read-only memory of the smart card runtime environment. The applets are identified in the configuration file by their Application Identifier (AID). With the applets configured into its mask, the JCWDE is able to direct processing requests in the form of command APDUs to the appropriate applet for processing.

		Get Application Identifiers from ISO  AIDs are assigned by the International Standards Organization (ISO) in accordance with ISO 7816-5, the smart card specification standard that covers AIDs. You need to obtain these identifications for your Java Card applets and packages of Java Card applets before you can make your applets available.

The Configuration File

To see what a configuration file looks like, examine the sample configuration file, jcwde.app, in the samples/src/demo directory of the Java Card 2.1.2 Development Kit. Or click here to see the source code for the jcwde.app file. You'll notice that each line contains two fields: (1) the fully-qualified name of the class that represents the applet, and (2) the AID of the applet. For example, in the line:

com.sun.javacard.samples.wallet.Wallet
0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x6:0x1

com.sun.javacard.samples.wallet.Wallet is the name of the class for the Wallet applet, and 0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x6:0x1 is the AID of the Wallet in hexadecimal. (Although shown here as two lines, each class-AID pair in a configuration file comprises one line. Subsequent examples in this section display the class and AID on separate lines.)

Notice that the first applet-AID line of the jcwde.app file is:

com.sun.javacard.installer.InstallerApplet
0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0x8:0x1

This line is for the installer applet that is provided with the Java Card 2.1.2 Development Kit, and must be the first applet-AID pair line in a configuration file. The installer applet creates instances of the applets that are identified in the configuration file; it performs functions analogous to the Installer component on a smart card that loads applets into the card's memory. Your configuration file would start with the applet-AID pair line for the installer applet, followed by applet-AID lines for your applets. For example, suppose you wrote an applet named MyWallet in a package namedmywallet, and the AID assigned to that applet is0xb0:0x0:0x0:0x0:0x6:0x0:0x1:0xc:0x5:0x1. The content of your configuration file would be:

com.sun.javacard.installer.InstallerApplet
0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0x8:0x1
mywallet.MyWallet
0xb0:0x0:0x0:0x0:0x6:0x0:0x1:0xc:0x5:0x1

An example

With a configuration file available, you can start the JCWDE. As an example, start the JCWDE and specify jcwde.app as the configuration file; rely on defaults for the remaining input. To do that, go to location where you installed the Java Card 2.1.2 Development Kit, then change to thesamples/src/demo subdirectory and issue the following command:

jcwde jcwde.app

This starts the JCWDE and masks into it the applets, including the Wallet applet, that are identified in the jcwde.app configuration file. By default, the JCWDE will listen for APDU commands through port 9025, and it will display all messages, including the banner message, generated by the JCWDE. You should see the following in response:

Java Card 2.1.2 Workstation Development Environment (version 0.18). Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved. jcwde is listening for T=0 Apdu's on TCP/IP port 9,025

Notice the reference in the response to T=0. This refers to the type of transport protocol used to transmit the APDUs. The T=0 protocol is a byte-oriented protocol, meaning that the smallest unit of data that can be transmitted by the protocol is a byte. By comparison, another APDU transport protocol in use today, the T=1 protocol, is a block-oriented protocol, where data is transmitted in blocks of bytes.

Running the APDUTool Utility

The APDUTool Utility submits command APDUs to a Java Card runtime environment, or to a simulated runtime environment such as the JCWDE. It's used in the process of installing a CAP file into the Java Card runtime environment of a smart card. But it also provides a convenient way for you to submit command APDUs to a Java Card applet masked into the JCWDE, as a way of testing the applet. The primary input to the utility is a script file that contains one or more command APDUs as well as some other commands unique to the APDUTool. When used with the JCWDE, the utility directs each command APDU to the JCWDE, which in turn, sends it to the appropriate applet for processing. Each applet responds with a response APDU. As output, the APDU utility displays the command APDUs and the associated response APDUs.

To start the APDUTool Utility, issue the apdutool command, and specify the script file as input. This runs a script file in the Solaris Operating Environment (a different script file than the one that contains the command APDUs), and a batch file in the Windows NT platform. There are other inputs that you can optionally specify such as a file to contain the output from the APDUtool utility -- by default, output is directed to the standard output stream. For a description of all the inputs to theapdutool command, see apdutool Command Syntax in the Reference section.

The Script File

The script file contains the primary input data for the APDUTool utility. The file contains the command APDUs to be processed by the Java Card runtime environment (or JCWDE). It also contains commands that are unique to the APDUTool utility. In addition, the file can include comments. To see what a script looks like, examine the sample script file, demo1.scr, in thesamples/src/demo directory of the Java Card 2.1.2 Development Kit. Or click here to see the source code for the demo1.scr file. You'll notice that the first non-comment line is:

powerup;

This is an APDUTool command that prepares the APDUTool utility for reading command APDUs. It must be executed before any command APDUs are sent. The powerup command's logical opposite is the powerdown command, which ends APDUTool processing. The utility also provides an echo command to write a text string to the output file; and a delay command to pause execution of the APDUTool script.

Notice that the powerup command line in demo1.scr is followed by lines such as the following, surrounded by comments (although shown here as two lines, the following is one line indemo1.scr):

0x00 0xA4 0x04 0x00 0x09 0xa0 0x00 0x00 0x00 0x62 0x03
0x01 0x08 0x01 0x7F;

These are command APDUs specified in hexadecimal (the command APDUs can also be specified in decimal, octal, UTF-8 quotes literals, or UTF-8 quoted strings). The command APDUs conform to the command APDU format specified by ISO7816. For example, the hexadecimal line after the powerup command selects the installer applet. The first four bytes ( 0x00 0xA4 0x04 0x00) are the CLA, INS, P1, and P2 bytes, respectively, of the APDU command format; they specify that this is a selection request; the fifth byte, the Lc byte, ( 0x09) indicates that nine bytes of data follow; the nine bytes of data ( 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x08 0x01) specify the AID of the applet (in this case, the installer applet); and the remaining byte, the Le byte ( 0x7F) indicates the maximum number of bytes expected in the response to the command APDU.

An Example

As an example, start the JCWDE as described in Starting the JCWDE. Then in another window, start the APDUTool. Use demo1.scr as the input file, and specify demo1.scr.jcwde.out as the output file. Rely on defaults for the remaining input. To do that, go to the location where you installed the Java Card 2.1.2 Development Kit, then change to the samples/src/demosubdirectory and issue the following command:

apdutool demo1.scr > demo1.scr.jcwde.out

In response, you should see the following in the window where you started the APDUTool:

Java Card ApduTool (version 0.15) Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved. Opening connection to localhost on port 9025. Connected.

When the APDUTool ends, you should also see the following line in the window where you started the JCWDE:

jcwde exiting on receipt of power down command

The command should also produce an output file demo1.scr.jcwde.out . If you examine the contents of output file, you'll see that it displays an "ATR" (answer to reset) message (in hexadecimal), followed by each command APDU (also in hexadecimal) submitted from the input file. You'll also see that each field in the command APDU is labeled. Following each command APDU, is the associated response APDU in conformance with the ISO7816 response APDU format (again, in hexadecimal, and with each field labeled). For example, the first APDU line of thedemo1.scr.jcwde.out file is (although shown here as two lines, the following is one line indemo1.scr.jcwde.out):

CLA: 00, INS: a4, P1: 04, P2: 00, Lc: 09, a0, 00, 00,
00, 62, 03, 01, 08, 01, Le: 00, SW1: 90, SW2: 00

You'll recognize the first six fields in the line as those in the command APDU that selects the installer applet. The final two fields in the line comprise the response APDU (some response APDUs precede the status words with a data field.) The two fields are status words (SW1 and SW2) that indicate the processing state of the smart card, as though the request was actually submitted to the smart card. Here, the status word values SW1: 90, SW2: 00 indicate that processing was successful.

Debugging a Java Card Applet

As mentioned in Running the APDUTool Utility the output produced by the APDUTool utility includes command APDUs provided as input to the utility, and their associated response APDUs. The last two bytes of each response APDU are status words (SW1 and SW2) that indicate the processing state of the smart card. The status words values SW1: 90, SW2: 00 indicate that processing was successful. Other status word values indicate that processing was not successful. In some cases, unsuccessful processing is what you want. For example, one of the command APDUs directed to the Wallet applet in the demo1.scr file attempts to credit money to an account before the personal identification (PIN) of the user who enters the transaction is verified. Here's the command APDU:

0xB0 0x30 0x00 0x00 0x01 0x7F 0x00;

The response APDU returned for this request includes the status word values SW1: 63, SW2: 01. These status word values are defined in the Wallet applet to indicate that PIN verification is required. In other words, they're the anticipated response to this condition.

Other responses are unanticipated. These are the ones you need to identify, and probably fix, when you debug your Java Card applet. For example, suppose you created your own Java Card applet named MyWallet. The MyWallet applet is the same as the Wallet applet, except that it has the following code to check the debit amount:

// check debit amount if ( ( debitAmount > MAX_TRANSACTION_AMOUNT) || ( debitAmount > 0 ) ) ISOException.throwIt (SW_INVALID_TRANSACTION_AMOUNT);

If you test the MYWallet applet in the JCWDE, and attempt to debit money from an account, say by submitting the following command APDU:

0xB0 0x40 0x00 0x00 0x01 0x32 0x7F;

The output from the APDUTool should look like this (although shown here as two lines, the following is one line of output):

CLA: b0, INS: 40, P1: 00, P2: 00, Lc: 01, 32, Le: 00,
SW1: 6a, SW2: 83

The status word values SW1: 6a, SW2: 83 indicate that this is an invalid transaction amount, something that is unanticipated. If you investigate the code, you'll see that it throws an exception for any debited amount (not a very workable debit method!). So you need to do some debugging here.

You can debug the applet on your workstation or PC just as you do for a Java application. More specifically, you can use the same debugging tools, such as the debugging facilities of an IDE, or the Java debugger tool (jdb) in the Java 2 SDK. When you use these facilities, you reference the JCWDE. Remember that the jcdwe command runs a script file or batch file. The script or batch file runs the JCWDE class. So when you invoke a debugging tool such as jdb, you invoke it inside of the jcdwe script or batch file. For example, in the Solaris Operating Environment, you can run the jdb tool with the JCWDE by replacing the -native flag in the following line in the jcwde script file:

JFLAGS="-native -classpath $JC_PATH"

with the -jdb flag:

JFLAGS="-jdb -classpath $JC_PATH"

You then run the jcwde command and APDUtool utility (in separate windows). This will start the jdb, at which point you can use its facilities to do things such as set breakpoints and list method calls. For example:

jcwde -p 9025 myjcwde.app Initializing jdb... > stop in mywallet.MyWallet.debit Deferring breakpoint mywallet.MyWallet.debit. It will be set after the class is loaded. > run run com.sun.javacard.jcwde.Main -p 9025 myjcwde.app > VM Started: Java Card 2.1.2 Workstation Development Environment (version 0.18). Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved. jcwde is listening for T=0 Apdu's on TCP/IP port 9,025. Set deferred breakpoint mywallet.MyWallet.debit Breakpoint hit: thread="main", mywallet.MyWallet.debit(), line=174, bci=0 main[1] where [1] mywallet.MyWallet.debit (MyWallet.java:174) [2] mywallet.MyWallet.process (MyWallet.java:112) [3] javacard.framework.Dispatcher.main (Dispatcher.java:78) [4] javacard.framework.JCWDEDispatcher.main (JCWDEDispatcher.java:28) [5] com.sun.javacard.jcwde.Main.run (Main.java:86) [6] com.sun.javacard.jcwde.Main.main (Main.java:148) main[1] quit

Converting a Java Card Applet

In Java Card technology, you don't directly incorporate a Java Card applet into a mask. Similarly, after a smart card is manufactured, you don't directly download a Java Card applet for installation onto a smart card. Instead, for masking, you convert an applet class and all the classes in its package to a JCA (Java Card Assembly) file. The JCA file and JCA files for any other packages to be included in the mask are then converted into a format compatible with the target runtime environment. It's this converted output for the target runtime environment that is incorporated into the mask.

For installation onto an already-manufactured smart card, you convert an applet class and all the classes in its package to a CAP (converted applet) file. You then download the CAP file to a smart card using the off-card installer in conjunction with the APDUTool utility and the on-card installer.

Both a JCA file and a CAP file are self-descriptive files, that is, they contain information about their contents. In other words, these files contain information about the converted package. In addition, a CAP file is in a compressed format that is optimized for the limited amount of memory in a smart card. A JCA file is simply a text representation of the contents of a CAP file.

A JCA file and a CAP file contain information about the converted package. A CAP file is in a compressed format. A JCA file is a text representation of a CAP file.

To convert a Java Card applet (whether it's for masking or installation), use the Converter tool that's in the Java Card 2.1.2 Development Kit. You do this by issuing the converter command. (This runs a script file in the Solaris Operating Environment, and a batch file in the Windows NT platform.) The tool operates on a Java package. You specify the name, AID, and version of the package; the tool then converts all the classes in the package. What this means is that you don't convert a Java Card applet individually, but instead you convert as a unit the applet and all the other applets in its package.

When you run the Converter tool you specify what output to produce: a CAP file, JCA file, or another file not yet mentioned called an export file. You can request any combination of these files. By default, the converter produces a CAP file and an export file.

For example, suppose you had an applet named mywallet in a package named mytest. Assume that the package is in the mytest subdirectory of the Java Card 2.1.2 Development Kit download directory. Also assume that the AID assigned to that package is0xF2:0x34:0x12:0x34:0x56:0x10:0x10:0x00. You can convert mywallet and all the other classes in mytest to a CAP file and an export file by issuing the following command in the Solaris Operating Environment:

converter -classdir $JC21_HOME/mytest mytest \
0xF2:0x34:0x12:0x34:0x56:0x10:0x10:0x00 1.1

In the Windows NT platform (on one line):

converter -classdir %JC21_HOME%\mytest mytest
0xF2:0x34:0x12:0x34:0x56:0x10:0x10:0x00 1.1

To convert mywallet and all the other classes in mytest to a JCA file, use the following command in the Solaris Operating Environment:

converter -out JCA -classdir $JC21_HOME/mytest mytest \
0xF2:0x34:0x12:0x34:0x56:0x10:0x10:0x00 1.1

In the Windows NT platform (on one line):

converter -out JCA -classdir %JC21_HOME%\mytest mytest
0xF2:0x34:0x12:0x34:0x56:0x10:0x10:0x00 1.1

The name of the resulting CAP file is mytest.cap, that is, the name of the input package, with the file extension cap. Similarly, the resulting export file is named mytest.exp. The resulting JCA file is named mytest.jca. The Converter tool creates a subdirectory named javacard below the directory of the input package, and puts the generated files (CAP, EXP, or JCA) in that subdirectory. You have the option (using the -d option) of specifying another root directory below which the Converter tool puts the generated files. For example, if you specify -d $myRoot, the converter writes the output files to the directory $myRoot/mytest/javacard. Notice that the directory hierarchy of the root directory and the javacard subdirectory corresponds to the fully-qualified package name. The -d option, and other options that you can specify to the Converter tool, are described in converter Command Syntax in the Reference section.

Also notice the 1.1 that is specified at the end of the command. This is the version of the package. The converter command requires that you specify the version in the format major version. minor version.

What Happens During Conversion?

As part of the conversion process, the Converter tool preprocesses classes.

Of course one thing that happens is that one or more files such as a CAP, EXP, or JCA file is produced. But some other important things happen too. As part of the conversion process, the Converter tool preprocesses the classes. That is, it performs some of the tasks that a Java virtual machine normally does when it loads a Java class in a desktop environment. The idea behind the preprocessing is to keep the Java virtual machine on a smart card as small as possible. One of the preprocessing tasks the Converter tool performs is initializing static variables in the classes, another is resolving symbolic references. In addition, the Converter tool checks whether the Java classes in the package are properly formed, and whether the applets use only the subset of the Java programming language that is supported by the Java Card platform. The Converter tool then directs the result of its preprocessing checks to the standard output stream. For example, suppose you issued the converter command as described above for the mytest package. If the Converter tool found no errors in its checks, you should see the following displayed:

Java Card 2.1.2 Class File Converter (version 1.2) Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved. conversion completed with 0 errors and 0 warnings.

If the Converter tool finds errors during its checks, it displays appropriate error messages.

The Java Card 2.1.2 Development Kit includes a utility called capdump that produces an ASCII version of a CAP file. This can help in debugging a CAP file. To run capdump, issue the command:

capdump  
             capfile
          

where capfile is the name of the CAP file.

The CAP File

A CAP file is a container file in JAR file format. Each component in the container is a file itself, and contains information about the converted package. As the following table shows, each component contains information about a different aspect of the package. For example, one component contains information about the applets in the package. Another component contains information about the classes in the package.

Component Description Header Contains general information about the CAP file and the package it defines. Directory Lists the size of each of the components in the CAP file. Applet Contains information about each of the applets defined in this package. Import Lists the set of packages that are imported by this package. Constant Pool Contains information about the classes, methods, and fields referenced by elements in the Method component. Class Describes each of the classes defined in this package. Method Describes each of the methods declared in this package. Static Field Contains information required to create and initialize an image of all the static fields defined in this package. Reference Location Contains offsets required to access data in the Constant Pool component. Export Lists all static elements in this package that may imported by other packages.

The Export File

An export file is used by the Converter tool during the conversion of a package that imports classes from another package.

If you run the Converter tool for the mytest package as described inConverting a Java Card Applet, you'll find that the tool does indeed generate a CAP file for the package in the javacard subdirectory. But you'll also notice a second output file, named mytest.exp. This is known as an export file. Unlike a CAP file, an export file is not downloaded to a smart card. Instead it's used by the Converter tool during the conversion of a package that imports classes from another package. The Converter tool actually loads the export file. For example, if an applet in a package (say, yourtest) imports classes from the mytest package, the Converter tool loadsmytest.exp during the conversion of the yourtest package.

An export file contains the public interface information about all the classes in the package. For example, it contains information about the fields in each class and about method signatures. When you provide an export file (say mytest.exp) as input for conversion, the Converter tool includes the public interface information for that package into the CAP file for the package being converted (say yourtest.cap). After a CAP file is downloaded to a smart card, the public interface information in the CAP file is used to link the contents of the package with the other package. In other words, if yourtest.cap is downloaded to a smart card, the public interface information in the CAP file is used to link the contents of the yourtest package with the mytest package.

Verifying the Integrity of CAP and Export Files

Verifying integrity means ensuring that the CAP and export files conform to the Java Card 2.1.1 specifications, for example, by checking that the files do not attempt to compromise the integrity of the Java Card virtual machine implementation and other applets.

The Java Card 2.1.2 Development Kit provides a number of tools that you can use to verify the integrity of the CAP and export files. Verifying integrity means ensuring that the CAP and export files conform to theJava Card 2.1.1 specifications. For example, one aspect of verifying integrity is checking that the files do not attempt to compromise the integrity of the Java Card virtual machine implementation and other applets.

There are three integrity verification tools that you can use:

• VerifyCap. Use this tool to verify the integrity of a CAP file within the context of the export files it imports. The tool also verifies the integrity of the export file (if any) for this package that can be imported during the conversion of another package.
• VerifyExp. Use this tool to verify the integrity of a single export file.
• VerifyRev. Use this tool to verify the binary compatibility of two export files, for example, where each file is for a different version of a package.

To run the VerifyCap tool, use the verifycap command, and specify the pertinent export files and CAP file as arguments. Remember to include the export files for the Java Card API packages that the CAP file uses. The export files for the Java Card packages in the Java Card 2.1.2 Development Kit are in the api21_export_files subdirectory of the Java Card 2.1.2 Development Kit download directory. For example, assume that a CAP file, mytest.cap and an export file mytest.exp are in the javacard subdirectory under the mytest subdirectory of the Java Card 2.1.2 Development Kit download directory. Assume too that mytest.cap also uses the java.lang package (but uses no other Java Card API packages). The following command, verifies the integrity of the CAP file and export file in the Solaris Operating Environment:

verifycap $JC21_HOME/mytest/javacard/mytest.exp \
$JC21_HOME/api21_export_files/java/lang/javacard/lang.exp \
$JC21_HOME/mytest/javacard/mytest.cap

In the Windows NT platform (on one line):

verifycap %JC21_HOME%\mytest\javacard\mytest.exp
%JC21_HOME%\api21_export_files\java\lang\javacard\lang.exp
%JC21_HOME%\mytest\javacard\mytest.cap

There are various options that you can specify to the VerifyCap tool, for example, you can specify the name of a package whose CAP and export files are to be verified. For a list and description of the verifyexp options, see verifycap Command Syntax in the Reference section.

To run the VerifyExp tool, use the verifyexp command, and specify the export file to be verified as an argument. The following command, verifies the integrity of the export file mytest.exp in the Solaris Operating Environment:

verifyexp $JC21_HOME/mytest/javacard/mytest.exp

In the Windows NT platform:

verifyexp %JC21_HOME%\mytest\javacard\mytest.exp

There are various options that you can specify to the VerifyExp tool, for example, you can request additional information in the output messages. For a list and description of the verifyexp options, see verifyexp Command Syntax in the Reference section.

Let's say you update a version of an export file and you want to check the new version against the older version for binary compatibility. If the two versions of the export file are binary compatible, then a CAP file that is converted using the older version of the export file can also be converted using the new version of the export file. You can use the VerifyRev tool to check for binary compatibility. To run the VerifyRev tool, use the verifyrev command, and specify the fully-qualified paths and names of the two export files to be checked for binary compatibility. The names of the two files must be the same, but their paths must be different. For example, the following command, verifies the binary compatibility of two export files named mytest.exp. Notice the different paths of the two files in the Solaris Operating Environment:

verifyrev $JC21_HOME/mytestold/javacard/mytest.exp \
$JC21_HOME/mytestnew/javacard/mytest.exp

In the Windows NT platform (on one line):

verifyexp %JC21_HOME%\mytestold\javacard\mytest.exp
%JC21_HOME%\mytestnew\javacard\mytest.exp

There are various options that you can specify to the VerifyRev tool, for example, you can request additional information in the output messages. For a list and description of the verifyrev options, see verifyrev Command Syntax in the Reference section.

The JCA File

A JCA (Java Card Assembly) file is a text representation of the contents of a CAP file. To mask a Java Card applet into a smart card, you need to convert the applet class and all the classes in its package to a JCA file. You then specify the JCA file and the JCA files for any other packages to be included in the mask as input to the mask generator.

A JCA file also has a second purpose: you can use it as an aid in testing and debugging the conversion. For example, if you're converting an applet for eventual installation onto a smart card, you can generate a CAP file and a JCA file. You then examine the JCA file to see if all the applets in the package are identified in the CAP file.

The information in the CAP file is arranged hierarchically, like this:

• package
  • package directives
  • imports block
  • applet declarations
  • constant pool
  • class
  • field declarations
  • virtual method tables
  • methods
    • method directives
    • method statements

Each of these sections is well commented so that you can understand its purpose. For example, here's what the imports block in a JCA file might look like:

/* * The imports block declares all of the packages that * this package imports. The data that is declared in * this section appears in the Import component of the * CAP file. The ordering of the entries within this * block defines the package tokens which must be used * within this package. The imports block is optional, * but all packages except for java/lang import at least * java/lang. There should be only one imports block * within a package. */ .imports { 0xa0:0x00:0x00:0x00:0x62:0x00:0x01 1.0; // java/lang aid <SPACE> //java/lang major version <DOT> //java/lang minor version 0:1:2:3:4:5 0.1 // package test2 1:1:2:3:4:5 0.1 // package test3 2:1:2:3:4:5 0.1 // package test4 }

You can also use a JCA file to generate a CAP file. To generate a CAP file from a JCA file, use the capgen tool that's in the Java Card 2.1.2 Development Kit. You do this by issuing the capgencommand. (This runs a script file in the Solaris Operating Environment, and a batch file in the Windows NT platform.) Specify the JCA file as input to the command, for example:

capgen $JC21_HOME/mytest/javacard/mytest.jca

in the Solaris Operating Environment.

In the Windows NT platform:

capgen %JC21_HOME%\mytest\javacard\mytest.jca

There are various options that you can specify to the capgen tool, for example, you can specify an output file (if you don't specify this option, the output file is a.jar in the current directory). For a list and description of the capgen options, see capgen Command Syntax in the Reference section.

Generating a Mask File

Use the mask generator provided with the Java Card 2.1.2 Development Kit to generate a mask file for one or more Java Card applets. The mask file can then be incorporated into a mask for a specific Java Card runtime environment. You specify as input to the mask generator the JCA file for the package that contains the applets, as well as JCA files for any other packages to be included in the mask file, such as JCA files for any needed Java Card API packages.

To run the mask generator, issue the maskgen command. (This runs a script file in the Solaris Operating Environment, and a batch file in the Windows NT platform.) Specify the JCA files as input to the command. You also need to specify a specific "generator", that is, a pluggable back end to the mask generator. The pluggable back end formats the output of the mask generator for a specific Java Card runtime environment. For Java Card 2.1.2, the only generator plugins supported are cref, which formats the output for the C-JCRE, and size which produces mask size statistics. For example, the the following is a simplified version of a command that generates a mask file for the C-JCRE in the Solaris Operating Environment. The command uses the file mytest.jca as input. The example is simplified because you would also need to specify JCA files for all the other API packages to be included in the mask file. Typically, you would specify JCA files for all the Java Card API packages:

maskgen cref $JC21_HOME/mytest/javacard/mytest.jca

In the Windows NT platform:

maskgen cref %JC21_HOME%\mytest\javacard\mytest.jca

There are various options that you can specify to the mask generator, for example, you can request the mask generator to produce debug information. For a list and description of the maskgen options, see maskgen Command Syntax in the Reference section.

Installing a CAP File

As mentioned earlier, you don't install a Java Card applet onto a smart card, instead you install its CAP file. The Java Card 2.1.2 Development Kit includes an off-card installer utility that prepares a CAP file for installation. The "off-card" designation differentiates the installer provided with the Java Card 2.1.2 Development Kit from the "on-card" installer resident in a smart card.

The off-card installer produces a script file that contains command APDUs that identify the beginning and end of the CAP file, its components, and component data. The script file is used as input to the APDUTool Utility. This is the same APDUTool utility and script file that are described inRunning the APDUTool Utility. As is the case for running the APDUTool for testing, the script file produced by the off-card installer requires commands such as powerup to prepare the APDUTool utility for reading command APDUs. You must manually add these commands to the script file, as described in Tailoring the Script File. The APDTool utility works in conjunction with the on-card installer to download the CAP file, so you also need to add an APDU command to the script file to start the on-card installer. You can also add command APDUs to direct the on-card installer to create, that is, instantiate, the applets defined in the CAP file.

After you tailor the script file, you run the APDUTool utility, specifying the script file as input. The APDUTool starts the on-card installer, which downloads the CAP file. If requested in the script file, the on-card installer creates the applets that are defined in the CAP file, so that the applets are available in the Java Card runtime environment.

Running the Off-Card Installer

To run the off-card installer, issue the scriptgen command. (This runs a script file in the Solaris Operating Environment, and a batch file in the Windows NT platform.) Specify the CAP file path as input to the command. By default, the off-card installer directs output to the standard output stream, however the command does provide a flag for specifying an output script file name. For example, the following command generates a script file named mytest.scr for the CAP file mytest.cap in the Solaris Operating Environment:

scriptgen -o $JC21_HOME/mytest/javacard/mytest.scr \
$JC21_HOME/mytest/javacard/mytest.cap

In the Windows NT platform (on one line):

scriptgen -o %JC21_HOME%\mytest\javacard\mytest.scr
%JC21_HOME%\mytest\javacard\mytest.cap

There are other options that you can specify to the off-card installer. For a list and description of the off-card installer options, see scriptgen Command Syntax in the Reference section.

The Script File Produced by the Off-Card Installer

The script file produced by the off-card installer contains command APDUs that identify the beginning and end of a CAP file, its components, and its data. The following table lists and describes the command APDUs produced by the off-card installer, and also shows their header bytes. The header bytes are the first four bytes in the command APDU. See APDU Formats for a description of command APDU format.

Command APDU Description Header CAP Begin Identifies the beginning of a CAP file. This indicates that command APDUs for CAP file components will be sent next. 0x80, 0b00, 0x00, 0x00 Component## Begin Identifies the beginning of a CAP file component. The ## represents the component number. This indicates that command APDUs for component number ## will be sent next. 0x80, 0xb2, 0x##, 0x00 Component## Data Contains the data for a CAP file component. The ## represents the component number. 0x80, 0xb4, 0x##, 0x00 Component## End Identifies the end of a CAP file component. The ## represents a component number. This indicates that command APDUs for component number ## have been sent. 0x80, 0xbc, 0x##, 0x00 CAP End Identifies the end of a CAP file. This indicates that command APDUs for all the CAP file components have been sent. 0x80, 0xba 0x00, 0x00

The script file contains a combination of these command APDUs. For example, the script file might comprise the following series of command APDUs. Notice the component number 01 in the third byte of the Component## Begin header.

// CAP Begin 0x80 0b00 0x00 0x00 0x00 0x7f; // Component## Begin 0x80 0xb2 0x01 0x00 0x00 0x7f; // Component## Data 0x80 0xb4 0x01 0x00 0x16 0x01 0x00 0x13 0xde 0xca 0xff 0xed 0x01 0x02; 0x04 0x00 0x01 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x0c 0x01 0x7f; // Component## End 0x80 0xbc 0x01 0x00 0x00 0x7f; // CAP End 0x80 0xba 0x00 0x00 0x00 0x7f;

Tailoring the Script File

The script file produced by the off-card installer does not contain all the command APDUs needed to download a CAP file. To download a CAP file, you need to add the powerup command as the first non-comment line in the file. You also need to add the powerdown command as the last non-comment line in the file. The commands start and stop APDUTool processing, respectively.

In addition, you need to add a SELECT command APDU that selects the on-card installer, so that the on-card installer can process the command APDUs sent to it by the APDUTool. You specify the AID of the on-card installer in the data field of the SELECT command APDU. See APDU Formats for a description of the SELECT command APDU format. The on-card installer AID value is: 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x08 0x01 0x7f

Finally, you can add command APDUs to create applets that are in the CAP file. The header of the CREATE APPLET command APDU is: 0x80 0xb8 0x00 0x00. The header is followed by the following fields:

• LC
• AID length
• AID
• parameter length
• parameters
• LE

Here, for example, is a CREATE APPLET command APDU for an applet named mywallet that is assigned an AID of 0xb0 0x0 0x0 0x0 0x6 0x0 0x1 0xc 0x5 0x1:

// Create mywallet
0x80 0xB8 0x00 0x00 0x00 0xb0 0x0 0x0 0x0 0x6 0x0 0x1
0xc 0x5 0x1 0x01 0x00 0x7f;

After tailoring the script file, its content might look like this:

powerup; // Select the installer applet 0xA4 0x04 0x00 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x08 0x01 0x7f; // CAP Begin 0x80 0b00 0x00 0x00 0x00 0x7f; // Component## Begin 0x80 0xb2 0x01 0x00 0x00 0x7f; // Component## Data 0x80 0xb4 0x01 0x00 0x16 0x01 0x00 0x13 0xde 0xca 0xff 0xed 0x01 0x02; 0x04 0x00 0x01 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x0C 0x01 0x7f; // Component## End 0x80 0xbc 0x01 0x00 0x00 0x7f; // CAP End 0x80 0xba 0x00 0x00 0x00 0xfF; // Create mywallet 0x80 0xba 0x00 0x00 0x00 0xb0 0x0 0x0 0x0 0x6 0x0 0x1 0xc 0x5 0x1 0x01 0x00 0x7f; powerdown;

What Next?

If you generated a mask file for a specific Java Card runtime environment, you're ready to mask the applets that are specified by the mask file into that JCRE. For example, if you generated a mask file, specifying the cref generator, you can mask the applets specified by the mask file into the C-JCRE. For instructions on incorporating a mask file into the C-JCRE, see the User's Guide provided in the Java Card 2.1.2 Development Kit. For instructions on incorporating a mask file into other JCRE implementations, see the documentation provided with the pertinent JCRE.

If you used the off-card installer to create a script file for an applet package's CAP file, you're ready to install the applets that are specified by the CAP file into a JCRE. (However before you install the applets, you can do additional testing, as described in the box Testing in a Java Card Simulator.) To install the applets, run the APDUTool utility, specifying the script file as input. The APDUTool starts the on-card installer, which downloads the CAP file. If requested in the script file, the on-card installer creates the applets that are defined in the CAP file, so that the applets are available in the Java Card runtime environment. For information on running the APDUTool utility, see Running the APDUTool Utility.

		Testing in a Java Card Simulator  To further test a Java Card applet before putting it on a card, its CAP file can be tested using a simulator that fully simulates the Java Card virtual machine and provides a debugging facility. A workstation tool, called the Java Card Simulator, provides this capability. The tool is currently available as part of a Beta program. To join the Beta program for the Java Card Simulator, send a request to mptp-admin@metrowerks.com.

Reference

jcwde Command Syntax

The format of the jcdwe command is:

jcdwe [-p  
             port] [-version] [-nobanner] [-help]
              config_file
          

where:

-p port

is an optional flag that specifies a TCP/IP port through which the JCWDE "listens" for command APDUs. For example, specifying the flag -p 9500 directs the JCWDE to listen for command APDUs through TCP/IP port 9500. The default is port 9025.

-version

is an optional flag that displays the version number of the JCWDE. The default is not to display the version number.

-nobanner

is an optional flag that suppresses the "banner" message generated by the JCWDE. The banner message includes "Java Card 2.1.2 Workstation Development Environment" followed by the version number and the copyright notice. The default is not to suppress the banner message.

-help

is an optional flag that displays help information for the jcdwe command.

config_file

is a file that configures one or more applets into the JCWDE mask. Each line in the configuration file contains two fields: (1) the fully-qualified name of the class that represents the applet, and (2) the AID of the applet. See The Configuration File for further information.

apdutool Command Syntax

The format of the apdutool command is:

apdutool [-h  
             hostname] [-nobanner] [-noatr]
[-o  
             output_file] [-p  
             port] [-serialPort]
[version]  
             input_file [
             input_file ...]
[-help]
          

where:

-h hostname

is an optional flag that specifies the hostname for the TCP/IP port. The default is the local host.

-nobanner

is an optional flag that suppresses the "banner" message generated by the APDUTool. The banner message includes "Java Card ApduTool (version 0.15)" and the copyright notice. The default is not to suppress the banner message.

-noatr

is an optional flag that suppresses the "ATR" (answer to reset) messages. The default is not to suppress ATR messages.

-o output_file

is an optional flag that allows you to specify a file to contain the output from the APDUTool Utility. By default, the APDUTool directs output to the standard output stream.

-p port

is an optional flag that specifies a TCP/IP socket port through which the APDUTool sends command APDUs. For example, specifying the flag -p 9500 specifies TCP/IP socket port 9500. The default is port 9025.

-serialPort

is an optional flag that specifies serial COM port (in case you want to use a serial COM port instead of a TCP/IP socket port).

-version

is an optional flag that displays the version number of the JDCWE. The default is not to display the version number.

input_file

is a script file that contains the primary input data for the APDUTool. The file contains the command APDUs to be processed by a Java Card runtime environment such as the C-JCRE, or by a simulated runtime environment such as the JCWDE. The command APDUs can be specified in hexadecimal, decimal, octal, UTF-8 quotes literals, or UTF-8 quoted strings. The command APDUs conform to the command APDU format specified by ISO7816.

The script file also contains one or more of the following commands:

Command Purpose powerUp prepares the APDUTool utility for reading command APDUs. It must be executed before any command APDUs are sent by the script. powerDown ends APDUTool utility processing. echo "string" writes the specified text string to the output file. delayinteger pauses execution of the script for the specified number of milliseconds.

More than one input file can be specified, each separated from the other by white space.

-help is an optional flag that displays help information for the apdutool command.

converter Command Syntax

The format of the converter command is:

converter [
             options]  
             package_name

              package_AID  
             package_version
          

where:

options

identifies optional command line flags, as follows:

Option Purpose -classdirroot_directory specifies a root directory in which the Converter tool looks for input classes. If this option is not specified, the Converter tool uses the current directory as the root directory. -i instructs the Converter tool to support the 32-bit Integer type. -exportpathdirectory_list identifies the root directories in which the Converter tool looks for export files. If multiple directories are listed, the directories are separated by a semicolon (;) in the Windows NT platform, and a colon (:) in the Solaris Operating Environment. If this option is not specified, the Converter sets exportpath to the Java class path. -exportmap requests the Converter tool to convert a package using tokens in a predefined export file of the package. The Converter looks for the file in the root directories specified in the exportpath option. -applet AIDclass_name specifies the default applet AID, and identifies the class that contains the install method for the applet. If the package contains multiple applet classes, this option must be specified for each class. -doutput_directory identifies the root directory for output. If this option is not specified, output is directed to the javacard subdirectory of the package's directory. -out [CAP] [EXP] [JCA] specifies the type of output to be produced by the Converter tool. Any or all of the following files can be specified: CAP file (CAP), export file (EXP), Java Card Assembly file (JCA). If this option is not specified, the Converter tool produces a CAP file and an export file. -V or -version displays the version number of the Converter tool in output messages. The default is not to display the version number. -v or -verbose displays verbose output, that is, additional information in output messages. -mask indicates that the package is for masking, so restrictions on native methods are relaxed. If this option is specified, the -out CAP option cannot be specified. -help displays help information for the converter command. -nowarn suppresses the display of warning messages. The default is not to suppress warning messages. -nobanner suppresses the "banner" message generated by the Converter tool. The banner message includes "Java Card 2.1.2 Class File Converter (version 1.2)" and the copyright notice. The default is not to suppress the banner message. -debug directs the Converter tool to generate a debug component in the CAP file. The debug component contains metadata that can be used for debugging the package. If the -mask option is also specified, the file debug.msk is produced in the output directory.

package_name

the fully-qualified name of the package to be converted.

package_AID

the AID of the package to be converted.

package_version

the version of the package to be converted. The version must be in the format major_version.minor_version, where major_version is the major version number of the package, andminor_version is the minor version number of the package.

You can also specify all of the arguments and options in a configuration file. The syntax for using a configuration file is:

converter -config  
             configuration_file
          

where:

configuration_file

is the file path and file name of the configuration file.

verifycap Command Syntax

The format of the verifycap command is:

verifycap [
             options]  
             export_files
              CAP_file
          

where:

options

identifies optional command line flags, as follows:

Option Purpose -packagepkg specifies the name of a package whose CAP and export files are to be verified. -nobanner suppresses the "banner" message generated by the verifycap command. The default is not to suppress the banner message. -verbose displays verbose output, that is, additional information in output messages. -version displays version information in the output. The default is not to display version information. -help displays help information for the verifycap command.

export_files

are the names of the export files to be verified.

CAP_file

is the name of the CAP file to be verified.

verifyexp Command Syntax

The format of the verifyexp command is:

verifyexp [
             options]  
             export_file

          

where:

options

identifies optional command line flags, as follows:

Option Purpose -nobanner suppresses the "banner" message generated by the verifyexp command. The default is not to suppress the banner message. -verbose displays verbose output, that is, additional information in output messages. -version displays version information in the output. The default is not to display version information. -help displays help information for the verifyexp command.

export_files

is the name of one or more export files to be verified.

CAP_file

is the name of the CAP file to be verified.

verifyrev Command Syntax

The format of the verifyrev command is:

verifyrev [
             options]  
             export_file1
              export_file2
          

where:

options

identifies optional command line flags, as follows:

Option Purpose -nobanner suppresses the "banner" message generated by the verifyrev command. The default is not to suppress the banner message. -verbose displays verbose output, that is, additional information in output messages. -version displays version information in the output. The default is not to display version information. -help displays help information for the verifyrev command.

export_file1

is the fully-qualified path and name of the first export file to be compared for binary compatibility.

export_file2

is the fully-qualified path and name of the second export file to be compared for binary compatibility.

capgen Command Syntax

The format of the capgen command is:

capgen [
             options]  
             input_file
          

where:

options

identifies optional command line flags, as follows:

Option Purpose -ooutput_file specifies an output file for the generated CAP file. If you don't specify this option, the output file is a.jar in the current directory. -version displays version information in the output. The default is not to display version information. -help displays help information for the capgen command. -nobanner suppresses the "banner" message generated by the capgen command. The default is not to suppress the banner message.

input_file

specifies the file name of the input JCA file.

maskgen Command Syntax

The format of the maskgen command is:

maskgen [
             options]  
             generator
              input_file [
             input_file ...]
          

where:

options

identifies optional command line flags, as follows:

Option Purpose -cconfig_file specifies a configuration file that can be used to tailor the format of the output file produced by the specified generator. A configuration file for the cref generator is provided in the samples/src/demo subdirectory. -debuginfo specifies that debugging information should be produced for the generated mask. The default is not to produce debugging information. -ooutput_file specifies an output file for the generated mask file. If you don't specify this option, the output file is a.out in the current directory. -version displays version information in the output. The default is not to display version information. -help displays help information for the maskgen command. -nobanner suppresses the "banner" message generated by the maskgen command. The default is not to suppress the banner message.

generator

specifies the name of a pluggable back end to the mask generator that formats the mask file for a specific Java runtime environment. For Java Card 2.1.2, the only generator plugins supported arecref, which formats the output for the C-JCRE, and size which produces mask size statistics.

input_file

is a JCA file that is used as input for mask file generation. Any number of JCA files can be specified, each separated from the other by white space. Note however that the Windows platform allows a maximum of nine arguments in a command specification. If you need to specify more than nine JCA files in the maskgen command for the Windows platform, you can create a text file that lists JCA file names. You then specify the text file name, preceded by the @ character, as input to the maskgen command. For example, the following command specifies a text file namedmaskin as input to the maskgen command; the maskin file can contain a list of more than nine JCA file names.

maskgen cref @maskin

scriptgen Command Syntax

The format of the scriptgen command is:

scriptgen [
             options]  
             capfilepath
          

where:

options

identifies optional command line flags, as follows:

Option Purpose -ooutput_file specifies a name of a file to contain scriptgen output. By default, scriptgen directs output to the standard output stream. -nobeginend specifies that no command APDUs be generated to identify the beginning and end of a CAP file. -version displays version information in the output. The default is not to display version information. -help displays help information for the scriptgen command. -nobanner suppresses the "banner" message generated by the scriptgen command. The default is not to suppress the banner message.

capfilepath

specifies the path of the CAP file.

For More Information

Writing a Java Card Applet

Java Card Technology for Smart Cards: Architecture and Programmer's Guide

Java Card 2.1.1 Platform Specifications

Java Card Technology Questions and Answers with Zhiqun Chen

About the Author:

 Ed Ort is a staff member of the Java Developer Connection. He has written extensively about relational database technology and programming languages.