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
build.xml. It already includes the Oracle JavaCard SDKs as a submodule, so use
git clone --recursive https://github.com/fidesmo/javacard-tutorial-codewhen 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.
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.
All Java Card applications (called “cardlets” for some reason) must extend the abstract
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.
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.
Once you have a copy of
fdsm.exe for Windows), you can start it by running
java -jar fdsm.jar -h
fdsm.exe -h on Windows. With Linux or macOS, it is recommended to add a handy alias to your
~/Downloads is where you saved
alias fdsm="java -jar ~/Downloads/fdsm.jar"
It is also useful to set your Fidesmo App Id and App Key as the environment variables
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.xmlfile. Then, to build the cardlet and create the file installable (in a format called CAP, or “converted applet”) just run ant:
-app-keyif you set them before as environment variables):
cmd> fdsm -upload -install <applet.cap> -app-id <your_app_id> -app-key <your_app_key>
-app-keyif you set them before as environment variables):
cmd> fdsm -uninstall <applet.cap> -app-id <your_app_id> -app-key <your_app_key>
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:
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!