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 ~96KB reproducible jar file.
• Supports all available JavaCard SDK versions: 2.1.1, 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 25 (don't forget to set $JAVA_HOME)
  • Use the latest JavaCard SDK (jckit="sdks/jc320v26.0_kit") with right target (targetsdk="3.x.y")
• Targeting JC 2.2.x or 3.0.1 (older JavaCard-s)
  • Use JDK 17 (don't forget to set $JAVA_HOME)
  • Use JavaCard SDK 3.0.5u4 (jckit="sdks/jc305u4_kit") with right target (targetsdk="sdks/jc222_kit")
• Targeting JC 2.1.x (archeology)
  • Use JDK 8 (don't forget to set $JAVA_HOME)
  • Use the matching legacy SDK (jckit="sdks/jc212_kit")
  • No off-card verification, it gets disabled automatically

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 for this CAP, or a version name with SDK v3.1.0 and later: "3.0.4", "3.0.5" and "3.1.0", plus "3.2.0" with v24.0 and later, and "preview" and "preview-final" with v26.0. 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, or a folder to save it into. Optional, see below for variables.
  • export attribute - path (folder) where to place the JAR and generated EXP file. Optional.
  • exportmap attribute - 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, the converter does not verify the resulting CAP file with the off-card verifier. 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 - JavaCard version required by the CAP imports (ex: 3.0.5)
• %J - used JDK version (ex: jdk11)
• %v - applet package version (same as version attribute for cap, ex: v1.0)

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.
• SOURCE_DATE_EPOCH - seconds since the Unix epoch, used instead of the current time in the CAP. Use with TZ=UTC.

Known issues

• The bytes that reach the card are identical on every JDK, but the .cap container is not: META-INF/MANIFEST.MF and the bundled class files vary with the JDK. See Reproducibility notes.

Maven dependency

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

<repositories>
    <repository>
        <id>javacard-pro</id>
        <url>https://mvn.javacard.pro/public/</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
  • OpenFIPS201 (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