Ant Tasks User s Guide

Transcription

1 Ant Tasks User s Guide Java Card Platform, Version Sun Microsystems, Inc

2 Copyright 2005 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and in other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, Java, Solaris, Sparc, Java Card, Java Developer Connection, Javadoc, JDK, JVM, J2ME, NetBeans and J2SE are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Products covered by and information contained in this service manual are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON- INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 2005 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés. Sun Microsystems, Inc. détient les droits de propriété intellectuels relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plus des brevets américains listés à l'adresse et un ou les brevets supplémentaires ou les applications de brevet en attente aux Etats - Unis et dans les autres pays.l'utilisation est soumise aux termes de la Licence. Cette distribution peut comprendre des composants développés par des tierces parties. Des parties de ce produit pourront être dérivées des systèmes Berkeley BSD licenciés par l'université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d'autres pays et licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, Java, Solaris, Sparc, Java Card, Java Developer Connection, Javadoc, JDK, JVM, J2ME, NetBeans et J2SE sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Les produits qui font l'objet de ce manuel d'entretien et les informations qu'il contient sont regis par la legislation americaine en matiere de controle des exportations et peuvent etre soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucleaires, des missiles, des armes biologiques et chimiques ou du nucleaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou reexportations vers des pays sous embargo des Etats-Unis, ou vers des entites figurant sur les listes d'exclusion d'exportation americaines, y compris, mais de maniere non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une facon directe ou indirecte, aux exportations des produits ou des services qui sont regi par la legislation americaine en matiere de controle des exportations et la liste de ressortissants specifiquement designes, sont rigoureusement interdites. LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.

3 Contents 1. Introduction 1 2. Installing the Ant Tasks 3 System Requirements 3 Installing Apache Ant 3 Installing the Ant Tasks 4 Setting Up the Ant Tasks 4 Library Dependencies 5 3. Using the Ant Tasks 7 APDUTool 7 Errors 8 Examples 8 CapDump 10 Errors 10 Examples 10 Capgen 11 Errors 11 Examples 11 Converter 13 iii

4 Parameters Specified As Nested Elements 14 AppletNameAID 14 Errors 14 Examples 14 DeployCap 16 Errors and Return Codes 16 Examples 16 Exp2Text 18 Errors 18 Examples 18 Maskgen 20 Parameters Specified As Nested Elements 20 JCAInputFile 20 Errors 21 Examples 21 Scriptgen 22 Errors 22 Examples 22 VerifyCap 24 Parameters Specified As Nested Elements 24 ExportFiles 24 Errors 24 Examples 25 VerifyExp 26 Parameters Specified As Nested Elements 26 ExportFiles 26 Errors 26 Examples 26 Contents iv

5 VerifyRev 28 Parameters Specified As Nested Elements 28 ExportFiles 28 Errors 28 Examples Custom Types 31 AppletNameAID 31 Example 31 JCAInputFile 32 Examples 32 ExportFiles 32 Examples NetBeans Software Integration Ant Tasks Example 39 Contents v

6 vi Ant Tasks User s Guide, Java Card Platform, Version March 2006

7 Preface This book describes how to use the optional and unsupported Ant tasks included in the Ant tasks bundle of the Java Card development kit. These tasks are designed to work with version of Apache Ant (as verified with Ant version). Java Card technology combines a portion of the Java programming language with a runtime environment optimized for smart cards and related, small-memory embedded devices. The goal of Java Card technology is to bring many of the benefits of the Java programming language to the resource-constrained world of smart cards. Who Should Use This Book This book is intended to assist users of the Java Card development kit in using the tools included in the Ant tasks bundle, particularly if the users are already familiar with Ant. Use of Ant as described in this document is unsupported. Before You Read This Book Before reading this guide, you should be familiar with Apache Ant, the Java programming language, Java Card technology, and smart card technology. A good resource for becoming familiar with Java technology and Java Card technology is the Sun Microsystems, Inc. web site, located at: vii

8 Related Books The following documents might prove useful: User s Guide for the Java Card Platform, Version Programming tes for the Java Card Platform, Version Apache Ant documentation at Typographic Conventions TABLE P-1 Typographic Conventions Used in This Book Typeface Meaning Examples AaBbCc123 The names of commands, files, and directories; on-screen computer output Edit your.login file. Use ls -a to list all files. % You have mail. AaBbCc123 What you type, when contrasted with on-screen computer output % su Password: AaBbCc123 Book titles, new words or terms, words to be emphasized Read Chapter 6 in the User s Guide. These are called class options. You must be superuser to do this. Command-line variable; replace with a real name or value To delete a file, type rm filename. Accessing Sun Documentation Online Access Java platform technical documentation on the web at the Java Developer Connection program web site at: viii Ant Tasks User s Guide, Java Card Platform, Version March 2006

9 Sun Welcomes Your Comments We are interested in improving our documentation and welcome your comments and suggestions. your comments to us at Preface ix

10 x Ant Tasks User s Guide, Java Card Platform, Version March 2006

11 CHAPTER 1 Introduction The Java Card platform, version development kit comes with a set of command line tools to help developers create, verify and test their Java Card-based applications. Those tools use Apache Ant, but users are not required to use Ant directly. For more information on the development tools and how Ant is used by them, refer to Development Kit User s Guide for the Java Card Platform, Version However, the Ant tasks as described in this book are included in the Ant tasks bundle, not the development kit. These Ant tasks are designed for Ant users who might wish to use them to make use of the development kit tools more efficient. Use of the Ant tasks as described in this book is strictly optional and not supported by Sun Microsystems, Inc. Javadoc tool files for the Ant tasks are located in this bundle in HTML format at java_card_kit-2_2_2/ant-tasks/docs/html/javadocs. A compilation of the Javadoc tool files in PDF format is at java_card_kit-2_2_2/anttasks/docs/pdf/ant-tasks-javadocs.pdf. 1

12 2 Ant Tasks User s Guide, Java Card Platform, Version March 2006

13 CHAPTER 2 Installing the Ant Tasks System Requirements To use the current version of these tasks, you will need version 1.5.0_03 of the Java Runtime Environment and version of Apache Ant installed on your system. You can obtain Apache Ant on documentation on Ant from the Apache web site at The Ant tasks included in the Ant Tasks bundle have been tested on Solaris 10 operating system and Windows XP (Pro), though they might work on other platforms as well. Installing Apache Ant The development kit requires Ant to run its tools and the demos. Once Ant is installed, the use of Ant in the development kit will not be apparent. If you have already installed Apache Ant version for use in the development kit, you can skip this procedure. te Ant is supported for use within the development kit, but its use as described in this book is not supported, nor have the Ant tasks been thoroughly tested. 1. Download and unzip Apache Ant in a separate directory. 3

14 If you don't already have Apache Ant version installed on your system, you must download it from their web site at Unzip the package in a directory that is separate from the development kit. 2. Add Ant to your system path. Add Ant's bin directory to your system path. Installing the Ant Tasks 1. Install Ant as described in Installing Apache Ant on page Unzip the Ant tasks bundle. If you haven t already, unzip the Ant tasks bundle, which is included in the binary product and named java_card_kit-2_2_2-rr-ant-tasks.zip. When you unzip the Ant tasks bundle, the Ant tasks' Java Archive (JAR) file, jctasks.jar, is extracted into the subdirectory java_card_kit-2_2_2/ant-tasks/lib. This user s guide is extracted into the subdirectory java_card_kit-2_2_2/anttasks/docs in PDF and HTML format. 3. Copy the file jctasks.jar to a directory that will serve as your Ant tasks home directory. This directory will be called JC_ANT_TASK_HOME throughout this book. 4. Add the file JC_ANT_TASK_HOME/lib/jctasks.jar to your classpath or put jctasks.jar into a directory named ANT_HOME/lib, from which it will automatically be picked up when Ant is run. Setting Up the Ant Tasks The following XML must be added your build.xml file to use the 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" 4 Ant Tasks User s Guide, Java Card Platform, Version March 2006

15 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 2-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. Chapter 2 Installing the Ant Tasks 5

16 TABLE 2-1 LIBRARIES Library Dependencies FEATURES converter.jar and offcardverifier.jar offcardverifier.jar apdutool.jar and apduio.jar capdump.jar scriptgen.jar apdutool.jar, apduio.jar and scriptgen.jar Creating CAP, EXP or JCA files. Using maskgen to create a mask. Dumping contents of an EXP file in a text file. Verifying EXP files, CAP files and verifying binary compatibility between two versions of an export file. Sending an APDU script to cref. Dumping contents of a CAP file. Generating a APDU script from a CAP file. Installing a CAP file in cref and generate resulting EEPROM image. 6 Ant Tasks User s Guide, Java Card Platform, Version March 2006

17 CHAPTER 3 Using the Ant Tasks 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. te that the JAR files for the tasks are expected to be in the system classpath, unless otherwise noted. APDUTool on page 7. CapDump on page 10. Capgen on page 11. Converter on page 13. DeployCap on page 16. Exp2Text on page 18. Maskgen on page 20. Scriptgen on page 22. VerifyCap on page 24. VerifyExp on page 26. VerifyRev on page 28. 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

18 APDUTool is invoked in a different instance of the Java Virtual Machine 1 (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 CheckDownload Failure classpath Output EEPROM file that will contain the EEPROM image after cref finishes execution. Stops the build if any response status coming back from cref is not 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. dir The directory to invoke the Java VM in. InEEFile nobanner Input EEPROM file for cref. If specified cref initiates using the EEPROM image stored in this file. Set this element to true if you do not want the APDUTool banner showing. version Prints the version number of APDUTool. Yes 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 <target name="apdutooltarget" > <apdutool scriptfile="${samples.helloworld.script}" outeefile="${samples.eeprom}/outeefile" 1. The terms "Java Virtual Machine" and "JVM" mean a Virtual Machine for the Java(TM) platform. 8 Ant Tasks User s Guide, Java Card Platform, Version March 2006

19 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> Chapter 3 Using the Ant Tasks 9

20 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. dir The directory to invoke the Java VM in. 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> 10 Ant Tasks User s Guide, Java Card Platform, Version March 2006

21 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. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you do not want the Capgen banner showing. version Prints Capgen version number. 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"> Chapter 3 Using the Ant Tasks 11

22 <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> 12 Ant Tasks User s Guide, Java Card Platform, Version March 2006

23 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). CAP If enabled tells the converter to create a CAP file. EXP If enabled tells the converter to create a EXP file. JCA If enabled tells the converter to create a JCA file. ClassDir The root directory of the class hierarchy. Specifies the directory where the converter will look for class files. Int If enabled turns on support the 32-bit integer type. Debug If enabled, enables generation of debugging information. ExportPath ExportMap Outputdirectory Root directories where the Converter will look for export files. 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. Sets the output directory where the output files will be placed. Verbose If enabled, enables verbose converter output. nowarn Mask Verify If enabled instructs the Converter to not report warning messages. If enabled tells the Converter that this package is for mask, so restrictions on native methods are relaxed. If enabled tells the Converter to turn off verification. Verification is turned on by default. Yes Chapter 3 Using the Ant Tasks 13

24 TABLE 3-3 Parameters for Converter Attribute Description Required 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you do not want the Capgen banner showing. version Prints Converter version number. 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 on page 31. 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" 14 Ant Tasks User s Guide, Java Card Platform, Version March 2006

25 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> Chapter 3 Using the Ant Tasks 15

26 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. CrefExe Fully qualified path and name of cref executable. Yes OutEEFile InEEFile classpath Output EEPROM file that will contain the EEPROM image after cref finishes execution. Input EEPROM file for cref. If specified cref initiates using the EEPROM image stored in this file. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you do not want the tool banner showing. Yes Yes 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. 16 Ant Tasks User s Guide, Java Card Platform, Version March 2006

27 <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> Chapter 3 Using the Ant Tasks 17

28 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. OutputDir The root directory for output. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you do not want the Exp2Text banner showing. version Prints Exp2Text version number. 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> 18 Ant Tasks User s Guide, Java Card Platform, Version March 2006

29 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> Chapter 3 Using the Ant Tasks 19

30 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 ConfigFile DebugInfo MemRefSize OutFile classpath 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 (Sun Microsystems, Inc., 2006). Fully qualified path and name of generator specific configuration file. If enabled, tells Maskgen to generate location debug information for mask. 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. 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. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you do not want the Capgen banner showing. version Prints Capgen version number. Yes 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 20 Ant Tasks User s Guide, Java Card Platform, Version March 2006

31 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 on page 32 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 > Chapter 3 Using the Ant Tasks 21

32 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. PkgName Fully qualified name of the package inside the CAP file. BeginEnd classpath If enabled, instructs Scriptgen to suppress "CAP_BEGIN", "CAP_END" APDU commands. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you do not want the Scriptgen banner showing. version Prints Scriptgen version number. 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" > 22 Ant Tasks User s Guide, Java Card Platform, Version March 2006

33 <classpath refid="classpath" /> </scriptgen > </target > Chapter 3 Using the Ant Tasks 23

34 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. nowarn If enabled, tells the verifier not to output any warning messages. Verbose If enabled, enables verbose converter output. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you want to suppress Verifier banner. version Prints the version number of the off-card verifier. 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 on page 32. 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. 24 Ant Tasks User s Guide, Java Card Platform, Version March 2006

35 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> Chapter 3 Using the Ant Tasks 25

36 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. Verbose If enabled, enables verbose converter output. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you want to suppress Verifier banner. version Prints the version number of off-card verifier. Parameters Specified As Nested Elements ExportFiles Use nested element ExportFiles to specify the EXP file being verified. For details regarding ExportFiles type see ExportFiles on page 32. 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 26 Ant Tasks User s Guide, Java Card Platform, Version March 2006

37 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> Chapter 3 Using the Ant Tasks 27

38 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. Verbose If enabled, enables verbose converter output. 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. dir The directory to invoke the Java VM in. nobanner Set this element to true if you want to suppress Verifier banner. version Prints the version number of off-card verifier. Parameters Specified As Nested Elements ExportFiles Use nested element ExportFiles to specify the EXP files being verified. For details regarding ExportFiles type see ExportFiles on page 32. 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 28 Ant Tasks User s Guide, Java Card Platform, Version March 2006

39 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> Chapter 3 Using the Ant Tasks 29

40 30 Ant Tasks User s Guide, Java Card Platform, Version March 2006

41 CHAPTER 4 Custom Types The custom types available for the Ant tasks are described in this chapter. AppletNameAID AppletNameAID groups together name and AID for a Java Card applet. TABLE 4-1 Parameters for ApplietNameAID Attribute Description Required appletname Fully qualified name of the Java Card applet. Yes aid AID (Application Identifier) of the Java Card applet. Yes 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"/> 31

42 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 "@". TABLE 4-2 Parameters for JCAInputFile Attribute Description Required inputfile Fully qualified name of the input file Yes 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}"> 32 Ant Tasks User s Guide, Java Card Platform, Version March 2006

43 <include name="**/*.exp"/> <exclude name="**/*test*"/> </exportfiles> Chapter 4 Custom Types 33

44 34 Ant Tasks User s Guide, Java Card Platform, Version March 2006

45 CHAPTER 5 NetBeans Software Integration NetBeans integrated development environmnet 4.1 creates Ant script for Java technology projects and uses this script to compile, build and run projects. The build.xml file for a NetBeans project is located in the project's root directory. Modify this build.xml file as explained in Chapter 2 to enable usage of the Ant tasks. Netbeans software recognizes some pre-defined targets in the build.xml file that is generated for the 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 may safely modify this target to incorporate usage of the Ant tasks in your project. An example of a modified build.xml file for a NetBeans project is included here. For information on NetBeans software, go to the NetBeans integrated development environment web site at build.xml Modified for a NetBeans Project CODE EXAMPLE 5-1 <?xml version="1.0" encoding="utf-8"?> <!-- You may freely edit this file. See commented blocks below for --> <!-- some examples of how to customize the build. --> <!-- (If you delete it and reopen the project it will be recreated.) --> <project name="javapurse" default="default" basedir="."> <description>builds, tests, and runs the project JavaPurse.</description> <import file="nbproject/build-impl.xml"/> <!-- There exist several targets which are by default empty and which can be used for execution of your tasks. These targets are usually executed before and after some main targets. They are: -pre-init: called before initialization of project properties -post-init: called after initialization of project properties -pre-compile: called before javac compilation -post-compile: called after javac compilation -pre-compile-single: called before javac compilation of single file -post-compile-single: called after javac compilation of single file -pre-compile-test: called before javac compilation of JUnit tests -post-compile-test: called after javac compilation of JUnit tests -pre-compile-test-single: called before javac compilation of single JUnit test 35

46 CODE EXAMPLE 5-1 build.xml Modified for a NetBeans Project (Continued) -post-compile-test-single: called after javac compilation of single JUunit test -pre-jar: called before JAR building -post-jar: called after JAR building -post-clean: called after cleaning build products (Targets beginning with '-' are not intended to be called on their own.) Example of inserting an obfuscator after compilation could look like this: <target name="-post-compile"> <obfuscate> <fileset dir="${build.classes.dir}"/> </obfuscate> </target> For list of available properties check the imported nbproject/build-impl.xml file. Another way to customize the build is by overriding existing main targets. The targets of interest are: -init-macrodef-javac: defines macro for javac compilation -init-macrodef-junit: defines macro for junit execution -init-macrodef-debug: defines macro for class debugging -init-macrodef-java: defines macro for class execution -do-jar-with-manifest: JAR building (if you are using a manifest) -do-jar-without-manifest: JAR building (if you are not using a manifest) run: execution of project -javadoc-build: Javadoc generation test-report: JUnit report generation An example of overriding the target for project execution could look like this: <target name="run" depends="javapurse-impl.jar"> <exec dir="bin" executable="launcher.exe"> <arg file="${dist.jar}"/> </exec> </target> tice that the overridden target depends on the jar target and not only on the compile target as the regular run target does. Again, for a list of available properties which you can use, check the target you are overriding in the nbproject/build-impl.xml file. --> <!-- the directory structure under the base directory --> <property name="sourceroot" value="src" /> <property name="classroot" value="build/classes" /> <property name="exportmap" value="exportmap" /> <!-- the directories where the Java Card(TM) export are located --> <!-- could go into a properties file--> <property name="jcardkit_home" value="c:\java_card_kit-2_2_2" /> <property name="jcardkit_exports" value="${jcardkit_home}/api_export_files" /> 36 Ant Tasks User s Guide, Java Card Platform, Version March 2006

47 CODE EXAMPLE 5-1 build.xml Modified for a NetBeans Project (Continued) <property name="jcardkit_libs" value="${jcardkit_home}/lib" /> <!-- 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" /> <!-- set the export path to the Java Card export files --> <path id="export" description="set the export file path"> <pathelement path="${jcardkit_exports}" /> <pathelement path="build/classes"/> </path> <!-- set the classpath at minimum to the Java Card API --> <!-- but also for all other API needed in the project--> <path id="classpath" description="sets the classpath to Java Card API and tools"> <pathelement path="${jcardkit_home}/lib/api.jar"/> <pathelement path="${jcardkit_home}/lib/converter.jar"/> <pathelement path="${jcardkit_home}/lib/offcardverifier.jar"/> <pathelement path="${jcardkit_home}/lib/scriptgen.jar"/> <pathelement path="${jcardkit_home}/lib/apdutool.jar"/> <pathelement path="${jcardkit_home}/lib/apduio.jar"/> <pathelement path="."/> </path> <target name="convert_library" description="build export file and CAP file for SampleLibrary"> <convert EXP="true" CAP="true" packagename="com.sun.javacard.samples.samplelibrary" packageaid="0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x4" Chapter 5 NetBeans Software Integration 37

48 CODE EXAMPLE 5-1 build.xml Modified for a NetBeans Project (Continued) majorminorversion="1.0" classdir="${classroot}" outputdirectory="${classroot}"> <exportpath refid="export"/> <classpath refid="classpath"/> </convert> </target> <target name="convert_purse" depends="convert_library" description="build cap file for the JavaPurse package"> <convert CAP="true" packagename="com.sun.javacard.samples.javapurse" packageaid="0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x2" majorminorversion="1.0" classdir="${classroot}" outputdirectory="${classroot}"> <AppletNameAID appletname="com.sun.javacard.samples.javapurse.javapurse" aid="0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x2:0x1"/> <exportpath refid="export"/> <classpath refid="classpath"/> </convert> </target> <target name="-post-compile" depends="convert_purse"> </target> </project> 38 Ant Tasks User s Guide, Java Card Platform, Version March 2006

49 CHAPTER 6 Ant Tasks Example CODE EXAMPLE 6-1 Following is a complete build.xml file that can be used to compile, convert, verify, and deploy the JavaPurse demo applet that comes with Java Card development kit in cref and then run a demo script. To use this example, copy and paste CODE EXAMPLE 6-1 in build.xml file. Place the build.xml file in <Java Card Dev Kit Directory>/samples/src directory. Create a subdirectory in src directory named scripts and place testpurse.scr (CODE EXAMPLE 6-2) in that directory. At this point you should be able to run Ant in the src directory to run the example. build.xml <?xml version="1.0"?> <project name="java Card(TM) Tasks Sample" default="all" basedir="."> <!-- the directory structure under the base directory --> <property name="sourceroot" value="." /> <property name="classroot" value="classes" /> <property name="samples.eeprom" value="eeprom" /> <property name="samples.scripts" value="scripts" /> <property name="exportmap" value="exportmap" /> <!-- the directories where the Java Card(TM) export are located could go --> <!-- into a properties file--> <property name="jcardkit_home" value="../.." /> <property name="jcardkit_exports" value="${jcardkit_home}/api_export_files" /> <property name="jcardkit_libs" value="${jcardkit_home}/lib" /> <!-- 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" /> 39