This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== 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)