Skip to main content

A JavaCard bytecode emulator

Project description


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


The following script can be ran by 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.


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:


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


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

$ hg clone

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
$ hg clone

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:

$ --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 By default, it will emulate a JavaCard Classic 3.0.1, if you need another version, just give it as parameter. For instance:

$ ./ 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.


  • 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.


The documentation is autogenerated and gently published by ReadTheDocs after every commit.

Project details

Release history Release notifications

This version


Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page