Java Card Firewall Tester

AUTHORS

Wojciech Mostowski, woj@cs.ru.nl
Erik Poll, erikpoll@cs.ru.nl
Radboud University Nijmegen
The Netherlands

Copyright (c) Wojciech Mostowski, Erik Poll,
Radboud University Nijmegen (RU),
Stichting Technische Wetenschappen (STW)

INTRODUCTION

The Java Card Firewall Tester is a suite of programs to thoroughly 
test the firewall mechanism on a Java Card smartcard. The test suite
consists of a set of Java Card applets/libraries and a host
application. The general usage of this test suite is to load the test
applets onto the smartcard,  run the host application, stick the
smartcard into the reader and get the compliance report on your
screen.

LICENCE

This program is distributed under the licence terms described in the
LICENCE file. In particular, you are only allowed to use this program
for non-commercial purposes, and we do not take any responsibility
whatsoever for any damage that may be caused by the use of this
program (broken Java Cards included). For details please refer to the
LICENCE file included in the distribution.

CREDITS

This program has been developed for the PinPas Java Card project (see
http://www.win.tue.nl/pinpasjc/). The project is supported by
Sentinels, the Dutch research programme in computer security, which is
financed by the Technology Foundation STW, the Netherlands
Organisation for Scientific Research (NWO), and the Dutch Ministry of
Economic Affairs.

We would also like to thank Marc Witteman of Riscure
(http://www.riscure.com) for his insights, ideas, and help.

REQUIREMENTS

To run the test you need the following setup:

1. A PC/SC compatible smart card reader properly setup on your system
2. A Java Card smartcard (version 2.1.* or 2.2.*)
3. A Java Card development kit (optionally, see below):
   http://java.sun.com/javacard/
4. A Java Card applet loader / management system that works with your
   card: 
   * Open source Global Platform implementation (GPShell):
     http://sourceforge.net/projects/globalplatform/
   * JCOP tools Eclipse plug-in (not available publicly at the moment)
   * Any other proprietary on-card applet management system
5. Java 6 runtime environment: http://java.sun.com

INSTRUCTIONS

The first thing to get working is to setup the PC/SC compatible smart
card reader on your system. On Windows this should be as easy as just
installing the reader driver. On Linux pcsc-lite
(http://pcsclite.alioth.debian.org/) is what you need plus an
appropriate reader driver. 

Once this is done you need to get the test applets onto the card. We
provided sources and binaries for both major versions of Java Card on
the market:

* Directory firewallapplets_jc21 contains applets for Java Card 2.1.*
* Directory firewallapplets_jc22 contains applets for Java Card 2.2.1

(In case you need to test a 2.2 Java Card you have to compile the
applets yourself).

In most cases it will be enough if you load and instantiate the
following files onto the card with your favourite applet loading
program, in this order:

* firewallinterface.cap (no applets, library package)
* firewallserver.cap
* firewallserverms.cap (only Java Card 2.2.1)
* firewallclients.cap

However, it may happen that your card either 

(a) needs massaged CAP files for the on-card byte verifier,

(b) needs proprietary format of applet load files,

(c) will refuse to load the applets altogether, because they refer to
    Shareable interface objects.

In all three cases you are mostly on your own:

* Not much can be done with issue (c). 

* To resolve issue (a) a CAP file transformer from Trusted Labs
  (http://www.trusted-labs.com/) might be helpful.

* To help you resolve issue (b) we provided source files of the
  applets and appropriate Makefiles (Unix-like systems only). Here use
  your favourite tool for your Java Card with our source files.

**IMPORTANT** Deletion of applets: once you loaded all the applets (or
only some of them) to the card you may find it impossible to delete
them with your favourite tool. This is because there are reference
interdependencies between all the applets. To resolve this you have to
issue one reset APDU to any of the installed applets, you can do this
with the host application run with the -reset option (note that after
this the applets are not usable for the firewall test  anymore, they
need to be reloaded and re-instantiated).

Once you have the applets on your card you can run the host
application, from the Command Prompt (Windows) or Terminal (Linux): 

* go to the firewallhost directory:

  cd firewallhost

* run:

  - To test a 2.2.1 Java Card: "java -jar firewallhost.jar"

  - To test a 2.1.* Java Card: "java -jar firewallhost.jar -jc21"

  - To reset the interdependencies in the applets:
    "java -jar firewallhost.jar -reset"

In the first two cases the program will report what is wrong (if
anything) with the firewall implementation on your card. May the
messages be too cryptic you will have to find the corresponding test
in the applet  source file (ClientApplet1.java) and see what exactly
failed.

SUPPORT

As the licence states, we provide *no* support for this program.
However, if you would like to give us feedback or comments, please
free to contact us:

Wojciech Mostowski: woj@cs.ru.nl
Erik Poll: erikpoll@cs.ru.nl
