Java Card tutorial

Introduction

In this tutorial you will learn how to create a Java Card application and install it in a Fidesmo Card locally connected to the development computer. The application is extremely simple: it always responds “Hello Fidesmo!” to all commands addressed to that application by the reader. This tutorial focuses instead on the development and installation process, which we have simplified with some handy development tools. The toolchain, plus some important aspects of Java Card development, is described here.

We have published the application's source code in GitHub. Feel free to download and modify it as a way to learn how to build a Java Card application using the Fidesmo platform.

What you need for this tutorial

  • The Java Card development kit, version 2.2.2, available here
  • Our “Hello Fidesmo!” Java Card example, available as a GitHub repository. Feel free to use it as a template for your own projects.
  • A Fidesmo Card
  • A contactless reader, for the last part of this tutorial. If you haven’t one around, jump directly to this tutorial [coming soon!] that shows how to install the application using an Android phone.

We have built our tools as Gradle plugins. Gradle will be installed automatically when running this tutorial.

Code walkthrough

In this section, we’ll see how the example application is implemented. Oracle has quite comprehensive documentation (this guide for example), so we will keep it short.

The beginning

All Java Card applications (called “cardlets” for some reason) must extend the abstract javacard.framework.Applet class:

Installation

When the cardlet is installed onto a smart card, the install() method is executed. That’s where we will write all the initialization code (not much in our example), dealing with installation parameters.

Processing requests

We need to implement the process() method, called by the Java Card runtime whenever a command is received that addresses our cardlet. Normal cardlets would branch depending on the command’s header, but since this is a cheerful little cardlet, it will just send back a response with the string “Hello Fidesmo!” encoded in ASCII.

If you are not familiar with the commands exchanged between readers and cards, called APDUs, you can read a brief introduction in the Java Card documentation. Wikipedia has a brief but useful description.

Building and installing the cardlet

Once your code is ready, it is time to build the cardlet and install it onto your Fidesmo Card.

Preparations

Java Card JDK

  • Download the JavaCard Development Kit in Version 2.2.2 from Oracle
  • Unzip the Javacard Development Kit and also the zipfiles it contains
  • Set the environment variable JC_HOME to the folder containg the JDK (usually named java_card_kit-2_2_2)

Gradle properties

If you haven’t done so yet, you need to define an application here. Note down the credentials assigned to it, because you need to write them in the gradle.properties file. If the file does not exist, create it inside a directory called .gradle, in your home directory, and write your application's credentials as properties:

cmd> echo 'fidesmoAppId: yourAppID' >> $HOME/.gradle/gradle.properties cmd> echo 'fidesmoAppKey: yourAppKey' >> $HOME/.gradle/gradle.properties

Off we go!

This used to take a lot of sweat and tears. Now, building and installing your cardlet is just one command away:

  • To build the cardlet and create the file installable on the card (in a format called CAP, or “converted applet”):
  • cmd> ./gradlew build
  • If you have a contactless card reader plugged to your computer, to build the cardlet and install it onto a Fidesmo Card:
  • cmd> ./gradlew installToLocalCard
  • To remove the cardlet from the Fidesmo Card:
  • cmd> ./gradlew deleteFromLocalCard

Testing the cardlet

It is good that the command ./gradlew installToLocalCard finished successfully, but how can we be sure that there is a cardlet actually installed on the card that will answer “Hello Fidesmo!” to all APDUs?

We expect to find a new cardlet on the Fidesmo Card whose Application ID has been assigned automatically by Fidesmo, based on your AppID. For example, if your AppID = C8739B19, the resulting AID assigned to the cardlet is A00000061700C8739B190101.

We can test it with an Android app, following this tutorial.
We can also use a very simple Java program to test it, derived from the example posted on Ludovic Rousseau’s blog. We have found it very useful when testing card readers’ drivers in different operating systems.

The modified version, unimaginatively named HelloFidesmoTest, is available here. Download and unzip it.

HelloFidesmoTest first checks for connected card terminals (readers) and uses the last one to connect to the card: in dual interface readers, the contact one is usually assigned the lowest position in the list, while the contactless one gets the highest index. In case it is not the case in your setup, it first prints the list of terminals. Then it sends a SELECT command to our cardlet's AID, which is generated from the AppId assigned to you by Fidesmo, so we are setting it using an environment variable. Finally, it outputs the response's ASCII characters.

Let's run it. First, set the environment variable with your AppId:

cmd> export HELLO_FIDESMO_APPID="XXXXXXXX"

After making sure that your Fidesmo Card is on the reader, compile and run the little test program:

cmd> javac HelloFidesmoTest.java cmd> java HelloFidesmoTest Terminals: [PC/SC terminal OMNIKEY CardMan (076B:5321) 5321 (OKCM0070212111919358692715895273) 00 00, PC/SC terminal OMNIKEY CardMan (076B:5321) 5321 (OKCM0070212111919358692715895273) 00 01] Answer to SELECT APDU: ResponseAPDU: 16 bytes, SW=9000 Hello Fidesmo!

Publishing the cardlet

That is the topic of the next tutorial!