Ant Task Descriptions

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^Foot 1 software (JVM software) than the one being used by Ant.

Table B-1 Parameters for APDUTool

Attribute	Description	Required
ScriptFile	Fully qualified path and name of the APDU script file.	Yes
CrefExe	Fully qualified path and name of `cref` executable.	Yes
OutEEFile	Output EEPROM file that contains the EEPROM image after `cref` finishes execution.	Yes
CheckDownloadFailure	Stops the build if any response status coming back from `cref` is not 9000.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory in which to invoke the JVM software.	No
InEEFile	Input EEPROM file for `cref`. If specified `cref` initiates using the EEPROM image stored in this file.	No
nobanner	Set this element to `true` if you do not want the APDUTool banner showing.	No
version	Prints the version number of APDUTool.	No

Errors

Execution of this task fails if the required attributes are not provided, JC_HOME_SIMULATOR\lib\tools_simulator.jar and JC_HOME_TOOLS\lib\tools.jar are not in the classpath, or APDUTool returns an error code.

Examples

To use these examples:

Enter the following example code to run 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>

Enter the following example code to run the APDUTool to install the APDU script in test.scr file to cref and check if the APDU commands were processed successfully:

Note:

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>

Enter the following example code to 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:

Note:

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

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

Table B-2 Parameters for CapDump

Attribute	Description	Required
CapFile	Fully qualified name of CAP file.	Yes
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory in which to invoke the JVM software.	No

Errors

Execution of this task fails if CapFile attribute is not supplied, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or CapDump returns an error code.

Examples

To use these examples:

Enter the following example code to run CapDump to dump the contents of the test.cap file:

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

Enter the following example code to run CapDump to dump the contents of the test.cap file:
Note:

Classpath used in this example code 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.

Table B-3 Parameters for Capgen

Attribute	Description	Required
JCAFile	Fully qualified path and name of the input JCA file.	Yes
OutFile	Fully qualified path and name of the output CAP file.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory in which to invoke the JVM software.	No
nobanner	Set this element to `true` if you do not want the Capgen banner showing.	No
version	Prints Capgen version number.	No

Errors

Execution of this task fails if the required attributes are not provided, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or Capgen returns an error code.

Examples

To use these examples:

Enter the following example code to run Capgen to generate the helloworld.cap file from the helloworld.jca file.

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

Enter the following example code to run Capgen to generate a helloworld.cap file from the helloworld.jca file.

Note:

Classpath used in this example is referenced by the classpath refid.

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

Enter the following example code to run Capgen as in the previous example, except no output file is specified.
Note:

Capgen generates out.cap in the directory in which the JVM software was invoked.
```
<target name="CapgenTarget" > 
  <capgen 
      JCAFile="${sample.output}/helloworld.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.

Table B-4 Parameters for Converter

Attribute	Description	Required
PackageName	Fully qualified name of the package being converted.	Yes, if the configuration file is not provided.
PackageAID	AID of the package being converted.	Yes, if the configuration file is not provided.
MajorMinorVersion	Major and Minor version numbers of the package, for example, 1.2 (where 1 is major version number and 2 is minor version number).	Yes, if the configuration file is not provided.
CAP	If enabled, tells the converter to create a CAP file.	No
EXP	If enabled, tells the converter to create a EXP file.	No
JCA	If enabled, tells the converter to create a JCA file.	No
ClassDir	The root directory of the class hierarchy. Specifies the directory where the converter looks for class files.	No
Int	If enabled, turns on support for the 32-bit integer type.	No
Debug	If enabled, enables generation of debugging information.	No
ExportPath	Root directories where the Converter looks for export files.	No
ExportMap	If enabled, tells the converter to use the token mapping from the pre-defined export file of the package being converted. The converter looks for the export file in the exportpath.	No
Outputdirectory	Sets the output directory where the output files are placed.	No
Verbose	If enabled, enables verbose converter output.	No
noWarn	If enabled, instructs the Converter to not report warning messages.	No
Mask	If enabled, tells the Converter that this package is for mask, so restrictions on native methods are relaxed.	No
NoVerify	If enabled, tells the Converter to turn off verification. Verification is turned on by default.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
nobanner	Set this element to `true` if you do not want the Capgen banner showing.	No
version	Prints Converter version number.	No
ConfigFile	Configuration file containing all the configuration parameters for the converter.	No

In addition to the parameters specified in the preceding table, the target Java Card platform can be specified for the converter through the environment variable JC_TARGET_PLATFORM. If this environment variable is set, then the converter creates the CAP files for the specified target platform.

Parameters Specified As Nested Elements

The AppletNameID parameters are specified as nested elements and 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 the required attributes are not provided, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or the Converter returns an error code.

Examples

To use these examples:

Enter the following example code to run the Converter and 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>

Enter the following example code to run the Converter with the converter options specified in the helloworld.cfg file instead of being specified in the target itself.

Note:

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.

Table B-5 Parameters for DeployCap

Attribute	Description	Required
CapFile	Fully qualified path and name of the CAP file which is to be sent to `cref`.	Yes
CrefExe	Fully qualified path and name of `cref` executable.	Yes
OutEEFile	Output EEPROM file that contains the EEPROM image after `cref` finishes execution.	Yes
InEEFile	Input EEPROM file for `cref`. If specified `cref` initiates using the EEPROM image stored in this file.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
nobanner	Set this element to `true` if you do not want the tool banner showing.	No

Errors and Return Codes

Execution of this task fails if the required attributes are not provided, JC_HOME_SIMULATOR\lib\tools_simulator.jar and JC_HOME_TOOLS\lib\tools.jar are not in the classpath, APDUTool, scriptgen, or cref fail to execute.

Examples

To use these examples:

Enter the following example code to install helloworld.cap file in cref:

Note:

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>

Enter the following example code to install helloworld.cap file in cref, which in this case is initialized with EEFile:
Note:

The cref output EEPROM image is also 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.

Table B-6 Parameters for Exp2Text

Attribute	Description	Required
PackageName	Fully qualified name of the package.	Yes
ClassDir	Root directory where the exp2text tool looks for the export file. If no ClassDir is specified, the directory in which the Java VM is invoked is taken as base dir.	No
OutputDir	The root directory for output.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
nobanner	Set this element to `true` if you do not want the Exp2Text banner showing.	No
version	Prints Exp2Text version number.	No

Errors

Execution of this task fails if the required attributes are not provided, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or Exp2Text returns an error code.

Examples

To use these examples:

Enter the following example code to run Exp2Text and generate text file from the export file of package HelloWorld:

Note:

This example assumes that converter.jar is already in classpath.

<target name="Exp2TextTarget" > 
  <exp2text 
      packagename="com.oracle.jcclassic.samples.helloworld" 
      classdir="${classroot}" 
      outputdir="${classroot}"> 
  </exp2text>
</target>

Enter the following example code to run Exp2Text and generate text file from the export file of package HelloWorld:
Note:

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.oracle.jcclassic.samples.helloworld"> 
      <classpath refid="classpath"/> 
  </exp2text>
</target>
```

Scriptgen

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

Table B-7 Parameters for Scriptgen

Attribute	Description	Required
CapFile	Fully qualified path and name of the input CAP file.	Yes
HashFile	Fully qualified path and name of the verifier-generated file that contains the hashes for all the components in the input CAP file.	Yes
OutFile	Fully qualified path and name of the output script file. If no output file name is specified, generated script is output on the console.	No
PkgName	Fully qualified name of the package inside the CAP file.	No
NoBeginEnd	If enabled, instructs Scriptgen to suppress "CAP_BEGIN", "CAP_END" APDU commands.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
nobanner	Set this element to `true` if you do not want the Scriptgen banner showing.	No
version	Prints Scriptgen version number.	No

Errors

Execution of this task fails if the required attributes are not provided, JC_HOME_SIMULATOR\lib\tools_simulator.jar and JC_HOME_TOOLS\lib\tools.jar are not in the classpath, or Scriptgen returns an error code.

Examples

To use these examples:

Enter the following example code to run Scriptgen and generate script file helloWorld.scr from helloWorld.cap file.

Note:

Classpath used in this example is referenced by the classpath refid.

<target name="ScriptgenTarget" > 
  <scriptgen  
      noBeginEnd="true" 
      noBanner="true" 
      HashFile="${samples.helloworld.output}/HelloWorld.hash"
      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.

Table B-8 Parameters for VerifyCap

Attribute	Description	Required
CapFile	Fully qualified path and name of CAP file that is to be verified.	Yes
PkgName	Fully qualified Name of the package inside the CAP file for which the CAP file was generated.	No
noWarn	If enabled, tells the verifier not to output any warning messages.	No
Verbose	If enabled, enables verbose verifier output.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
outFile	Fully qualified output path of the digest file, which contains the digests generated using the default algorithm (SHA-256) for all CAP file components.
nobanner	Set this element to `true` if you want to suppress Verifier banner.	No
version	Prints the version number of the off-card verifier.	No

Parameters Specified As Nested Elements

The ExportFiles are parameters specified as nested elements that 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 the required attributes are not provided, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or Verifier returns an error code.

Examples

To use these examples:

Enter the following example code to run the Java Card platform off-card verifier and verify the 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.

Table B-9 Parameters for VerifyExp

Attribute	Description	Required
noWarn	If enabled, tells the verifier not to output any warning messages.	No
Verbose	If enabled, enables verbose verifier output.	No
classpath	Classpath to use for this task. If required JAR files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
nobanner	Set this element to `true` if you want to suppress Verifier banner.	No
version	Prints the version number of off-card verifier.	No

Parameters Specified As Nested Elements

The ExportFiles are parameters specified as nested elements that 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 none or more than one EXP file are specified, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or Verifier returns an error code.

Examples

To use these examples:

Enter the following example code to run the Java Card platform off-card verifier to verify HelloWorld.exp file:

<target name="VerifyExpTarget" > 
  <verifyexport>  
      <exportfiles file="${samples.helloworld.output}/HelloWorld.exp" /> 
      <classpath refid="classpath"/> 
  </verifyexport>
</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.

Table B-10 Parameters for VerifyRev

Attribute	Description	Required
noWarn	If enabled, tells the verifier not to output any warning messages.	No
Verbose	If enabled, enables verbose verifier output.	No
classpath	Classpath to use for this task. If required jar files are not already in the system classpath, you can specify this attribute to put them in the classpath when this task is executed.	No
dir	The directory to invoke the Java VM in.	No
nobanner	Set this element to `true` if you want to suppress Verifier banner.	No
version	Prints the version number of off-card verifier.	No

Parameters Specified As Nested Elements

The ExportFiles are parameters specified as nested elements that use nested element ExportFiles to specify the EXP files being verified. For details regarding ExportFiles type see ExportFiles. VerifyExp requires that exactly two input EXP files are specified: it throws an error if that is not the case.

Errors

Execution of this task fails if no EXP file is specified. It also fails if exactly two EXP files are not specified, JC_HOME_TOOLS\lib\tools.jar is not in the classpath, or Verifier returns an error code.

Examples

To use these examples:

Enter the following example code to run the Java Card platform off-card verifier to verify binary compatibility between two versions of HelloWorld.exp file.

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