Building JavaCard applet CAP files with Ant

Easy to use Apache Ant task for building JavaCard CAP files in a declarative way.

Have a consistent and concise build declaration for JavaCard applets, no matter which JavaCard SDK version you use or target.

       

Features

• Do What I Mean. You will love it!
• No dependencies, no extra or unrelated downloads. Just a ~50KB reproducible jar file.
• Supports all available JavaCard SDK versions: 2.1.2, 2.2.1, 2.2.2, 3.0.3, 3.0.4, 3.0.5, 3.1.0 and 3.2.0
  • Get one from oracle.com or use the handy Github repository
• Works on all platforms with LTS Java 1.8+: Windows, OSX, Linux.
  • Usable SDK-s depend on JDK version
• Almost everything integrates or works with Ant.
  • Trigger it from Maven or via Gradle wrapper
• Can be easily integrated into continuous integration workflows.
• Generates CAP files from sources or pre-compiled class files.
• Import external libraries: natural use of .jar libraries and/or .exp files.
• No restrictions on project folder layout (but src/main/javacard works).

Tip

Loading JavaCard applets is equally pleasing with GlobalPlatformPro

Download & Use

• Download ant-javacard.jar
• Or use the download task:

<get src="https://github.com/martinpaljak/ant-javacard/releases/latest/download/ant-javacard.jar" dest="." skipexisting="true"/>

• Then load the task with the following in your build.xml file:

<taskdef name="javacard" classname="pro.javacard.ant.JavaCard" classpath="ant-javacard.jar"/>

• Now you can create applets within your Ant targets like this:

<javacard>
  <cap jckit="/path/to/jckit_dir" aid="0102030405">
    <applet class="myapplet.MyApplet" aid="0102030405060708"/>
  </cap>
</javacard>

(which results in output similar to this)

target:
      [cap] INFO: using JavaCard 3.0.5 SDK in sdks/jc305u4_kit
      [cap] INFO: targeting JavaCard 2.2.2 SDK in sdks/jc222_kit
      [cap] Setting package name to testapplets.empty
      [cap] INFO: generated applet AID: A000000617008E5CDAAE01 for testapplets.empty.Empty
      [cap] Building CAP with 1 applet from package testapplets.empty (AID: A000000617008E5CDAAE)
      [cap] testapplets.empty.Empty A000000617008E5CDAAE01
  [compile] Compiling files from /Users/martin/projects/ant-javacard/src/testapplets/empty
  [compile] Compiling 1 source file to /var/folders/gf/_m9mq9td3lz32qv1hd4r12yw0000gn/T/jccpro841338375581620546
      [cap] CAP saved to /Users/martin/projects/ant-javacard/Empty_A000000617008E5CDAAE_50da91a4_2.2.2.cap

Recommended setup

Based on the JavaCard SDK and JDK version compatibility matrix.

• Targeting JC 3.0.4 or later (modern JavaCard-s)
  • Use JDK 17 (don't forget to set $JAVA_HOME)
  • Use JavaCard SDK 3.2.0 (jckit="sdks/jc320v24.0_kit") with right target (targetsdk="3.x.y")
  • NOTE: depending on your external components, absence of v2.3 export files will force you to stick with JavaCard SDK 3.1
• Targeting JC 2.2.x or 3.0.1 (older JavaCard-s)
  • Use JDK 11 (don't forget to set $JAVA_HOME)
  • Use JavaCard SDK 3.0.5u4 (jckit="sdks/jc305u4_kit") with right target (targetsdk="sdks/jc222_kit")

Note

ant-javacard will continue to support using legacy JavaCard 2.X SDK-s (and thus JDK-8) for as long as this is achievable with sane effort

Syntax

Sample:

<javacard jckit="/path/to/jckit_dir1">
  <cap targetsdk="/path/to/jckit_dir2" aid="0102030405" package="package.name" version="0.1" output="MyApplet.cap" sources="src/myapplet" classes="path/to/classes" export="mylib">
    <applet class="myapplet.MyApplet" aid="0102030405060708"/>
    <import exps="path/to/exps" jar="/path/to/lib.jar"/>
  </cap>
</javacard>

Details:

• javacard tag - generic task
  • jckit attribute - path to the JavaCard SDK that is used if individual cap does not specify one. Optional if cap defines one, required otherwise.
• cap tag - construct a CAP file
  • jckit attribute - path to the JavaCard SDK to be used. Optional if javacard defines one, required otherwise.
  • targetsdk attribute - path to the target JavaCard SDK (or "3.0.X" target version when using JavaCard SDK v3.1), to be used for this CAP. Optional, value of jckit used by default. Allows to use a more recent converter to target older JavaCard platforms.
  • sources attribute - path(s) to Java source code, to be compiled against the JavaCard SDK. Either sources or classes is required, unless src/main/javacard or src/main/java exists.
  • sources2 attribute - additional sources to build per-platform applets. Optional, deprecated (use multiple paths for sources)
  • classes attribute - path to pre-compiled class files to be assembled into a CAP file. If both classes and sources are specified, compiled class files will be put to classes folder, which is created if missing.
  • includes attribute - comma or space separated list of patterns of files that must be included (like **/SomeFile.java).
  • excludes attribute - comma or space separated list of patterns of files that must be excluded.
  • package attribute - name of the package of the CAP file. Optional for applets - set to the parent package of the applet class if left unspecified, required for libraries
  • version attribute - version of the package. Optional - defaults to 0.0 if left unspecified.
  • aid attribute - AID (hex) of the package. Recommended - or set to the 5 first bytes of the applet AID if left unspecified.
  • output attribute - path where to save the generated CAP file. Optional, see below for variables.
  • export attribtue - path (folder) where to place the JAR and generated EXP file. Optional.
  • exportmap attribtue - if set to true, use pre-defined export file. Optional.
  • jar attribute - path where to save the generated archive JAR file. Optional.
  • jca attribute - path where to save the generated JavaCard Assembly (JCA) file. Optional.
  • verify attribute - if set to false, disables verification of the resulting CAP file with offcardeverifier. Optional.
  • debug attribute - if set to true, generates debug CAP components. Optional.
  • strip attribute - if set to true, removes class files from target CAP. Optional.
  • ints attribute - if set to true, enables support for 32 bit int type. Optional.
• applet tag - for creating an applet inside the CAP
  • class attribute - class of the Applet where install() method is defined. Required.
  • aid attribute - AID (hex) of the applet. Recommended - or set to package aid+i where i is index of the applet definition in the build.xml instruction
• import tag - for linking against external components/libraries, like GPSystem or OPSystem
  • exps attribute - path to the folder keeping .exp files. Optional. Required if file in jar does not include .exp files.
  • jar attribute - path to the JAR file for compilation. Required if using sources mode and not necessary with classes mode if java code is already compiled

Notes:

• jc.home property has the highest precedence, followed by jckit path of cap, followed by path in javacard, followed by JC_HOME environment variable. SDK must be valid to be considered for use.
• All source files are expected to be UTF-8. It is a sane choice, please use it.

Output file name variables

The default file name template is %n_%a_%h_%j_%J.cap which results in a file name similar to SomeApplet_010203040506_9a037e30_2.2.2_jdk11.cap.

Following substitutions are available:

• %h - 8 character prefix (hex) of the SHA-256 Load File Data Block hash of the CAP file
• %H - SHA-256 Load File Data Block hash (hex) of the CAP file
• %n - common name of the entity, either applet class (if only one applet) or package name
• %p - package name
• %a - package AID (hex)
• %j - targeted JavaCard version (ex: 3.0.5)
• %J - used JDK version (ex: jdk11)

Command line utility

ant-javacard.jar can be used to dump built .cap file metadata and to re-run off-card verifier.

• dump .cap file metadata
  • java -jar ant-javacard.jar <capfile>
• run off-card verifier
  • java -jar ant-javacard.jar <sdk> [<targetsdk>] <capfile> <expfiles>

Environment variables

• JAVA_HOME - path to the JDK to be used.
• JC_HOME - path to the JavaCard SDK to be used if not specified in the build file.
• ANT_JAVACARD_TMP - path to the temporary folder to be used for building CAP files. This is not cleaned after use.
• ANT_JAVACARD_DEBUG - if set, shows debug output.

Maven dependency

Releases are published to https://mvn.javacard.pro/maven/. To use it, add this to your pom.xml:

<repositories>
    <repository>
        <id>javacard-pro</id>
        <url>https://mvn.javacard.pro/maven/</url>
    </repository>
</repositories>

Pushes to Maven Central happen manually and only for selected final versions.

License

• MIT

Happy users

A random list of users, with a public link:

• Applets:
  • IsoApplet by @philipWendland
  • NdefApplet by @promovicz
  • GidsApplet by @vletoux
  • LedgerWalletApplet by @LedgerHQ
  • KeePassNFC by @nfd
  • PivApplet (PIV) by @arekinath
  • OpenFIP201 (PIV) by @makinako
  • Cryptonit (PIV) by @mbrossard
  • HTOP NDEF by @petrs
  • Yubikey OTP by @arekinath
  • SmartPGP by @ANSSI-FR
  • SatochipApplet (Bitcoin Hardware Wallet) by @Toporin
  • SIMple-ID by @alan-turing-institute
  • HelloSTK2 (SIM toolkit sample app) by @mrlnc
  • NeoPGP by @mwalle
  • EUCLEAK by NinjaLab
  • Plus loads of academic projects, classes and papers.
• Integration projects:
  • JavaCard Gradle plugin by @bertrandmartel
  • JavaCard Template project with Gradle by @ph4r05
  • ant-javacard in Docker by @xoryouyou
• Other:
  • You! Don't torture yourself with complexity, KISS!

Contact

• See javacard.pro
• GlobalPlatform/JavaCard discussions

Similar projects

• standard JavaCard SDK Ant tasks
  • :( as cumbersome to use as the command line utilities
  • :( not declarative/DWIM enough
  • :) very explicit interface with all details exposed
• JavaCard Gradle plugin (MIT) - https://github.com/bertrandmartel/javacard-gradle-plugin
  • :) Wraps ant-javacard for use with Gradle
• gradle-javacard (Apache 2.0) - https://github.com/fidesmo/gradle-javacard
  • :) nice declarative interface
  • :( requires gradle (40M download)
  • :( JavaCard 2.2.2 only
• EclipseJCDE (Eclipse 1.0) - http://eclipse-jcde.sourceforge.net/
  • :( JavaCard 2.2.2 only
  • :( not possible to integrate in CI - depends on eclipse
  • :( essentially an Eclipse GUI wrapper for JC SDK
• JCOP Tools
  • :( not open source
• NetBeans IDE JC support
  • :( not possible to integrate into CI
  • :( JavaCard 3.0 only
  • :( Netbeans, not cross platform
• Maven2 task from FedICT (LGPL3) - https://code.google.com/p/eid-quick-key-toolset
  • :( Maven downloads half the internet before even simple tasks
  • :( JavaCard 2.2.2 only
• Ant script files with templates
  • :( XML is a very bad and verbose programming environment