Easy to use Ant task for building JavaCard applets (2.1.1 to 3.2.0)
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.
.jar
libraries and/or .exp
files.src/main/javacard
works).ant-javacard.jar
<get src="https://github.com/martinpaljak/ant-javacard/releases/latest/download/ant-javacard.jar" dest="." skipexisting="true"/>
build.xml
file:<taskdef name="javacard" classname="pro.javacard.ant.JavaCard" classpath="ant-javacard.jar"/>
<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.4 SDK in sdks/jc304_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
[convert] [ INFO: ] Converter [v3.0.4]
[convert] [ INFO: ] Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
[convert]
[convert]
[convert] [ INFO: ] conversion completed with 0 errors and 0 warnings.
[javacard] NB! Please use JavaCard SDK 3.0.5u3 or later for verifying!
[cap] CAP saved to /Users/martin/projects/ant-javacard/Empty_A000000617008E5CDAAE_50da91a4_2.2.2.cap
$JAVA_HOME
)jckit="sdks/jc320v24.0_kit"
) with right target (targetsdk="3.x.y"
)$JAVA_HOME
)jckit="sdks/jc305u4_kit"
) with right target (targetsdk="sdks/jc222_kit"
)Note: ant-javacard will continue to support JavaCard 2 for as long as this is achievable with sane effort
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 librariesversion
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 instructionimport
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 compiledNotes:
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.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)ant-javacard.jar
can be used to dump built .cap file metadata and to re-run off-card verifier.
java -jar ant-javacard.jar <capfile>
java -jar ant-javacard.jar <sdk> [<targetsdk>] <capfile> <expfiles>
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.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.
A random list of users, with a public link: