2. User Manual

2.1. Introduction

This part of this document describes how to use CAPRunner from a User point of vue.

2.2. Installation

From the README:

2.2.1. Installation

Your best chance for the moment is to clone the repository using Mercurial to a local directory:

$ hg clone https://bitbucket.org/benallard/caprunner/

This will create a copy of the repository in a caprunner directory.

In order to get the dependencies right, I suggest you also clone their repositories (the second one is optionnal):

$ hg clone https://bitbucket.org/benallard/pythoncard/
$ hg clone https://bitbucket.org/benallard/pythonplatform/

Finally, the easiest way to get the dependencies resolved is to copy (or link on UNIX) the following directories at the root of the caprunner directory:

  • python, pythoncard and pythoncardx from the pythoncard directory
  • and (optionnaly) org from the pythonplatform directory.

2.2.2. Getting started

As a final step, you will need to compile the export files used during compilation of your applet into a JSON file. This step is needed in order to not read every single export file at each startup.

This is done with the following command line:

$ genref.py --dump dump.json /path/to/export_files

This will generate a file called dump.json containing the necessary information from the export files. The path given as second parameter is the directory containing the export files from your JavaCard Development Kit (e.g. the api21_export_files directory for a JavaCard 2.1.2).

CAPRunner will expect the generated json file to be called <JavaCard version>.json

Finally, you should be able to launch runcap.py. By default, it will emulate a JavaCard Classic 3.0.1, if you need another version, just give it as parameter. For instance:

$ ./runcap.py 2.1.2

Starting from here, runcap will wait for your orders. Please refer to the Command format for the format of the order to send to runcap.

2.3. RunCAP

2.3.1. Overview

2.3.2. Parameters

2.3.3. Command format APDUs

APDU are sent to the CAP file in the following format:

==> se nd ap du;
<== ex pe ct ed re tu rn co de;

Each byte is in hexadecimal format without 0x preceding them.

If the CAP file returns another return code, the execution will stop. Load command

To load an applet into the interpreter, the following command has to be used:

load: /path/to/capfile.cap

The result of this command will be that the given CAP file will be loaded into memory and its applets will be ready for the Install command. At this step, the whole CAP file will be parsed. Install command

To install an applet into the interpreter, and make it selectable, the following command has to be used:

install: data : offset

The data is the one tramsmitted to Applet.install() [1] prepended with AIDlen || AID of the applet to install. The offset parameter indicate the offset of the AIDlen byte inside the data. Example

The following example is used to test the HelloWorld example from the JavaCard Development Kit.

load: HelloWorld-2.1.2.cap

install: 0a a0 00 00 00 62 03 01 0c 01 01 00 00 00 : 00

==> 00 a4 04 00 0a a0 00 00 00 62 03 01 0c 01 01 7F
<== 00 A4 04 00 0A A0 00 00 00 62 03 01 0C 01 01 90 00

==> 80 B8 00 00 0C 0A
<== 80 B8 00 00 0C 90 00
  • Line 1, the CAP file HelloWorld-2.1.2.cap is loaded inside the interpreter.

  • Line 3, the applet with AID a0 00 00 00 62 03 01 0c 01 01 is being installed. This applet is included inside the CAP file. The data transmitted to the function is constructed as follow:

    • First, the length of the AID on one byte: 0a
    • Then comes the AID itself a0 00 00 00 62 03 01 0c 01 01
    • And finally the data to be transmitted to the Applet.install() function.

    As second parameter comes the offset of the AIDlength bytes, 00 in our case as we did’nt gave junk data in the input.

  • Line 5-6, the first APDU is being set to the Applet, namely a SELECT command with the AID of the installed applet. this select is processed by the interpreter and then by the Applet itself, returning some data.

  • Line 8-9, a random command is processed by the Applet and some data is returned.



This is the concatenation of the following three fields, each one prepended with its own length (which is 0 if the field is empty)

  • instance AID (if not specified the applet AID will be taken)
  • control info
  • applet data

2.4. RefCollection

2.5. Export