| Ant Tasks User's Guide, Java Card Platform, Version 2.2.2
|
   
|
The eleven Ant tasks provided in the Ant tasks bundle might simplify the use of the development kit tools for Ant users. This chapter describes 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
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 (VM) than the one being used by Ant.
TABLE 3-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 will contain 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 to invoke the Java VM in.
|
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 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.
TABLE 0-1 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 to invoke the Java VM in.
|
No
|
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.
TABLE 3-2 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 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 Capgen version number.
|
No
|
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 Java VM 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.
TABLE 3-3 Parameters for Converter
|
Attribute
|
Description
|
Required
|
|
PackageName
|
Fully qualified name of the package being converted.
|
Yes
|
|
PackageAID
|
AID of the package being converted.
|
Yes
|
|
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
|
|
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 will look for class files.
|
No
|
|
Int
|
If enabled turns on support the 32-bit integer type.
|
No
|
|
Debug
|
If enabled, enables generation of debugging information.
|
No
|
|
ExportPath
|
Root directories where the Converter will look 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 will look for the export file in the exportpath.
|
No
|
|
Outputdirectory
|
Sets the output directory where the output files will be 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
|
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.
TABLE 3-4 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 will contain 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 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.
TABLE 3-5 Parameters for Exp2Text
|
Attribute
|
Description
|
Required
|
|
PackageName
|
Fully qualified name of the package.
|
Yes
|
|
ClassDir
|
Root directory where the exp2text tool will look 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 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).
TABLE 3-6 Parameters for Maskgen
|
Attribute
|
Description
|
Required
|
|
Generator
|
Tells Maskgen for which platform is the mask to be generated. Possible choices are a51, cref, and size. For details see Maskgen documentation in the User's Guide for the Java Card Platform, Version 2.2.2 (Sun Microsystems, Inc., 2006).
|
Yes
|
|
ConfigFile
|
Fully qualified path and name of generator specific configuration file.
|
No
|
|
DebugInfo
|
If enabled, tells Maskgen to generate location debug information for mask.
|
No
|
|
MemRefSize
|
Integer value that tells Maskgen what memory reference size to use in the mask. Two possible values for element are 16 and 32. Default value used by Maskgen is 32.
|
No
|
|
OutFile
|
Fully qualified path and name of the output mask file. If this element is not specified, default file name is a.out which will be generated in the directory where the Java VM is invoked.
|
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 Capgen version number.
|
No
|
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.
TABLE 3-7 Parameters for Scriptgen
|
Attribute
|
Description
|
Required
|
|
CapFile
|
Fully qualified path and name of 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 will be 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 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.
TABLE 3-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 converter 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 the off-card verifier.
|
No
|
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.
TABLE 3-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 converter 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
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.
TABLE 3-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 converter 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
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>
|