Hardware Security

[ main | schedule | cases | smartcard practicalities | project work | side-channel lab ]

Below you find some information and pointers about the smartcards we will use. This should help you get started writing your first smartcard applets and terminal applications.

Another source of info is Eric Vetillard's blog, which also contains a Java Card tutorial.

(Java Card) smart cards

Smart cards communicate with the outside world by receiving commands and answering them. The protocol is described in the ISO7816-4 standard.

Java Card is a "dialect" of Java for programming such smart cards. A brief introduction to Java Card is available at JavaWorld. Lots more information is available from Oracle's Java Card site. In particular, you can download the Java Card Development Kit there. The kit includes the Java Card API which contains classes you can use in your applet. Applets are compiled using a normal Java compiler and transformed to CAP files using a converter included in the kit. The protocol to download CAP files onto a smartcard is described in the Global Platform standard.

We will be using JCOP smartcards, the Java Card platform originally developed by IBM but since taken over NXP. The JCOP4.1 cards we use support Java Card 2.2.1 and Global Platform 2.1.1 (or higher). To get an idea of the specs, these cards contain something like an SmartMX2-P40 or A710xC with JCOP2.4.2.

Tools for working with the Java Card smart cards

JCOP toolset
Applets can be loaded onto the card using the JCOP toolset software that comes with the cards as an Eclipse plug-in. A virtual machine for VirtualBox will be provided with Eclipse and the JCOP toolset pre-installed (the password for the default user is 'development'). We e-mail you a link with a copy of the toolset. You should save this zip file to your disk, and then open it in Eclipse as a "New Archived Site", by selecting
  Help -> Software Updates -> Find and Install -> Search for new features -> New Archived Site
in Eclipse.
Open-source alternative
On Linux or iOS there is also the option of using GlobalPlatformPro for managing the card. In this case, you will need the javacard dev kit 2.2.1 available from here to compile the .cap file. We are not sure if and how this will work on a Windows machine. See below the sections concerning the compilation of two Java applets (TestApplet and CardApplet) from a Makefile (courtesy of Moritz Neikes). On Linux install pcscd, OS X should have this by default.
applet: ${APPLETFILES} CardApplet/jc-bin/applet/javacard/applet.cap

CardApplet/jc-bin/applet/javacard/applet.cap: ${APPLETFILES}
	# Convert to .cap...
	@${CONVERTER} -v -out CAP -exportpath ${JC_HOME}/api_export_files -classdir CardApplet/jc-bin -d CardApplet/jc-bin \
	-applet ${TestAppletAID} applet.TestApplet \
	-applet ${CardAppletAID} applet.CardApplet \
	applet ${PID} 1.0
	# Installing applet...
	@${GP} --reinstall CardApplet/jc-bin/applet/javacard/applet.cap
	# Creating applet instances...
	@echo Card applet AID: ${CardAppletAIDplain}
	@${GP} --applet ${TestAppletAIDplain} --package ${PIDplain} --create ${TestAppletAIDplain}31
	@${GP} --applet ${CardAppletAIDplain} --package ${PIDplain} --create ${CardAppletAIDplain}31
	# DONE

CardApplet/jc-bin/%.class: CardApplet/src/%.java
	@mkdir -p CardApplet/jc-bin
	# compiling $^
	@javac -source 1.3 -target 1.1 -d CardApplet/jc-bin -cp Terminal/lib/jcardsim-2.2.2-all.jar:\
	Terminal/lib/gp.jar:\
	Terminal/src:\
	CardApplet/src $^

Using the following definitions:
JUNIT_HOME=Common/lib
JC_HOME=Common/lib/java_card_kit-2_2_1

JC_PATH=${JC_HOME}/lib/apdutool.jar:${JC_HOME}/lib/apduio.jar:${JC_HOME}/lib/converter.jar:${JC_HOME}/lib/jcwde.jar:${JC_HOME}/lib/scriptgen.jar:${JC_HOME}/lib/offcardverifier.jar:${JC_HOME}/lib/api.jar:${JC_HOME}/lib/installer.jar:${JC_HOME}/lib/capdump.jar:${JC_HOME}/samples/classes:${CLASSPATH}

GP=java -jar Terminal/lib/gp.jar
CONVERTER=java -Djc.home=${JC_HOME} -classpath ${JC_PATH}:CardApplet/bin com.sun.javacard.converter.Converter

CLASSFILES_TERM := $(shell find Terminal/src/* -type f -regex .*java | sed 's/src/bin/g' | sed 's/java/class/g')
CLASSFILES_APPL := $(shell find CardApplet/src/* -type f -regex .*java | sed 's/src/bin/g' | sed 's/java/class/g')
APPLETFILES := $(shell find CardApplet/src/* -type f -regex .*java | sed 's/src/jc-bin/g' | sed 's/java/class/g')

# Fill this with your own AIDs
PID=0x48:0x57:0x53:0x45:0x43
TestAppletAID=${PID}:0x2D:0x54:0x45:0x53:0x54
CardAppletAID=${PID}:0x2D:0x43:0x41:0x52:0x44

PIDplain=$(shell echo ${PID} | sed 's/://g' | sed 's/0x//g')
TestAppletAIDplain=$(shell echo ${TestAppletAID} | sed 's/://g' | sed 's/0x//g')
CardAppletAIDplain=$(shell echo ${CardAppletAID} | sed 's/://g' | sed 's/0x//g')

Ant project template
If you like Ant: one of the 2017 groups found this IntelliJ IDEA JavaCard project template very useful.

Terminal

The terminal or host application can be written in Java. Obviously, you will need to install a recent version of the Java SDK.

For easy communication with the Java Card applets on the card you should use the Smart Card I/O API.

Since the host application will need to do some cryptographic computations, you also need to install a cryptographic provider compatible with Sun's JCE. (Although the standard Java library does provide an API for cryptography, the underlying engine lacks some of the important cryptographic primitives due to export restrictions.) The Bouncy Castle provider is recommended.

We have several types of smartcard readers available for use in this course:

The virtual machine will automatically connect to the OmniKey 3121 readers. For more information and driver links check the bottom of this page.

API Documentation and Jars

Jar files should be copied to the jre\lib\ext folder of the Java 2 SDK in use. The dll files should be copied to \Windows or \Windows\System32.

API

Web site

Side

Javadocs

Java Card

http://www.oracle.com/technetwork/java/javacard/

card

API

Java

http://www.oracle.com/technetwork/java

terminal

API

Bouncy Castle

http://www.bouncycastle.org/

terminal

API

Smart Card IO

terminal

Smart Card IO API

Installing applets on a smart card

To install an applet on the smart card you first have to create a run configuration in Eclipse: Cards named "Antonio" require additional steps to install an applet:

Tips

Example applications

Some example smartcard applications (applets and terminals) are available below.

Chipknip terminal

A simple terminal to get the current balance of your Chipknip card. (Chipknip is the Dutch national E-Purse.) Have a look at the Java file: ChipknipTerminal.java. This example demonstrates that your setup (reader and middleware APIs) is ok. It's safe to use your real chipknip with this application.

Calculator applet and terminal

This simple applet implements a calculator which operates on signed shorts. Overflow is silent. The terminal sends a command for every key on the keypad a user presses, the applet responds by sending the number to put on the display (i.e. the terminal has no state at all). Have a look at the source files in CalcApplet.zip and CalcTerminalSmartCardIO.zip. This example demonstrates Java Card and Smart Card I/O programming.

RSA crypto example

This simple example shows how to do RSA keypair generation, encryption and decryption in Java. Have a look at the source files in: RSAKeyGen.java, RSAEncrypt.java and RSADecrypt.java.

RSA crypto applet and terminal

The applet encrypts or decrypts blocks of data (length at most 128 bytes) using RSA keys which are generated off-card and uploaded to the card. RSA keys have to be sent to the card first and then the card needs to be "issued" before any encryption and decryption is done. The files with private and public keys that the host application requires/asks for can be generated with RSAKeyGen.java above. Have a look at the source files in CryptoApplet.java and CryptoTerminalSmartCardIO.java.

More Java Card code samples are at the end of this document.

Some additional (but mostly outdated) info is collected on the old version of this webpage.