Java Card tutorial


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 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

  • Our handy command line client, fdsm. You can grab the latest version here.
  • Our “Hello Fidesmo!” Java Card example, available as a GitHub repository. It builds using ant with ant-javacard and fidesmoappid attributes in build.xml. It already includes the Oracle JavaCard SDKs as a submodule, so use git clone --recursive when cloning it.
  • A Fidesmo Card.
  • A contactless reader, for the last part of this tutorial. If you haven't one around, once you have built your cardlet you can skip to the next tutorial and install it using an Android phone with our Fidesmo App.

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:


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.


Fidesmo Developer Account

If you haven’t done so yet, you need to define an application here. Note down the credentials assigned to it, and write your App Id on the build.xml file under the fidesmoappid attribute. You will later need both the App Id and App Key to install and test your cardlet.


FDSM is the developer's Swiss Army Knife for working with a Fidesmo device and the Fidesmo API. All from the command line.

Once you have a copy of fdsm.jar (or fdsm.exe for Windows), you can start it by running

java -jar fdsm.jar -h

or fdsm.exe -h on Windows. With Linux or macOS, it is recommended to add a handy alias to your ~/.bashrc or ~/.profile (assuming ~/Downloads is where you saved fdsm.jar):

alias fdsm="java -jar ~/Downloads/fdsm.jar"

It is also useful to set your Fidesmo App Id and App Key as the environment variables FIDESMO_APP_ID and FIDESMO_APP_KEY:

cmd> export FIDESMO_APP_ID=<your_app_id> cmd> export FIDESMO_APP_KEY=<your_app_key>

Off we go!

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

  • Be sure to set your own App Id on the build.xml file. Then, to build the cardlet and create the file installable (in a format called CAP, or “converted applet”) just run ant:
  • cmd> ant
  • If you have a contactless card reader plugged to your computer, you can then install the cardlet onto a Fidesmo Card using FDSM. Be sure to replace the placeholders with the values corresponding to your application (you can skip -app-id and -app-key if you set them before as environment variables):
  • cmd> fdsm -upload -install <applet.cap> -app-id <your_app_id> -app-key <your_app_key>
  • To remove the cardlet from the Fidesmo Card (you can skip -app-id and -app-key if you set them before as environment variables):
  • cmd> fdsm -uninstall <applet.cap> -app-id <your_app_id> -app-key <your_app_key>
  • You can also use FDSM to check the cardlets intalled on your Fidesmo Card:
  • cmd> fdsm -card-apps

Testing the cardlet

It is good that the command fdsm -install 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 A00000061700C8739B1901.

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, then compile and run the .java file as any typical Java application.

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:


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

cmd> javac 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!