Command Line Tools
The sections below provide a quick overview on how to use the JCOP Tools
from the command line on both Windows and Unix.
Introduction
The JCOP Tools ship with a number of command line tools which allow for an
applet development outside of the Eclipse IDE. These include a Bytecode
converter for the creation of JCOP applet code, a shell to talk to
real cards and/or JCOP simulations, and a number of miscellaneous tools
such as an export-file maniupulator, Bytecode assembler and/or deconverter.
The Open Platform functionality is already available in the shell. APDU commands of custom
applets can be easly integrated by either writing simple scripts or by extending the shell
functionality with a plugin.
Prerequisites
Windows Prerequisites
Install the cygnus tools from www.cygwin.com. The JCOP command line tools, especially
the shell, can be especially efficiently used from an emacs shell buffer or terminal
window. Set and export JAVA_HOME to the base directory of the JCK installation
which should be used.
Linux Prerequisites
Install the MUSCLE pcsc-lite software from www.linuxnet.com. Install the PCSC daemon,
and proper driver software for your reader. Set and export the shell variable
PCSC_HOME to the base directory of your PCSC installation, typically
/usr/local/pcsc. Set and export JAVA_HOME to the base directory of the JCK installation
which should be used.
Location
The JCOP command line tools such as the converter can be found in subdirectories of the
JCOP Tools eclipse plugin. If you have installed Eclipse in /eclipse and the version 1.0.1 of
the Tools, the path to the shell scripts and executables is
/eclipse/plugins/com.ibm.bluez.jcop.eclipse_1.0.1/prebuilt/bin/ and
/eclipse/plugins/com.ibm.bluez.jcop.eclipse_1.0.1/prebuilt/bin/${ARCH} where
ARCH is either win32 or linux.
The JCOP simulations can be found in the targetpack-plugin, i.e.
/eclipse/plugins/com.ibm.bluez.jcop.eclipse.targetpack_1.0.1/lib/targets/${ARCH}.
The JCOP APIs which are required for converting Bytecode can also be found in the
targetpack-plugin, i.e. /eclipse/plugins/com.ibm.bluez.jcop.eclipse.targetpack_1.0.1/lib/apis
and covers both necessary class-files as well as expoprt-files.
Sample Session
In the following, the steps to convert an applet and to download it on a JCOP
simulation and/or card are described. It is assumed that the applet consists of a
class Simple.java which belongs to the package simple and is stored in /simple.
Furthermore, it is assumed that the path to the JCOP Development Tools
and JCOP Simulations have been added to your PATH variable. Additonally, the
environment variables JAVA_HOME and PCSC_HOME have been properly setup.
Compile the applet source code:
cd /simple
javac -classpath /eclipse/plugins/com.ibm.bluez.jcop.eclipse.targetpack_1.0.1/lib/apis/jc211.jar Simple.java
Convert the applet class-files:
cd /simple
tric.sh -dd /simple/output_directory -ep /eclipse/plugins/com.ibm.bluez.jcop.eclipse.targetpack_1.0.1/lib/apis/jc211.jar -cp / -g -ncv -cf -xf -a "|applet_aid" simple.Simple simple "|package_aid" 1 0
Outputs the generated cap-file in /simple/output_directory/simple/javacard/simple.cap. The applet and package AID are given here in a pseudo-ascii-notation, but can also be specified in hexadecimal
notation such as 0xa:0x1... or 0a0100....
Start a jcop simulation:
/eclipse/plugins/com.ibm.bluez.jcop.eclipse.targetpack_1.0.1/lib/targets/linux/JCOP30/jcop.exe
Start the shell:
shell.sh
Type the following commands in the shell to connect, authenticate and install the
applet on the card:
/mode trace=on
/term Remote
/card
auth
ls
upload /simple/output_directory/simple/javacard/simple.cap
ls
install |package_aid |applet_aid
select |applet_aid
/send ...
To download and install the applet on a real card, just use the PCSC terminal:
/mode trace=on
/term PCSC|any|s
/card
auth
ls
upload /simple/output_directory/simple/javacard/simple.cap
ls
install |package_aid |applet_aid
select |applet_aid
/send ...
CLI Tools Reference Documentation
CardMan (cardman.exe)
CardMan is a standalone command-line tool to perform basic OpenPlatform
compliant card management operations on sample cards. Detailed
information is available
here.
Shell (shell.sh)
The shell is available inside Eclipse as well as on the command line.
Detailed information is available here.
Converter (converter.sh, tric.sh)
The converter translates standards Java bytecode to bytecode suitable for the execution on
JCOPs, and takes the following parameters:
| -ep path |
|
A ';' or ':'-spearated list of zip/jar files and directories where to
look for export files. Note that export files are searched relative to the
path entries and are expected to be stored in proper subdirectories
(e.g. <BASE_DIR>/java/lang/javacard/lang.exp).
|
| -cp path |
|
A ';' or ':'-spearated list of zip/jar files and directories where to
look for class files. Note that class files are searched relative to the
path entries and are expected to be stored in proper subdirectories
(e.g. <BASE_DIR>/java/lang/Object.class).
|
| -cfs class_filename1 class_filename2 ... |
|
This option allows to specify individual class-files on the command line which the
converter should load and take for the cap-file to be generated.
|
| -dd outdir |
|
Specifies the base directory where to store the final output. By default, the
converter stores the resulting files in the temporary system directory (e.g. /tmp).
Also note that by default, the final cap and export file are stored in
a subdirectory of outdir whose path consists of package name and
the string javacard
(e.g. <BASE_DIR>/<MY_PACKAGE>/javacard/<MY_PACKAGE>.cap).
|
| -df |
|
If this option is enabled, the converter stores the final outputfiles, cap file
and export file, directly in the directory specified by the -dd option.
No subdirectories are thus created.
|
| -a applet_aid applet_class -a ... |
|
This option allows to specify an AID for an applet. If an applet is converted and
no AID is given on the command line, the converter derives the applet AIDs from
the package AID. If the package contains only one applet, its AID will be the
same as the package AID. If the package contains multiple applets, each applet
contains an AID consisting of package AID and an additional byte representing the
number of the applet in the package.
As soon as an applet is specified on the command line, the converter expects
the AIDs of all applets in the package to be specified on the command line.
The AID can be specified in different formats, for example
0x01:0x02:0x03:0x04:0x05:0x06, 010203040506 or
even |asciibased|00. The class name of the applet must be specified
in the standard, fully qualified manner, e.g. java.lang.Object.
|
| -ef |
|
Tells the converter to create an export file for the package to convert and
store it together with the cap file in the specified output directory.
|
| -em |
|
Tells the converter to layout the cap-file according to the token mappings
found for this package on the export-path.
|
| -xf or -g |
|
Tells the converter to create an XML file for the package to convert and
store it together with the cap file in the specified output directory. This file
is required for debugging in Eclipse.
|
| -cf |
|
Tells the converter to create a file commenting the contents of the generated
cap file. This is only useful for debugging the converter itself.
|
| -si |
|
Tells the converter to suppress certain output.
|
| -asm |
|
Outputs an assembler file which can be used by the assembler to generate a cap-file.
|
| -iasm classname |
|
Specifies the name of the inline assembler class. Not officially supported yet.
|
| -o output_base_name |
|
Specifies the basename of the cap-file to be generated.
|
| -ncv |
|
Do not verify the class-files to be loaded during the cap-file generation process.
|
| -nopts |
|
Switch off all code optimizations.
|
| -t level |
|
Only useful for debugging the converter itself.
|
| -tf file_name |
|
Only useful for debugging the converter itself.
|
| package_name package_aid major minor |
|
These parameters specify the package to be converted (fully qualified), the
AID to use, and the major and minor version to include for the package in
the cap file.
|
Assembler (assembler.sh)
The assmbler expects a .jcasm assembler file and translates it into a cap-file. Typically, you
generate an assembler file with the converter, edit it manually, and then create a cap-file from
the modified assembler file. Note that the assembler does not yet understand the
sourcefile-tag in assembly files created by the converter. You have to remove these entries manually,
before invoking the assembler. A sample invocation looks like this:
assembler.sh -dd /tmp -ep /eclipse/.../apis/jc211.jar demo_queens.jcasm
| -ep path |
|
A ';' or ':'-spearated list of zip/jar files and directories where to
look for export files. Note that export files are searched relative to the
path entries and are expected to be stored in proper subdirectories
(e.g. <BASE_DIR>/java/lang/javacard/lang.exp).
|
| -dd outdir |
|
Specifies the base directory where to store the final output. By default, the
converter stores the resulting files in the temporary system directory (e.g. /tmp).
Also note that by default, the final cap and export file are stored in
a subdirectory of outdir whose path consists of package name and
the string javacard
(e.g. <BASE_DIR>/<MY_PACKAGE>/javacard/<MY_PACKAGE>.cap).
|
| -t level |
|
Only useful for debugging the converter itself.
|
| -tf file_name |
|
Only useful for debugging the converter itself.
|
| assembler_file_name |
|
The name of the input file containing the package in assembly notation.
|
Deconverter (deconverter.sh)
The deconverter expects a .cap file and translates it bacl into one or more class-files. You can
then use a Java decompiler to study the cap-file in more detail. A typical invocation looks like this:
deconverter.sh -dd /tmp -ep /eclipse/.../apis/jc211.jar queens.cap
| -ep path |
|
A ';' or ':'-spearated list of zip/jar files and directories where to
look for export files. Note that export files are searched relative to the
path entries and are expected to be stored in proper subdirectories
(e.g. <BASE_DIR>/java/lang/javacard/lang.exp).
|
| -dd outdir |
|
Specifies the base directory where to store the final output. By default, the
converter stores the resulting files in the temporary system directory (e.g. /tmp).
Also note that by default, the final cap and export file are stored in
a subdirectory of outdir whose path consists of package name and
the string javacard
(e.g. <BASE_DIR>/<MY_PACKAGE>/javacard/<MY_PACKAGE>.cap).
|
| -df |
|
If this option is enabled, the converter stores the final outputfiles, cap file
and export file, directly in the directory specified by the -dd option.
No subdirectories are thus created.
|
| -t level |
|
Only useful for debugging the converter itself.
|
| -tf file_name |
|
Only useful for debugging the converter itself.
|
| cap_file_name |
|
The name of the cap file which is about to be deconverted.
|
|