Development Kit User’s Guide

The command line tools in this development kit execute Apache Ant transparently, so you are not required to use Ant directly to use the command line tools themselves. Those Ant tasks are required to install and run the development kit.

In addition, this development kit also includes additional, optional Apache Ant tasks for skilled Ant users to streamline using the development kit. These optional Ant tasks grouping several command line tools into a single Ant task. This chapter describes how to use these additional, optional, and unsupported Apache Ant tasks.

---

Location and Installation

The optional Ant tasks are included at:

JC_CLASSIC_HOME\lib\jctasks.jar

These tasks work with Apache Ant version 1.6.5 or later. You can use the ant -version command to verify the installed version.

1. Be sure Ant is configured as described in Downloading the Development Kit.

2. Copy the file JC_CLASSIC_HOME\lib\jctasks.jar to a directory that serves as your Ant tasks home directory.

3. Add the jctasks.jar file to your classpath or put it into the Ant-Home-Path\lib directory to be automatically be picked up when Ant is run.

Where:

• Ant-Home-Path is the path to the Ant installation.
• The value of the ANT_HOME environment variable is properly configured to run Ant (see Downloading the Development Kit).

The following XML must be added your build.xml file to use the optional Ant tasks in your build.

<!-- Definitions for tasks for Java Card tools --> 
<taskdef name="apdutool"   
  classname="com.sun.javacard.ant.tasks.APDUToolTask" /> 
<taskdef name="capgen"   
  classname="com.sun.javacard.ant.tasks.CapgenTask" /> 
<taskdef name="maskgen"   
  classname="com.sun.javacard.ant.tasks.MaskgenTask" /> 
<taskdef name="deploycap"   
  classname="com.sun.javacard.ant.tasks.DeployCapTask" /> 
<taskdef name="exp2text"   
  classname="com.sun.javacard.ant.tasks.Exp2TextTask" /> 
<taskdef name="convert" 
  classname="com.sun.javacard.ant.tasks.ConverterTask" /> 
<taskdef name="verifyexport" 
  classname="com.sun.javacard.ant.tasks.VerifyExpTask" /> 
<taskdef name="verifycap" 
  classname="com.sun.javacard.ant.tasks.VerifyCapTask" /> 
<taskdef name="verifyrevision" 
  classname="com.sun.javacard.ant.tasks.VerifyRevTask" /> 
<taskdef name="scriptgen" 
  classname="com.sun.javacard.ant.tasks.ScriptgenTask" /> 
<typedef name="appletnameaid" 
  classname="com.sun.javacard.ant.types.AppletNameAID" /> 
<typedef name="jcainputfile" 
  classname="com.sun.javacard.ant.types.JCAInputFile" /> 
<typedef name="exportfiles" 
  classname="org.apache.tools.ant.types.FileSet" />

Library Dependencies

The libraries from the Java Card development kit in TABLE B-1 are needed in your classpath if you are using the indicated feature. Alternatively, you can specify the classpath nested element for each task to put the required JAR files in the classpath during build execution.

offcardverifier.jar 

capdump.jar 

scriptgen.jar 

---

Ant Task Descriptions

The eleven Ant tasks provided in the Ant tasks bundle are provided to simplify the use of the development kit for Ant users. This section describes each of these Ant tasks and how to use them. Note that the JAR files for the tasks are expected to be in the system classpath, unless otherwise noted.

• APDUTool.
• CapDump.
• Capgen.
• Converter.
• DeployCap.
• Exp2Text.
• Maskgen.
• Scriptgen.
• VerifyCap.
• VerifyExp.
• VerifyRev.

APDUTool

Runs APDUTool to send the APDU script file to cref and check if all APDUs were sent correctly. You can set CheckDownloadFailure=true to stop the build if any response status is not 9000.

APDUTool is invoked in a different instance of the Java Virtual Machine^[1] software (JVM software) than the one being used by Ant.

Errors

Execution of this task fails if any of the required elements are not supplied, if apdutool.jar and apduio.jar are not in the classpath, or if APDUTool returns an error code.

Examples

Runs APDUTool to send APDUs in APDU script file test.scr to cref and to check if all APDUs were sent correctly. Also checks that the response returned from the card was 9000.

<target name="APDUToolTarget" >
        <apdutool
            scriptFile="${samples.helloworld.script}"
            outEEFile="${samples.eeprom}/outEEFile"
            CrefExe="${jcardkit_home}/bin/cref.exe">
        </apdutool>
</target>

Run the APDUTool to install the APDU script in test.scr file to cref and check if the APDU commands were processed successfully. Classpath in this example is referenced by the classpath refid.

<target name="APDUToolTarget" > 
  <apdutool 
      scriptFile="${samples.helloworld.script}" 
      outEEFile="${samples.eeprom}/outEEFile" 
      CheckDownloadFailure="true" 
      CrefExe="${jcardkit_home}/bin/cref.exe"> 
      <classpath refid="classpath"/> 
  </apdutool>
</target>

Run APDUTool to install the APDU script in test.scr file to cref, which is initialized using a stored EEPROM image from the file inEEFile. Also check if the APDU commands were sent correctly. Classpath used in this example is referenced by the classpath refid.

<target name="APDUToolTarget" > 
  <apdutool 
      scriptFile="${samples.helloworld.script}" 
      outEEFile="${samples.eeprom}/outEEFile" 
      inEEFile="${samples.eeprom}/inEEFile" 
      CheckDownloadFailure="true" 
      CrefExe="${jcardkit_home}/bin/cref.exe"> 
      <classpath refid="classpath"/> 
  </apdutool>
</target>

CapDump

Runs the CapDump tool to dump the contents of a CAP file.

Errors

Execution of this task fails if CapFile element is not supplied, if capdump.jar is not in the classpath, or if CapDump returns an error code.

Examples

Run CapDump to dump the contents of the test.cap file.

<target name="CapDumpTarget" > 
  <capdump 
      CapFile="${samples.output}/test.cap" 
  </capdump>
</target>

Run CapDump to dump the contents of the test.cap file. Classpath used in this example is referenced by the classpath refid

<target name="CapDumpTarget" > 
  <capdump 
      CapFile="${samples.output}/test.cap" 
      <classpath refid="classpath"/> 
  </capdump>
</target>

Capgen

Runs Capgen to generate a CAP file from a JCA file.

Errors

Execution of this task fails if any of the required elements are not supplied, if converter.jar is not in the classpath, or if Capgen returns an error code.

Examples

Run Capgen to generate the mathDemo.cap file from the mathDemo.jca file.

<target name="CapgenTarget" > 
  <capgen 
      JCAFile="${sample.output}/mathDemo.jca" 
      outfile="${sample.output}/mathDemo.cap"> 
      <classpath refid="classpath"/> 
  </capgen>
</target>

Run Capgen to generate a mathDemo.cap file from the mathDemo.jca file. Classpath used in this example is referenced by the classpath refid.

<target name="CapgenTarget" > 
  <capgen 
      JCAFile="${sample.output}/mathDemo.jca" 
      outfile="${sample.output}/mathDemo.cap"> 
      <classpath refid="classpath"/> 
  </capgen>
</target>

The following example is the same as the previous example, except no output file is specified. Capgen generates out.cap in the directory in which the JVM software was invoked.

<target name="CapgenTarget" > 
  <capgen 
      JCAFile="${sample.output}/mathDemo.jca"/> 
      <classpath refid="classpath"/> 
  </capgen>
</target>

Converter

Runs Converter to generate CAP, EXP and JCA files from a Java technology-based package. By default the Java Card platform converter creates CAP and EXP files for the input package. However, if any one of the CAP, JCA or EXP flags are enabled, only the output files enabled are generated.

Parameters Specified As Nested Elements

AppletNameAID

Use nested element AppletNameAID to specify names and AIDs of applets belonging to the package being converted. For details regarding AppletNameAID type, see AppletNameAID.

Errors

Execution of this task fails if any of the required elements are not supplied, if converter.jar or offcardverifier.jar are not in the classpath, or if Converter returns an error code.

Examples

Run Converter to generate helloworld.cap, helloworld.JCA and helloworld.EXP files.

<target name="convert_HelloWorld.cap" > 
  <convert 
      JCA="true" 
      EXP="true" 
      CAP="true" 
      packagename="com.sun.javacard.samples.HelloWorld" 
      packageaid="0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1" 
      majorminorversion="1.0" 
      classdir="${classroot}" 
      outputdirectory="${classroot}"> 
      <AppletNameAID 
          appletname="com.sun.javacard.samples.HelloWorld.HelloWorld" 
          aid="0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1:0x1"/> 
      <exportpath refid="export"/> 
      <classpath refid="classpath"/> 
  </convert>
</target>

In the following example the converter options are specified in helloworld.cfg file instead of being specified in the target itself. This example also shows how a classpath can be specified for a target and how a directory can be set in which the Java VM is invoked for the converter task.

<target name="convert_HelloWorld" > 
  <convert 
      dir="${samples}" 
      Configfile="${samples.configDir}/helloworld.cfg"> 
      <classpath> 
          <pathelement path="${samples}"/> 
          <fileset dir="${lib}"> 
              <include name="**/converter.jar"/> 
              <include name="**/offcardverifier.jar"/> 
          </fileset> 
      </classpath> 
  </convert>
</target> 

DeployCap

This task sends a CAP file to cref and hides the complexities of creating a script file, running cref and then running APDUTool to send the script to cref. The resulting EEPROM image is saved in the specified output file. This task automatically checks if installation was successful or not by checking status words returned by cref.

Errors and Return Codes

Execution of this task fails if any of the required elements are not supplied, if apdutool.jar, apduio.jar and scriptgen.jar are not in the classpath, or if APDUTool, Scriptgen or cref fail to execute.

Examples

The following example installs helloworld.cap file in cref. By default it is checked if the APDU commands were sent correctly. Classpath used in the above example is referenced by the classpath refid.

<target name="Deploy_Hello_world_CAP" > 
  <deploycap 
      CAPFile="${samples.output}/helloworld.cap" 
      outEEFile="${samples.eeprom}/outEEFile" 
      CrefExe="{JAVACARD_HOME}/bin/cref"> 
      <classpath refid="classpath"/> 
  </deploycap>
</target> 

The following example installs helloworld.cap file in cref, which in this case will be initialized with EEFile. The cref output EEPROM image will also be saved in the same EEFile. By default it is checked if the APDU commands were sent correctly. This example shows that the resulting EEPROM image can be stored in the same EEPROM image file that was used to initialize cref.

<target name="Deploy_Hello_world_CAP" > 
  <deploycap 
      CAPFile="${samples.output}/helloworld.cap" 
      outEEFile="${samples.eeprom}/EEFile" 
      inEEFile="${samples.eeprom}/EEFile" 
      CrefExe="{JAVACARD_HOME}/bin/cref"> 
      <classpath refid="classpath"/> 
  </deploycap>
</target> 

Exp2Text

Run Exp2Text tool to convert the export file of a package to a text file.

Errors

Execution of this task fails if any of the required elements are not supplied, if converter.jar is not in the classpath, or if Exp2Text returns an error code.

Examples

Run Exp2Text to generate text file from the export file of package HelloWorld. This example assumes that converter.jar is already in classpath.

<target name="Exp2TextTarget" > 
  <Exp2Text 
      packagename="com.sun.javacard.samples.HelloWorld" 
      classdir="${classroot}" 
      outputdir="${classroot}"> 
  </Exp2Text>
</target>

Run Exp2Text to generate text file from the export file of package HelloWorld. Classdir and the root outputdir are both assumed to be the directory where the Java VM was invoked. Classpath used in this example is referenced by the classpath refid.

<target name="Exp2TextTarget" > 
  <Exp2Text 
      packagename="com.sun.javacard.samples.HelloWorld"> 
      <classpath refid="classpath"/> 
  </Exp2Text>
</target>

Maskgen

Runs Maskgen to generate a mask for cref, depending on the generator used (see details below).

Parameters Specified As Nested Elements

JCAInputFile

Use nested element JCAInputFile to specify names of input JCA files for Maskgen. Input JCA files are required to create a Mask file. The reason a standard FileSet to specify JCA file names is not used here is that Maskgen supports input file names that starts with an “@” symbol to specify an input file that contains a list of names of input JCA files. A file name that starts with “@” is not supported by any of the standard Ant types. See description for JCAInputFile for details.

Errors

Execution of this task fails if any of the required elements are not supplied, if converter.jar is not in the classpath or if Maskgen returns an error code.

Examples

Run Maskgen to generate mask.c file from input JCA files specified in files mask1.in and mask2.in.

<target name="MasgenTarget" > 
  <maskgen  
      generator="cref"  
      configfile="${maskDir}/mask.cfg" 
      outfile="${crefDir}/common/mask.c" > 
      <jcainputfile inputfile="@${maskDir}/mask1.in" / > 
      <jcainputfile inputfile="@${maskDir}/mask2.in" / > 
  </maskgen >
</target >

Run Maskgen to generate mask.c file from input JCA files specified in files api.in and installer and helloworld JCA files.

<target name="MasgenTarget" > 
  <maskgen  
      generator="cref"  
      configfile="${maskDir}/mask.cfg" 
      outfile="${crefDir}/common/mask.c" > 
      <jcainputfile inputfile="@${maskDir}/api.in" / > 
      <jcainputfile inputfile="${jcaDir}/installer.jca" / > 
      <jcainputfile inputfile="${jcaDir}/helloworld.jca" / > 
  </maskgen >
</target >

The following example is the same as the previous example, except no output file is specified and classpath is specified. Maskgen will generate the file a.out in the directory in which Java VM was invoked.

<target name="MasgenTarget" > 
  <maskgen  
      generator="cref"  
      configfile="${maskDir}/mask.cfg" 
      outfile="${crefDir}/common/mask.c" > 
      <jcainputfile inputfile="@${maskDir}/api.in" / > 
      <jcainputfile inputfile="${jcaDir}/installer.jca" / > 
      <jcainputfile inputfile="${jcaDir}/helloworld.jca" / > 
      <classpath refid="classpath"/> 
  </maskgen >
</target >

Scriptgen

Runs Scriptgen to generate an APDU script file from a CAP file.

Errors

Execution of this task fails if any of the required elements are not supplied, if scriptgen.jar is not in the classpath or if Scriptgen returns an error code.

Examples

Run Scriptgen to generate script file helloWorld.scr from helloWorld.cap file. Classpath used in this example is referenced by the classpath refid.

<target name="ScriptgenTarget" > 
  <scriptgen  
      noBeginEnd="true" 
      noBanner="true" 
      CapFile="${samples.helloworld.output}/HelloWorld.cap"  
      outFile="${samples.helloworld.script}/helloWorld.scr" > 
      <classpath refid="classpath" /> 
  </scriptgen >
</target >

VerifyCap

Runs off-card Java Card platform CAP file verifier to verify a CAP file. The Java Card platform off-card verifier is invoked in a separate instance of Java VM.

Parameters Specified As Nested Elements

ExportFiles

Use nested element ExportFiles to specify group of export files for packages imported by the package whose CAP file is being verified and the export file corresponding to the CAP being verified. For details regarding ExportFiles type see ExportFiles.

Errors

Execution of this task fails if any of the required elements are not supplied, if offcardverifier.jar is not in the classpath, or if Verifier returns an error code.

Examples

Run the Java Card platform off-card verifier to verify HelloWorld.cap file.

<target name="VerifyCapTarget" > 
  <verifycap  
      CapFile="${samples.helloworld.output}/HelloWorld.cap" > 
      <exportfiles file="${samples.helloworld.output}/HelloWorld.exp" /> 
      <exportfiles file="${api_exports}/javacard/framework/javacard/framework.exp" /> 
      <exportfiles file="${api_exports}/java/lang/javacard/lang.exp" /> 
      <classpath refid="classpath"/> 
  </verifycap>
</target> 

VerifyExp

Runs off-card Java Card platform EXP file verifier to verify an EXP file. Java Card platform off-card verifier is invoked in a separate instance of Java VM.

Parameters Specified As Nested Elements

ExportFiles

Use nested element ExportFiles to specify the EXP file being verified. For details regarding ExportFiles type see ExportFiles. VerifiyExp requires that only one input EXP file be specified. This tasks throws an error if more than one EXP files are specified.

Errors

Execution of this task fails if no EXP file is specified or if more than one EXP file is specified, if offcardverifier.jar is not in the classpath, or if Verifier returns an error code.

Examples

Run the Java Card platform off-card verifier to verify HelloWorld.exp file.

<target name="VerifyExpTarget" > 
  <verifyExp  
      <exportfiles file="${samples.helloworld.output}/HelloWorld.exp" /> 
      <classpath refid="classpath"/> 
  </verifyExp>
</target> 

VerifyRev

Runs off-card Java Card platform verifier to verify binary compatibility between two versions of an EXP file. Java Card platform off-card verifier is invoked in a separate instance of Java VM.

Parameters Specified As Nested Elements

ExportFiles

Use nested element ExportFiles to specify the EXP files being verified. For details regarding ExportFiles type see ExportFiles. VerifiyExp requires that exactly two input EXP files are specified. This tasks throws an error if more or less than two EXP files are specified.

Errors

Execution of this task fails if no EXP file is specified or if less or more than two EXP files are specified, if offcardverifier.jar is not in the classpath, or if Verifier returns an error code.

Examples

Run the Java Card platform off-card verifier to verify binary compatibility between two versions of HelloWorld.exp file.

<target name="VerifyExpTarget" > 
  <verifyExp  
      <exportfiles file="${samples.helloworld.output}/HelloWorld.exp" /> 
      <exportfiles file="${samples.helloworld.output.new}/HelloWorld.exp" /> 
      <classpath refid="classpath"/> 
  </verifyExp>
</target> 

---

Custom Types

AppletNameAID

AppletNameAID groups together name and AID for a Java Card applet.

Example

Set the fully qualified name and AID for the HelloWorld applet.

<AppletNameAID
appletname="com.sun.javacard.samples.HelloWorld.HelloWorld"
aid="0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1:0x1"/>

JCAInputFile

This type is a simple wrapper for a fully qualified JCA file name or a name of an input file that contains a list of input JCA files. In case the input file contains a list of input JCA files, the name of the file should be prepended with “@”.

Examples

Set the fully qualified name of an input JCA file.

<jcainputfile 
   inputfile="C:\jcas\common\com\sun\javacard\installer
\javacard\installer.jca" />

Set the fully qualified name of an input file that contains a list of JCA files.

<jcainputfile inputfile="@C:\jc\mathDemo.in" />

ExportFiles

This type is actually the Ant FileSet type. It is used to specify a group of export files for the off-card verifier. For details, see Apache Ant documentation for FileSet type.

Examples

The following example sets the fully qualified name of an input EXP file.

<exportfiles 
   file="C:\samples\classes\com\sun\javacard\samples
\HelloWorld\javacard\HelloWorld.exp"

The following example groups all the files in the directory ${server.src} that are EXP files and do not have the text Test in their names.

<exportfiles dir="${server.src}"> 
  <include name="**/*.exp"/> 
  <exclude name="**/*Test*"/>
</exportfiles>

---

NetBeans Software Integration

The NetBeans IDE can be used to create an Ant script for a Java technology project and run it to compile, build and run the project. The build.xml file for a NetBeans project is located in the project's root directory. You modify the appropriate build.xml file as explained in Installing the Ant Tasks to enable usage of the Ant tasks.

The NetBeans IDE recognizes some pre-defined targets in the build.xml file that is generated for a related project. Some of these targets exist, such as clean and compile, while XML for others is left empty. One of these targets is -post-compile. You can modify this target to incorporate usage of the Ant tasks in your project.

^{1 (Footnote) The terms “Java Virtual Machine” and “JVM” mean a Virtual Machine for the Java(TM) platform.}

Development Kit User’s Guide

December-2009

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.