This is an old revision of the document!


JavaCard applet development with NetBeans IDE

© 2010-2011 by LaBAK FI MUNI (contact us at http://www.fi.muni.cz/research/laboratories/labak/)

Download script templates for common smart cards.

Download example project with standard Sun Java Card Hello World example with all configurations applied.

Download fully prepared Ubuntu VirtualBox image with preconfigured toolchain (1.3GB). Preconfigured JOpenPGPCard applet (PGP/GPG), CardEdge applet (PKCS#11, PKCS#15, ISO/IEC 7816-15) and CesTa framework also included.

{{:public:JavaCard_tutorial_2011.pdf | Download slides with JavaCard tutorial.]] To be used with Ubuntu VirtualBox image. ===== Installation process ===== Following software will be used * NetBeans 6.8 or later (http://netbeans.org/) * Java Standard Edition Development Kit (JDK) 1.3 or later (http://www.oracle.com/technetwork/java/javase/downloads/) * Apache Ant 1.7 or later (http://ant.apache.org/bindownload.cgi, already included in NetBeans) * GPShell 1.4.2 or later (http://sourceforge.net/projects/globalplatform/files/) * Java Card Development Kit 2.1.2 (http://www.oracle.com/technetwork/java/javacard/downloads/index-jsp-138488.html#devkit). NOTE: most of the current cards doesn't support JavaCard 2.2.2 therefore you cannot use JCDK 2.2.2. * Java Card Ant Tasks (binary and docs can be found in Java Card Development Kit 2.2.2, subdirectory "ant-tasks"). Note: Java card Ant Tasks are not included in JCDK 2.1.2, therefore you have to copy them from JCDK 2.2.2 - but converter must be from JCDK 2.1.2 (unless your card supports JC 2.2.2.) - Install NetBeans - Install Java Standard Edition Development Kit (JDK) - Install Java Card 2.1.2 (just unpack) - Install GPShell (just unpack) - Create new Java project in NetBeans (File->New Project->Java->Java application) - Create a "lib" directory in the project root folder and copy Java Card Ant Tasks "jctasks.jar" into this directory. - Set configuration parameters in "nbproject/project.properties" (file in your project directory) * jc.home - path to Java Card Development Kit * jc.export_files - path to Java Card export files (for verifier), usually ${jc.home}\\api_export_files * gpshell.home - path to GPShell * gpshell.cmd - path to GPShell executable * gpshell.templatepath - path to a GPShell script templates (used for automatic generation of GPShell scripts) * gpshell.script - name of the GPShell script template to use with the project (based on the smart card used in the project) * jctasks.path - path to jctasks.jar * jc.applet.AID - applet AID in specific format 0x00:0x01:0x02 ... * jc.applet.AID_GPShell- applet AID in format for GPShell 000102... * jc.applet.name - name of the applet * jc.package.AID - package AID in format 0x00:0x01:0x02 ... (must be different from applet AID) * jc.package.AID_GPShell - package AID in format 000102 ... (must be different from applet AID) * jc.package.name - package name * jc.package.path - package path (replace dots in package name with slashes) * jc.package.shortName - last part of the package name * jc.package.version - version of a package Example of configuration: <code> # Java Card Development Kit home directory jc.home=C:\\Program Files\\Java\\java_card_kit-2_1_2 # Path to Java Card export files jc.export_files=${jc.home}\\api21_export_files # GPShell home directory, ${basdir} is a path to a base directory of the project gpshell.home=${basedir}\\bin\\GPShell-1.4.3 # GPShell executable gpshell.cmd=${gpshell.home}\\GPShell.exe # Path to the template directory gpshell.templatepath = ${basedir}\\scriptTemplates # Name of the script template gpshell.script=helloInstallgemXpressoProR3_2E64.txt # Path to Java Card Ant Tasks jctasks.path=${basedir}\\lib\\jctasks.jar # Applet parameters jc.applet.AID=0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1:0x1 jc.applet.AID_GPShell=a00000006203010c0101 jc.applet.name=HelloWorld # Package parameters jc.package.AID=0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1 jc.package.AID_GPShell=a00000006203010c01 jc.package.name=com.sun.javacard.samples.HelloWorld jc.package.path=com/sun/javacard/samples/HelloWorld jc.package.shortName=HelloWorld jc.package.version=1.0 ... rest of project.properties file as automatically generated for new project </code> * Modify the 'build.xml' and add conversion, verification and testing targets according the example. (You can copy the example and just modify the project name and decription.) <code xml build.xml> <?xml version="1.0" encoding="UTF-8"?> <project name="SmartHelloWorld" default="default" basedir="." xmlns:j2seproject3="http://www.netbeans.org/ns/j2se-project/3"> <description>Builds, tests, and runs the project SmartHelloWorld.</description> <import file="nbproject/build-impl.xml"/> <target name="-post-init"> <!-- Java Card Ant Tasks definition --> <path id="jc-tasks" > <pathelement path="${jctasks.path}"/> </path> <taskdef name="convert" classname="com.sun.javacard.ant.tasks.ConverterTask" classpathref="jc-tasks" /> <taskdef name="verifycap" classname="com.sun.javacard.ant.tasks.VerifyCapTask" classpathref="jc-tasks" /> <!-- Java Card classpath --> <path id="jc-classpath" > <pathelement path="${jc.home}/lib/converter.jar"/> <pathelement path="${jc.home}/lib/offcardverifier.jar"/> <pathelement path="${jc.home}/lib/scriptgen.jar"/> <pathelement path="${jc.home}/lib/apdutool.jar"/> <pathelement path="${jc.home}/lib/apduio.jar"/> <pathelement path="."/> </path> </target> <!-- Target responsible for conversion and verification of the applet --> <target name="convert" depends="init"> <convert dir="${build.classes.dir}" nobanner="true" JCA="true" EXP="true" CAP="true" packagename="${jc.package.name}" packageaid="${jc.package.AID}" majorminorversion="${jc.package.version}"> <AppletNameAID appletname="${jc.package.name}.${jc.applet.name}" aid="${jc.applet.AID}"/> <exportpath> <pathelement path="${jc.export_files}"/> </exportpath> <classpath refid="jc-classpath"/> </convert> <verifycap Verbose="true" CapFile="${build.classes.dir}/${jc.package.path}/javacard/${jc.package.shortName}.cap"> <exportfiles file="${jc.export_files}/java/lang/javacard/lang.exp" /> <exportfiles file="${jc.export_files}/javacard/framework/javacard/framework.exp" /> <exportfiles file="${jc.export_files}/javacard/security/javacard/security.exp" /> <exportfiles file="${jc.export_files}/javacardx/crypto/javacard/crypto.exp" /> <exportfiles file="${build.classes.dir}/${jc.package.path}/javacard/${jc.package.shortName}.exp" /> <classpath refid="jc-classpath"/> </verifycap> </target> <!-- Overriding target, which runs conversion and verification instead of creating JAR file --> <target name="jar" depends="init,compile,convert"> </target> <!-- Target, which runs specific script via GPShell --> <target name="run-script" depends="init"> <!-- Generate and execute build script --> <copy file="${gpshell.templatepath}\\${gpshell.script}" todir="build//scripts" overwrite="true"> <filterchain> <expandproperties/> </filterchain> </copy> <exec executable="${gpshell.cmd}"> <arg value="build//scripts//${gpshell.script}"/> </exec> </target> <!-- Overriding target, which runs script during testing --> <target name="test" depends="jar,run-script"> </target> </project> </code> ===== Developing new Java Card applet ===== - If you are using newer JDK than 1.3, change source/binary format to 1.3 (convertor accepts only this version) * File->Project properties->Sources->Source/binary format - Write/Replace code with Java Card applet (e.g., HelloWorld.java from {{:public:smarthelloworld.zip|example project}}) * If you are using targets from provided build.xml, make sure you also specify your option file with applet name, AID, etc. (e.g., HelloWorld.opt from {{:public:smarthelloworld.zip|example project}}) - Add Java Card libraries * //Project_name//->Libraries->//R-Click//Add library->Create library * //javacard SDK folder///lib/api21.jar * in case of different Java Card SDKs, e.g. 2.2.1, add following libraries instead * //javacard SDK folder///lib/api.jar * //javacard SDK folder///lib/javacardframework.jar * add created Java Card library to project - Try to compile project (Project should compile without errors) ===== Converting and uploading applet to smart card ===== * Create 'scriptTemplates/scriptTemplateName.txt' script template file for GPShell suitable for your card. Example for JCOP 4.1 cards: <code> # Usable for: # NXP JCOP 4.1, 3.1 and 2.1 cards mode_211 enable_trace establish_context card_connect select -AID a000000003000000 open_sc -security 1 -keyind 0 -keyver 0 -mac_key 404142434445464748494a4b4c4d4e4f -enc_key 404142434445464748494a4b4c4d4e4f // Open secure channel delete -AID ${jc.applet.AID_GPShell} delete -AID ${jc.package.AID_GPShell} install -file ${build.classes.dir}/${jc.package.path}/javacard/${jc.package.shortName}.cap -nvDataLimit 2000 -instParam 00 -priv 2 select -AID ${jc.applet.AID_GPShell} card_disconnect release_context </code> * Try to rebuild your project (Run->Clean and build project). Project is compiled and converted, but not uploaded to smart card (use until java card applet compile and convert without error) * Following steps should occur with output visible in NetBeans output console: - Build of java card application, *.class file(s) are created - Conversion to Java Card format (convert task), *.cap files are created in //project_path\build\classes\...// directory * Try to test your project (Run->Test project). Use when applet is compiled and converted without error. * Following steps should occur with output visible in NetBeans output console: - Build of java card application, *.class file(s) are created - Conversion to Java Card format (convert task), *.cap files are created in //project_path\build\classes\...// directory - Upload to smart card (GPShell output) ===== Usage hints ===== * Both compilation and testing can be executed from NetBeans (Build or Test commands from menu) and are handled by Ant and configured in "build.xml". * When compilation is done (compiled files are in build/classes/), task "convert" is executed and performs conversion and verification. Converted file can be found in build\classes\com\sun\javacard\samples\HelloWorld\javacard. This action can be configured in task "convert" in build.xml. * Testing executes script "scripts/helloInstallGP211_JCOP41_cap.txt" in GPShell and tries to install HelloWorld on compatible Java Card. This action can be configured in task "run-script" in build.xml.