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

===== JavaCard applet development with AppletPlayground/GlobalPlatformPro/JCardSim and JCAlgTest =====

  * 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): {{:public:research:smartcard:javacard_2016.pdf|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


----


===== (OUTDATED) JavaCard applet development with NetBeans IDE =====
(c) 2010-2011 by LaBAK FI MUNI (contact us at http://www.fi.muni.cz/research/laboratories/labak/)

{{scripttemplates.zip|Download script templates}} for common smart cards.

{{:public:smarthelloworld.zip|Download example project}} with standard Sun Java Card Hello World example with all configurations applied.

{{JavaCard_tutorial_2011.pdf | Download slides with JavaCard tutorial.}} To be used with Ubuntu VirtualBox image.

[[https://www.youtube.com/watch?v=khgT5dwKvOo | Oracle JavaCard tutorial (2013)]]

===== 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  (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:
<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. 

===== Troubleshooting ===== 

  * 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., d:\\Apps\\JavaCardSDK2.2.2)