######### CAPRunner #########

%%%%%%%%%%%%%%%%%%%%%%%%%% JavaCard ByteCode Emulator %%%%%%%%%%%%%%%%%%%%%%%%%%

Overview

CAPRunner is a javacard bytecode emulator that is able to execute CAP files. It also comes with an handy runcap.py that bind them together and allow you to send some APDUs to a CAP file (without the need for a smartcard).

Example

The following script can be ran by runcap.py. It loads a CAP file, install and instanciate an applet from the file, send two APDu and check their Status Word::

load: /path/to/helloworld.cap

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

Select HelloWorld //aid/A000000062/03010C0101

==> 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

The example is taken from the JavaCard kit wich can be found under samples/classic_applets/HelloWorld.

Dependencies

In order to compile CAP files, you will need a working Java Development Kit together with a JavaCard Development Kit.

This project also relies on the following other ones:

• pythoncard_ which provide the JavaCard OS functionnalities in Python.
• and (optionnaly) pythonplatform_ which provides a minimal set of functionnalities from the globalplatform_ World.

.. note:: You will only need pythonplatform if your applet relies on some globalplatform functionnalities like secure messaging.

Installation

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

$ git clone https://github.com/benallard/caprunner.git

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)::

$ git clone https://github.com/benallard/pythoncard.git
$ git clone https://github.com/benallard/pythonplatform.git

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.

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 documentation_ for the format of the order to send to runcap.

Run the tests

python -m unittest discover test

Contribution

• If an issue is bugging you, the issue tracker_ is your best friend to begin with.
• If you want to help me improve this project, write some more docs or add functionnalities, the best for you is to make yourself an account on Github, fork the repository and make a Pull request. Chances are big that I also accept patches per mail.

RTFM !

The documentation_ is autogenerated and gently published by ReadTheDocs_ after every commit.

.. _documentation: http://caprunner.readthedocs.org .. _ReadTheDocs: http://readthedocs.org/ .. _pythoncard: https://github.com/benallard/pythoncard .. _pythonplatform: https://github.com/benallard/pythonplatform .. _Git: https://git-scm.com/ .. _globalplatform: http://www.globalplatform.org/ .. _issue tracker: https://github.com/benallard/caprunner/issues .. _Github: https://github.com .. _repository: https://github.com/benallard/caprunner