A JavaCard bytecode emulator
Project description
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.
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.
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.
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 BitBucket, 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.
