Introduction à la programmation de Javacard sous Windows

Les Javacard respectent le standard ISO7816 introduit en 1988. Ce dernier décrit (entre autres) l'interface de communication entre la carte et le terminal. Le lecteur fournit la tension d'alimentation et l'horloge de fréquence 3,5 MHz. L'échange de données est assuré par une liaison série half-duplex de débit compris entre 9600 et 115200 bauds.

Les échanges entre carte et terminal se font au moyen d'APDUs (suite d'octets respectant le format défini dans le standard ISO7816-4).

Nous utiliserons dans ce tutoriel l'APDU de requête suivante :

• CLA = octet de classe défini par l'ISO 7816 fournissant un certain nombre d'informations sur la commande (exemples : 0xBC pour les cartes vitales, 0x0A pour les cartes SIM, 0x00 pour les Mastercard/Visa)
• INS = octet d'instruction
• P1 = paramètre 1
• P2 = paramètre 2
• Lc = taille des données (0x00 si pas de données)
• Le = taille maximale des données pour la réponse

La carte répond en envoyant les données de réponse (s’il y a) suivies d'un status word codé sur 2 octets (nommés SW1 et SW2). Généralement, SW1 indique le type de réponse et SW2 fournit des informations supplémentaires.

Quelques exemples de status word :

Les applets sont identifiées par un AID (Applet ID) composé de 5 à 16 octets. Les 5 premiers correspondent à l'ID du fournisseur d'application (RID) et les suivants identifient l'application. Les RID sont fournis par l'ISO et il existe des RID réservés au développement.

Afin de pouvoir communiquer avec elle, une applet doit être préalablement sélectionnée à l'aide de l'APDU suivante via la commande SELECT (AID sur 16 octets dans cet exemple) :

Le framework Javacard 2.x est un sous-ensemble du langage Java. Il ne supporte que les éléments suivants :

• types primitifs boolean, byte et short ;
• les tableaux à une dimension ;
• les packages, classes, interfaces, exceptions ;
• l'héritage, les objets virtuels, la surcharge ;
• la création d'objets (new) mais uniquement dans son constructeur/sa méthode d'installation (donc pas de création d'objets en runtime).

Ainsi les types long, double, float, char, l'objet String et les tableaux à plusieurs dimensions ne sont pas autorisés.

• Java Card Development Kit 2.2.2 : archive java_card_kit-2_2_2-windows.zip (lien)
• Eclipse 3.2.2 : archive eclipse-SDK-3.2.2-win32.zip (lien)
• Eclipse-JCDE 0.1 : archive eclipse-jcde-0.1.zip (lien)

Tout d'abord, dézipper l'archive java_card_kit-2_2_2-windows.zip dans le dossier de votre choix (C:\JCDK dans ce tutoriel). Dézipper ensuite les 4 archives du dossier C:\JCDK\java_card_kit-2_2_2 dans ce même dossier. De cette manière vous devriez voir apparaître (entre autres) les dossiers suivants :

• C:\JCDK\java_card_kit-2_2_2\bin : contient les outils du JCDK (simulateur…) ;
• C:\JCDK\java_card_kit-2_2_2\lib : contient les librairies du JCDK ;
• C:\JCDK\java_card_kit-2_2_2\jc_specifications\specs\api\html : contient l'API du JCDK (très utile).

Afin de pouvoir utiliser les outils du JCDK en ligne de commande, il faut définir 2 variables d'environnement : JAVA_HOME contenant le chemin d'accès à Java et JC_HOME contenant le chemin d'accès au JCDK. Il peut alors être utile de créer un script batch permettant d'initialiser ces variables et actualiser la variable PATH. Pour ce tutoriel, nous créons le script setvars.bat suivant :

@echo off
set JAVA_HOME=c:\java
set JC_HOME=c:\JCDK\java_c~1
set PATH=%PATH%;%JC_HOME%\bin

Installer ensuite Eclipse : dézipper l'archive eclipse-SDK-3.2.2-win32.zip dans le dossier de votre choix (C:\Program Files\Eclipse dans ce tutoriel).

Installer le plugin EclipseJCDE : placer le contenu du dossier plugins de l'archive eclipse-jcde-0.1.zip dans le dossier plugins d'Eclipse (C:\Program Files\Eclipse\plugins dans ce tutoriel).

À ce stade, nous disposons d'un environnement de développement permettant de créer des Applet Javacard, de les simuler et créer des applications clientes.

Nous allons créer dans ce tutoriel une applet basique. Pour cela, lancer Eclipse, dans le menu File, faire New puis Other … :

Puis sélectionner Java Card Project :

Cliquer alors sur le bouton Next. Donner alors un nom au projet. Nous l'appellerons « Tutoriel Javacard » :

Cliquer alors sur le bouton Finish. Vous devriez alors voir le message d'erreur suivant :

Entrer alors le dossier où a été installé le Java Card Development Kit 2.2.2, puis cliquer sur le bouton OK :

À ce stade, nous venons de créer notre projet d'Applet Javacard. Nous allons maintenant créer notre Applet Javacard. Pour cela, aller dans le menu File, faire New puis Other … Sélectionner alors « Java Card Applet » puis cliquer sur le bouton Next :

Donner alors un nom au package ainsi qu'à l'applet. Nous les appellerons respectivement « monpackage » et « MonApplet » :

Cliquer alors sur le bouton Finish. Nous venons de générer le squelette de notre Applet :

Clic droit sur le package monpackage, Java Card Tools, Set Package AID :

Appuyer sur le bouton OK. Le Package AID doit obligatoirement être un préfixe de l'applet AID.

La méthode install est appelée lors de l'instanciation de l'applet dans la Javacard. Elle instancie notre classe MonApplet et l'enregistre. L'instanciation d'autres objets (instruction new) est autorisée uniquement dans cette méthode (ou dans le constructeur de la classe).

La méthode process est la méthode principale de l'Applet. Elle sera appelée à chaque fois que la carte recevra un APDU, passé en paramètre de la méthode.

Nous allons créer un compteur dans le cadre de ce tutoriel. L'applet comportera quatre fonctions :

• incrémenter le compteur ;
• décrémenter le compteur ;
• interroger le compteur ;
• initialiser le compteur à une valeur donnée.

Pour cela, nous allons définir des constantes et un attribut compteur de type primitif byte :

package monpackage;

import javacard.framework.APDU;
import javacard.framework.Applet;
import javacard.framework.ISO7816;
import javacard.framework.ISOException;

public class MonApplet extends Applet {
    /* Constantes */
    public static final byte CLA_MONAPPLET = (byte) 0xB0;
    
    public static final byte INS_INCREMENTER_COMPTEUR = 0x00;
    public static final byte INS_DECREMENTER_COMPTEUR = 0x01;
    public static final byte INS_INTERROGER_COMPTEUR = 0x02;
    public static final byte INS_INITIALISER_COMPTEUR = 0x03;
    
    /* Attributs */
    private byte compteur;
    
    /* Constructeur */
    private MonApplet() {
        compteur = 0;
    }

    public static void install(byte bArray[], short bOffset, byte bLength) throws ISOException {
        new MonApplet().register();
    }
}

Puis nous codons notre méthode process :

    public void process(APDU apdu) throws ISOException {
        byte[] buffer = apdu.getBuffer();
        
        if (this.selectingApplet()) return;
        
        if (buffer[ISO7816.OFFSET_CLA] != CLA_MONAPPLET) {
            ISOException.throwIt(ISO7816.SW_CLA_NOT_SUPPORTED);
        }

        switch (buffer[ISO7816.OFFSET_INS]) {
            case INS_INCREMENTER_COMPTEUR:
                compteur++;
                break;

            case INS_DECREMENTER_COMPTEUR:
                compteur--;
                break;
                
            case INS_INTERROGER_COMPTEUR:
                buffer[0] = compteur;
                apdu.setOutgoingAndSend((short) 0, (short) 1);
                break;
                
            case INS_INITIALISER_COMPTEUR:
                apdu.setIncomingAndReceive();
                compteur = buffer[ISO7816.OFFSET_CDATA];
                break;
                
            default:
                ISOException.throwIt(ISO7816.SW_INS_NOT_SUPPORTED);
        }
    }

Quelques explications :

• la méthode getBuffer() de la classe APDU permet de récupérer l'APDU sous forme d'un tableau d'octets ;
• la méthode selectingApplet() permet de préciser si l'APDU est en cours de sélection ;
• l'interface ISO7816 contient les constantes usuelles des APDU ;
• la méthode ISOException.throwIt permet de retourner le status word passé en paramètre ;
• se référer à l'API pour plus d'explications.

L'outil APDUTOOL du JCDK permet d'échanger des APDU avec une Javacard réelle ou un simulateur. Nous l'utiliserons dans la suite de ce tutoriel.

Le simulateur JCWDE ne nécessite pas de phase d'upload de code. Il nous suffit d'installer puis de sélectionner notre applet pour pouvoir la faire fonctionner. Dans le menu JCWDE d'Eclipse, sélectionner Start.

Cliquer sur le bouton OK pour lancer le simulateur JCWDE avec notre applet. Le simulateur est alors lancé et attend une connexion. Nous pouvons alors lancer l'outil APDUTOOL. Pour cela, ouvrir une invite de commandes, lancer le script setvars.bat (cf IV b), puis taper apdutool et valider :

Installons notre applet en recopiant les APDU contenus dans le script create-MonApplet.script (sauf la dernière instruction powerdown) :

Nous voyons que la carte répond « positivement » avec un status word 0x9000.

Nous pouvons alors sélectionner notre applet en recopiant l'APDU contenu dans select-MonApplet.script :

De nouveau, la carte répond « positivement » avec un status word 0x9000. Notre applet est désormais sélectionnée et nous pouvons la tester. Commençons par interroger le compteur (INS = 0x02) en envoyant l'APDU suivante :

Nous pouvons voir que le compteur est pour l'instant à 0. Nous allons l'incrémenter (INS = 0x00) :

Interrogeons de nouveau le compteur :

Il est désormais à 1. Initialisons maintenant (INS = 0x03) le compteur à 0x4A :

Décrémentons le compteur (INS = 0x01) et regardons le résultat :

0x4A - 1 = 0x49. Le résultat est cohérent. Nous allons nous déconnecter du simulateur en tapant « powerdown; » dans apdutool. Nous pouvons voir JCWDE se terminer :

JCWDE a l'avantage de ne pas nécessiter l'upload de l'applet sur le simulateur, ce qui le rend plus souple par rapport à CREF. En revanche dès que JCWDE est stoppé (à la réception d'une commande powerdown par exemple), l'état de la carte n'est pas conservé (exemple : la valeur du compteur dans le cas l'applet de ce tutoriel).

Les options de ligne de commande que nous allons utiliser :

• -i fichier_eeprom : initialise l'état de la carte avec l'image fichier_eeprom ;
• -o fichier_eeprom : enregistre l'état de la carte dans fichier_eeprom.

Nous pouvons lancer CREF et créer notre fichier image. Pour cela, ouvrir une invite de commandes, lancer le script setvars.bat (cf IV b), puis taper « cref -o monapplet.eeprom » et valider :

Uploadons maintenant notre applet. Pour cela, clic droit sur le package monpackage, Java Card Tools, Deploy :

Nous pouvons voir les APDUs envoyés dans la zone Console d'Eclipse :

Les status word 0x9000 indiquent que l'upload s'est déroulé correctement.

Relançons CREF afin d'installer notre applet, en prenant soin de recharger notre fichier image (option -i) :

Installons notre applet. Pour cela, clic droit sur le script create-MonApplet.script, Java Card Tools, Run Script :

À ce stade, nous pouvons utiliser apdutool pour tester notre carte, de la même manière qu'avec JCWDE, en prenant soin de ne pas oublier la commande powerup et la sélection de l'applet.

Créons un nouveau projet. Pour cela, dans Eclipse, aller dans le menu File, faire New puis Project … :

Puis confirmez en cliquant sur Next :

Donner un nom au nouveau projet puis cliquer sur Finish :

Afin de pouvoir utiliser les classes servant à communiquer avec notre Javacard, il faut ajouter la librairie apduio.jar (présente dans le dossier C:\JCDK\java_card_kit-2_2_2\lib). Pour cela, faire un clic droit sur notre nouveau projet puis Propriétés … :

Dans la section Java Build Path, sélectionner l'onglet Librairies et cliquer sur le bouton Add External Jars … :

Sélectionner alors le fichier apduio.jar, valider et appuyer sur le bouton OK.

Tout d'abord, créons un nouveau package. Pour cela, faire un clic droit sur notre projet, puis New et Package :

Donner un nom au package puis valider à l'aide du bouton Finish :

Créons maintenant la classe principale de notre application. Pour cela, faire un clic droit sur le package créé puis New et Class :

Donnons un nom à notre nouvelle classe, cocher la case public static void main puis cliquer sur Finish :

La connexion au simulateur se fait via une socket. Le simulateur écoute par défaut sur le port 9025. L'objet que nous utiliserons pour les échanges de données est CadT1Client.

        /* Connexion a la Javacard */
        CadT1Client cad;
        Socket sckCarte;
        try {
            sckCarte = new Socket("localhost", 9025);
            sckCarte.setTcpNoDelay(true);
            BufferedInputStream input = new BufferedInputStream(sckCarte.getInputStream());
            BufferedOutputStream output = new BufferedOutputStream(sckCarte.getOutputStream());
            cad = new CadT1Client(input, output);
        } catch (Exception e) {
            System.out.println("Erreur : impossible de se connecter a la Javacard");
            return;
        }

La déconnexion de la Javacard se fera via la méthode powerDown() de l'objet CadT1Client :

        /* Mise hors tension de la carte */
        try {
            cad.powerDown();
        } catch (Exception e) {
            System.out.println("Erreur lors de l'envoi de la commande Powerdown");
            return;
        }

La sélection d'applet se fait en envoyant l'APDU décrite dans le paragraphe c) :

        /* Sélection de l'applet */
        Apdu apdu = new Apdu();
        apdu.command[Apdu.CLA] = 0x00;
        apdu.command[Apdu.INS] = (byte) 0xA4;
        apdu.command[Apdu.P1] = 0x04;
        apdu.command[Apdu.P2] = 0x00;
        byte[] appletAID = { 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x00, 0x00 };
        apdu.setDataIn(appletAID);
        cad.exchangeApdu(apdu);
        if (apdu.getStatus() != 0x9000) {
            System.out.println("Erreur lors de la sélection de l'applet");
            System.exit(1);
        }

Voici le code de la boucle principale de l'application. Il suffit pour chaque opération d'initialiser correctement une instance de l'objet APDU et de l'envoyer à la carte via l'instance de l'objet CadT1Client.

Afin de mieux comprendre, il ne faut pas hésiter à taper ce code soi-même et refaire les manipulations de ce tutoriel : « c'est en faisant qu'on apprend ».

        /* Menu principal */
        boolean fin = false;
        while (!fin) {
            System.out.println();
            System.out.println("Application cliente Javacard");
            System.out.println("----------------------------");
            System.out.println();
            System.out.println("1 - Interroger le compteur");
            System.out.println("2 - Inrementer le compteur");
            System.out.println("3 - Decrementer le compteur");
            System.out.println("4 - Reinitialiser le compteur");
            System.out.println("5 - Quitter");
            System.out.println();
            System.out.println("Votre choix ?");
            
            int choix = System.in.read();
            while (!(choix >= '1' && choix <= '5')) {
                choix = System.in.read();
            }
            
            apdu = new Apdu();
            apdu.command[Apdu.CLA] = Maclasse.CLA_MONAPPLET;
            apdu.command[Apdu.P1] = 0x00;
            apdu.command[Apdu.P2] = 0x00;

            switch (choix) {
                case '1':
                    apdu.command[Apdu.INS] = Maclasse.INS_INTERROGER_COMPTEUR;
                    cad.exchangeApdu(apdu);
                    if (apdu.getStatus() != 0x9000) {
                        System.out.println("Erreur : status word different de 0x9000");
                    } else {
                        System.out.println("Valeur du compteur : " + apdu.dataOut[0]);
                    }
                    break;
                    
                case '2':
                    apdu.command[Apdu.INS] = Maclasse.INS_INCREMENTER_COMPTEUR;
                    cad.exchangeApdu(apdu);
                    if (apdu.getStatus() != 0x9000) {
                        System.out.println("Erreur : status word different de 0x9000");
                    } else {
                        System.out.println("OK");
                    }
                    break;
                    
                case '3':
                    apdu.command[Apdu.INS] = Maclasse.INS_DECREMENTER_COMPTEUR;
                    cad.exchangeApdu(apdu);
                    if (apdu.getStatus() != 0x9000) {
                        System.out.println("Erreur : status word different de 0x9000");
                    } else {
                        System.out.println("OK");
                    }
                    break;
                    
                case '4':
                    apdu.command[Apdu.INS] = Maclasse.INS_INITIALISER_COMPTEUR;
                    byte[] donnees = new byte[1];
                    donnees[0] = 0;
                    apdu.setDataIn(donnees);
                    cad.exchangeApdu(apdu);
                    if (apdu.getStatus() != 0x9000) {
                        System.out.println("Erreur : status word different de 0x9000");
                    } else {
                        System.out.println("OK");
                    }
                    break;
                    
                case '5':
                    fin = true;
                    break;
            }
        }

Afin de pouvoir lancer le simulateur de notre applet en ligne de commande, nous allons créer un fichier « de configuration ». Il permet de lister les applets Javacard à installer pour la simulation et de spécifier leurs AID respectifs.

Créons notre fichier que nous appellerons « monapplet.app ». Il contiendra la ligne suivante :

monpackage.MonApplet 0x01:0x02:0x03:0x04:0x05:0x06:0x07:0x08:0x09:0x00:0x00

Nous pouvons maintenant lancer notre simulateur :

Maintenant que notre simulateur est lancé, lançons notre application cliente :

Commençons par interroger le compteur : tapons 1 puis validons :

Le compteur est bien à 0. Incrémentons maintenant le compteur trois fois puis décrémentons-le une fois. Lorsque nous réinterrogeons la carte, le compteur vaut 2 donc tout va bien :

Quittons maintenant notre application cliente (commande 5). Nous pouvons voir que le simulateur se termine automatiquement à la réception de la commande « powerdown » :

Lançons CREF à partir de l'image EEPROM que nous avons générée (cf. VI.c)) :

Nous pouvons désormais lancer notre application cliente et observer les mêmes résultats qu'avec JCWDE (cf. VIII.a)). En revanche, l'état de la carte (le compteur) est conservé d'une session à l'autre.