JavaCard applet development

<note tip>The description in section 'JavaCard applet development with NetBeans IDE' is outdated as we now have easier option.</note>

• Use AppletPlayground for compilation and conversion into JavaCard applet (by Martin Paljak): https://github.com/martinpaljak/AppletPlayground
• Use GlobalPlatformPro for upload of converted applets onto real cards (by Martin Paljak): https://github.com/martinpaljak/GlobalPlatformPro
• Read slides with JavaCard development tutorial (by Petr Svenda): javacard.pdf
• Use JCardSim simulator to develop even without real smart card: https://jcardsim.org
• Consult JCAlgTest project for properties (supported algorithms, performance) of real smart card if you plan to buy one: https://www.fi.muni.cz/~xsvenda/jcsupport.html

© 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 slides with JavaCard tutorial. To be used with Ubuntu VirtualBox image.

Oracle JavaCard tutorial (2013)

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.)

1. Install NetBeans
2. Install Java Standard Edition Development Kit (JDK)
3. Install Java Card 2.1.2 (just unpack)
4. Install GPShell (just unpack)
5. Create new Java project in NetBeans (File→New Project→Java→Java application)
6. Create a “lib” directory in the project root folder and copy Java Card Ant Tasks “jctasks.jar” into this directory.
7. 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 (NOTE: JC SDK 2.1.2 has this folder named api21_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:

# 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

• 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.)

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>

1. 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
2. Write/Replace code with Java Card applet (e.g., HelloWorld.java from 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 example project)
3. Add Java Card libraries
   • Project_name→Libraries→R-ClickAdd 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
4. Try to compile project (Project should compile without errors)

• Create 'scriptTemplates/scriptTemplateName.txt' script template file for GPShell suitable for your card. Example for JCOP 4.1 cards:

# 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

• 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:
  1. Build of java card application, *.class file(s) are created
  2. 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:
  1. Build of java card application, *.class file(s) are created
  2. Conversion to Java Card format (convert task), *.cap files are created in project_path\build\classes\… directory
  3. Upload to smart card (GPShell output)

• 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.

• Problem: Compilation fails with error: cannot find symbol XY (e.g., symbol: variable KeyAgreement)
  • Correct JavaCard SDK was not added to libraries.
  • If you get error for all JavaCard classes, then add library for your target card (e.g., 2.2.1)
  • if you get this error only for few classes (but not all), then you are using JC SDK without supprt for this classes (e.g., KeyAgreement, Checksum, MEMORY_TYPE_PERSISTENT… are not present in 2.1.2, but are present in 2.2.1)

• Problem: Convert fails with: Error: Could not find or load main class com.sun.javacard.converter.Converter
  • Compilation was successful, but Converter was not found. Check if your jc.home path is correctly set in nbproject\project.properties file. Note that you must use double \ in path (e.g., \\Apps\\JavaCardSDK2.2.2)