This is an old revision of the document!
© 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.
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)
Add Java Card libraries
Try to compile project (Project should compile without errors)
Converting and uploading applet to smart card
# 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