Skip to content

Installation of the IsoApplet

Jump to bottom
Philip Wendland edited this page Jul 31, 2016 · 1 revision

This page describes how to install the applet onto your Java Card smartcard. Most Java Card smartcards follow the GlobalPlatform card specification version 2.1.1 or 2.2 which (among other things) describes how to install applets onto compatible smartcards.

I recommend to compile the applet yourself before installing it. You should make use of the advantages of open-source software and take a look at the code, too. Private-key-related operations only take place in the IsoApplet.java class.

Difficulties

GlobalPlatform compliant cards have an "Issuer Security Domain (ISD)" applet that implements the card manager which is responsible for the management of applets. The ISD requires to establish a secure channel before performing such operations. The difficulty of installing applets onto your smartcard will not be the installtion itself, but finding required information to establish this channel. These information include:

  • Master keys: A key or keyset that is used to secure access to most operations of the ISD. If you have an "open" card, it most likely uses the default key: 404142434445464748494a4b4c4d4e4f.
  • Key derivation: Some smartcards use different key derivation functions (e.g. VISA2 or EMVCPS11) to derive keys from the single master key. It is advised to obtain some information of the algorithm used by your card.
  • The applet ID of the ISD: Applets have an AID (Applet Identifier) and usually need to be selected using that ID. Getting to know the AID of the ISD is usually not a problem. The default AID for the ISD is a000000003000000.

Attention:

Most smartcards will be locked (i.e. destroyed) after a certain amount of failed attempts to open a secure channel! Be sure that you know the maximum and current amount of failed attempts for your card before trying anything. Be sure that the examples provided below are the correct one for your card!

Examples provided below assume you have an J2A081 smartcard with JCOP v2.4.1 operating system and default keys.

Choosing a tool

There are different tools available to perform the installation of applets. I recommend using one of the following:

  • GPShell, probably the most widely known tool for installing applets onto GlobalPlatform compliant cards. This tool uses script files that describe the operations it should perform on the card. New users will probably need some time to understand how to write those files.
  • GlobalplatformPro, a more comprehensive tool (personal opinion) that is used on the command line and is written in Java.

The installation process

Using GPShell

GPShell uses script files to specify which operations to perform. The following script file will (most likely) install IsoApplet on your unlocked (JCOP) smartcard as default selected applet. Note that you have to place the IsoApplet.cap file in the exact same directory.

{% highlight text %} mode_211 establish_context card_connect select -AID a000000003000000 open_sc -security 1 -keyind 0 -keyver 0 -mac_key 404142434445464748494a4b4c4d4e4f -enc_key 404142434445464748494a4b4c4d4e4f install -file IsoApplet.cap -instParam 00 -priv 4 card_disconnect release_context {% endhighlight %}

Please note that earlier versions of the IsoApplet may have different file names. You have to substitute the name in the script file or rename the file if you are using such a version.

If you have other cards or if this does not work, the first place to visit would be the GPShell wiki.

If your card uses the newer "Secure channel protocol 03 (SCP03)", you should try to use the latest "trunk" version of GPShell. I submitted some patches a while ago that should make it work with -security 1.

Using GlobalplatformPro

GlobalplatformPro is used on the command line. The following call should install the applet onto your card if it uses default keys and no key derivation:

{% highlight text %} gp -install IsoApplet.cap -default {% endhighlight %}

I recommend having a look at the readme file for further information. Late versions of GlobalplatformPro support SCP03 as well.

Exchanging the default keys of the ISD

If you want to use your smartcard in a productive environment, you should exchange the default keys of the ISD. This can be done using GlobalplatformPro (gp -lock <key>) or GPShell (using the put_sc_key operation to replace the default key after opening a secure channel) as well.

If the installation was successful, you can start initializing the applet.

Clone this wiki locally