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¶
2.3.3.1. 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.
2.3.3.2. 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.
2.3.3.3. 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.
2.3.3.4. Print the log¶
There is also a command to print an internal log of what happen during the last APDU processing:
log;
2.3.3.5. Example¶
The following example is used to test the HelloWorld example from the JavaCard Development Kit.
1 2 3 4 5 6 7 8 9 | 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.
Footnotes
[1] | This is the concatenation of the following three fields, each one prepended with its own length (which is 0 if the field is empty)
|