JCOP Shell Tutorial

The sections below provide an introduction on how to use the basic functionality of the JCOP Shell (also referred to as JCShell).

For detailed description and additional information seeJCOP Shell Details already but want to explore even more exciting JCShell features.

Introduction

The JCShell is a powerful tool to interact with your JavaCard. You can type commands interactively or you can run scripts against a JavaCard. The JCShell allows you to exercise functions of a JavaCard on the APDU level.

The GlobalPlatform 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.

Command Prompts

When the JCShell starts, it will display a simple prompt, designated by a -, that indicates that no smart card reader and card is yet attached. The command to exit this state is /terminal. It will establish a connection to a PC/SC smart card reader if possible. Upon the successful completion of this command the prompt changes to a caret (>) indicating connection to a smart card reader, but not to a card. In order to connect to a card, the command /card is to be used: It will reset the card (request the ATR) and try to select the CardManager since it expects an GlobalPlatform compatible card. If it is successful, the prompt changes to a cm> indicating successful activation of the CardManager plugin.

The JCShell can also connect to the JCOP emulation (JC32) instead of connecting to a real card. This can be done by using the /terminal Remote command instead of /terminal.

Remark: Before you execute any command you might want to enable the trace mode of the JCShell to make more information such as APDUs going back and forth visible. This is done by the command /mode trace=on.

Interactive Help

At any time during the execution of the JCShell, interactive online help to all commands is available by typing ? <command> or /help <command> (for more extensive text). All commands explained below usually also exist in more powerful, yet parameterized, versions. Please refer to the online help for explanations on these options not detailed in this tutorial.

Generic Commands

Some commands are only valid if a particular JCShell plugin has been activated. For instance, the CardManager plugin indicated by the command prompt cm> as mentioned previously. However, the commands below are those that are always available in the JCShell independent of a particular plugin.

Here is a list of currently active commands. For detailed command description see:
JCShell detailed command description

help / ?
usage: help [topic]
Displays available commands (if is used without parameters) or syntax information for a particular command.
List of CardManager-Commands or help to those commands are available only when CardManager has been activated (prompt is cm>).
quit
Exit JCShell
version
Display the current jcshell program version and it's build timestamp.
>
Redirect shell output.
usage: > {0|1|2|3} [-|[+]file]
/applet
Switch to specified applet plugin. By default a new instance of the desired plugin is created. If a plugin instance (with the same nickname) currenlty active onanother logical channel is to be reused, then the reuse option must be set. Reusing might make sense when communicating with a multi-selectable applet. If no nickname is provided, all registered plugins are listed.
usage: /applet [nickname [--reuse|-r]]
/atr
Resets the card (requests an Answer To Reset) without selecting an applet.
Waiting for card with timeout only with given param.
Uses only the reader selected with term-command.
usage: /atr [[-t|time num[s|ms]]]

/bugz
Starting a BUGZ-Session
Required: set variable "bugz-classpath" with the path to bugz and JRE before:
/set-var bugz-classpath "c:/Projekte/ibm/nJCOP/lib/bugz.jar;c:/jdk1.4.2_04/lib/tools.jar"
/cap-clear
Remove DAP and Delegated Management information from a CAP-file.
usage: /cap-clear [-p|--package package-name] CAP-file
/cap-info
Displays information about a particular CAP-file.
usage: /cap-info [-p|--package package-name] CAP-file
/cap-inst-auth
Authorize a package in a CAP-file for delegated installation of an applet of this package. The resulting Install Token information is stored in the CAP-file.
usage: /cap-inst-auth [-e|--delegation][-l|--cm-lock][-t|--terminate][-d|--default] [-c|--pin-change][-s|--security-domain][-b|--sd-dap][-m|--mandated-dap][-p|--package package-name] [-i|--instaid AID][-u|--params parameters][-n|--tokenpin PIN][-f|--target CAP-file] applet-AID CAP-file tokenspec
/cap-load-auth
Authorize a package in a CAP-file for delegated loading. The resulting Load Token information is stored in the CAP-file.
usage: /cap-load-auth [-p|--package package-name][-i|--tokenpin PIN][-s|--sdaid AID] [-l|--params parameters][-t|--target CAP-file] CAP-file tokenspec

/cap-sign
Sign a package in a CAP-file. The resulting DAP information is stored in the CAP-file. Note: Signing a CAP-file implies invalidating (removing) all Load/Install Tokens in the CAP-file.
usage: /cap-sign [-d|--debug][-p|--package package-name][-i|--tokenpin PIN][-t|--target CAP-file][-a|--algorithm VOP201|GP211] CAP-file AID tokenspec
/card
Resets the inserted card, gets the ATR and selects the CardManager (default=GlobalPlatform CardManager) via the default logical channel (zero).
Uses only the reader selected with term-command.
usage: /card [-t|time num[s|ms]][-c|card-manager class-name][-a|card-manager-aid aid][-v|--verbose]
/channel
List applets (JCShellPlugins) and their channels
usage: /channel [<0-3>]
/clear-vars
Clear variable pool
usage: /clear-vars
/close
Closes the connection to the terminal (also card disconnection). Terminal now is waiting for new connections.
/dialog
Display message dialog and wait for OK.
usage: /dialog [-V|--split-value][-c|--choice][-s|--sound sound][-l|--loop][title [text [label..]*
/echo
Arguments to be output/echoed.
usage: /echo[-0|1|2|3] args..
/error
Abort execution of DEFUN or SCRIPT and set arguments as error string (${last.error} - can be checked in try/catch).
usage: /error args..
/exec
Execute/kill/wait a subprocess.
usage: /exec [[-a|--async][-s|--silent][-l|--label label][-k|--kill][command [argument..]*
/expr
Arguments are evaluated as expression and the result is set as return value.
usage: /expr args..
/glob
Collect all file name matching given patterns and as return value. E.g. X[*]=$(/glob *.jcsh)
usage: /glob pattern..
/identify
Show card information data (only if card is connected).
usage: identify [-q]
/list-vars
Displays matching/all JCShell internal variables, e.g. keys.
usage: /list-vars [[pattern|!pattern]..]
/manage-channel
ISO 7816-4/Global Platform MANAGE CHANNEL command.
Either opens the next available supplementary logical channel or closes the current logical channel.
Upon opening a channel the new channel becomes the current channel. Upon closing a supplementary channel the default channel (zero) becomes the current channel.
usage: /manage-channel open|close
/mode
Set the JCShell mode of operation, e.g., whether full APDU command tracing shall be enabled or not.
usage: /mode [trace=on|off|num][echo=on|off][verbose=on|off][debug=on|off]
/printf
Format args according to format specification (like C printf).
usage: /printf [-0|1|2|3] format args..
/register
Without param: List the applets introduce to the shell.
With param: Introduce an applet to the shell.
The meaning of "applet" is a JCShellPlugin - a class with additional JCShell commands.
usage: /register [name aid [plugin] ]
/remote
Send commands to nJCOP simulation and print returned information.
Some commands also set a return value. This command is for development purposes only.
usage: /remote [-0|1|2|3] command...
/robot
Include java.awt.Robot class functionality.
This class is used to generate native system input events for the purposes of test automation, self-running demos, and other applications where control of the mouse and keyboard is needed. The primary purpose of Robot is to facilitate automated testing of Java platform implementations.
usage: /robot command [param];
/r-echo
Echo arguments to be output (remotely).
usage: /r-echo args..
/select
Selects the applet with the given AID on the card either on the current logical channel or optionally on another, possibly new, logical channel.
usage: /select AID [<0-3>]
/send
Send an APDU unconditional, bypassing the plugin(s), using negotiated protocol/channel or raw.
usage: /send [-r|--raw][nad=NAD][-t|--timeout num] apdu [pattern..]
/set-channel
Sets the logical channel number used in any subsequent APDU communication.
By default the logical channel number is zero.
usage: /set-channel [{0|1|2|3}]
/set-var
Sets the named JCShell internal variable.
usage: /set-var [-d|--def][-g|--global][-q|--quote] varname [expr..]
/sleep
Delay execution for given amount of time.
usage: /sleep time[s|ms]
/terminal
Connects to a given terminal (smart card reader device) or obtains status information if already connected.
Select Card-Terminal or Simulation.
usage: /terminal [[-p|--pop][[term] ]]
/test-suite
Control test suite (Only for special tests - not inside Eclipse plug-in).
usage: /test-suite [[--details][{--test-suite ...|--summary ...|--start-gui|--stop-gui|--open-folder ...| --enlist-test ...|--close-folder|--test-start ...|--test-passed|--test-not-run|--test-failed ...|--test-not-applicable ...}]]

Remarks: The JCShell supports automatic command completion. The operator | can be used to indicate that the following ASCII string shall be converted into a HEX string. For instance, selecting the applet with the AID SampleApplet can be done using the command /select 53616d706c654170706c6574 but also by the command /select |SampleApplet.



JCShell Plugins

In the JCShell, a plugin is the off-card representative of an applet on the card: It provides a convenient shell interface to the commands known to the respective applet. In the case of an e-purse application, it may provide commands like load or purchase to execute the complete debit or credit functions of the applet, thus completely hiding the complexities of the respective application inside of the plugin. How plugins can be developed and used in the JCShell is not covered in this tutorial.

One particularly important plugin, however, is the one dealing with the GlobalPlatform CardManager. It's functionality allows to perform card management operations such as applet loading, installation or deletion.
The following plugins will be described here:


GlobalPlatform CardManager Plugin

This plugin handles all commands necessary to make effective use of an GlobalPlatform card. It's identification is cm> and the following command sets are available if it is active, i.e., if the CardManager on the card has been activated either by an explicit /select command or the /card command as already explained above.

Here is a list of currently active commands. For detailed command description see:
CardManager Plugin detailed command description

auth
Authenticate using the given (or default) initial key (key set version 255).
usage:auth [plain|mac|enc] [keydata]
begin-RMAC
Global Platform BEGIN R-MAC command.
usage:begin-RMAC [-c [data]]
card-info
Displays card information (Card Manager state/AID and registry info). Obtain information about applets and packages currently contained in the card. Also dump information about the Open Platform lifecycle of the CardManager and the applets (Authentication required).
usage: card-info [[-o|--old-format][-q|--quiet][-x|--exclude][-e|--exists][-n|--not-exists] [-a|--applets][-p|--packages][AID..]]
change-pin
Changes the Open Platform 2.0.1' Global PIN value and it's max. false retry limit (Authentication required).
usage: change-pin <3-15> value
cvm-block-unblock
This command allowes to block/unblock the CVM. This is an extension to the Global Platform specification.
usage:cvm-block-unblock block|unblock
cvm-update
This command updates the CVM value and/or the CVM try limit. This is an extension to the Global Platform specification. The command is only allowed in the context of a secure channel using SCP 02.
usage:cvm-update [[-l|--limit retry-limit][-f|--format format][value]]
delete
Delete an applet or package from the card (Authentication required).
usage: delete [-r|--delete-related] AID
delete-key
Delete keys currently stored in the off-card repository.
By default all keys are removed from the repository.
usage:delete-key [keyref..]
end-RMAC
Global Platform END R-MAC command.
usage:end-RMAC
extradite
Extradite an applet to another Security Domain. Corresponds with the Global Platform Install [for extradition] command.
usage:extradite sdAID appAID
ext-auth
Global Platform EXTERNAL AUTHENTICATE command.
Complete the authentication to the CardManager with the EXTERNAL AUTHENTICATE command.
usage: ext-auth [plain|mac|enc|rmac|crmac|crmacenc]
flush
Flush Global Platform session info (close secure channel).
usage:flush
get-data
Global Platform GET DATA command used to retrieve data objects.
usage:get-data tag
get-cplc
Get CardProductionLifeCycle information from the card (as defined in Open Platform).
usage:get-cplc
init-update
Global Platform INITIALIZE-UPDATE command.
Execute the INITIALIZE UPDATE command to begin authentication to the CardManager. Prerequisite is the knowledge of the appropriate keys. These keys must be set via the set-key command.
usage: init-update [key-set [scp]]
install
Install an applet (via the Card Manager) under an AID with certain privileges and, if desired, make it selectable.
usage: install [-e|--delegation][-l|--cm-lock][-t|--terminate][-d|--default][-p|--pin-change][-s|--security-domain] [-b|--sd-dap][-m|--mandated-dap][-q|--install-param params][-i|--instance-aid AID][-o|--install-only] pkgAID appAID
install-rom-package
Install a romized package.
usage:install-rom-package [-s|--sd SD-AID] PKG-AID PKGID
ls
Displays card information (Card Manager state/AID and registry info). Alias to "card-info"
usage:ls [[-o|--old-format][-q|--quiet][-x|--exclude][-e|--exists][-n|--not-exists][-a|--applets][-p|--packages] [AID..]]
make-selectable
Make a previously installed applet selectable. Corresponds with the Global Platform Install [for make selectable] command.
usage:make-selectable [-d|--default-applet] AID
personalize
Initiate that the currenlty selected Security Domain shall personalize one of its associated applets (via subsequent STORE DATA commands). Corresponds with the Global Platform Install [for personalization] command.
usage:personalize appAID
print-key
Print information about keys currently stored in the off-card repository.
By default information about all keys is printed.
usage:print-key [keyref..]
put-data
Visa Open Platform PUT DATA command used to write data objects.
usage:put-data tag data
put-key
Load new keys or key sets into the card, possibly exchanging the currently active ones (Authentication required).
All keys must belong to the same key set and must be ordered (lowest index first).If the operation mode is 'replace' a replace key set must be defined.
usage: put-key [-m|--mode modify|replace|add][-r|--replace-keySet key-set]keydef|keyref..
put-keyset
Load a complete key set into the card. The difference to the put-key command is that this command does not allow to load single keys (Authentication required).
Add/modify/replace one DES key set (keys at index 1,2 and 3). If the mode option is not set the default mode is 'add' and if 'add' doesn't work the 'modify' mode is tried. If the operation mode is 'replace' a replace key set must be defined.
usage: put-keyset [-m|--mode modify|replace|add][-r|--replace-keySet key-set]key-set..
put-pub-key
Add a RSA public key to the desired key set at the desired key index. The specified token will be searched for key pairs (private certs) holding public keys which can be put onto the card.
usage:put-pub-key [-i|--tokenpin PIN][-d|--keyID key-ID] key-set tokenspec
select
Send select command APDU to card.
usage:select
Command generated APDU is: '0x00A4040008A00000000300000000'
send
Send APDU via secure channel, if established.
usage:send apdu [pattern..]
session-info
Print Global Platform session (secure channel) status.
usage:session-info
set-aid
Change the Card Manager AID via an Open Platform 2.0.1' PUT DATA command.
usage:set-aid AID
set-applet
Set the Open Platform life cycle of an applet (Authentication required).
usage: set-applet AID installed|selectable|personalized|blocked|locked.
set-scp
Allows defining the secure channel protocol to be used in subsequent implicit channel setup. If no secure channel exists and a SCP has been set using this command, implicit channel setup takes place automatically as soon as an APDU is sent.
usage:set-scp scp

set-key
Registers the secret key(s) with the CardManager plugin for use in the secure messaging executed during authentication. No interaction with card.
usage: set-key keydef..
set-security
Sets the security level of the current secure channel.
usage:set-security plain|mac|enc|rmac|crmac|crmacenc
set-state
Set the CardManager life cycle state.
usage: set-state ready|initialized|secured|locked|terminated.
store-aid
Change the Card Manager AID via a Global Platform 2.1.1 STORE DATA command.
usage:store-aid AID
store-dap-key
Set DAP verification public key information via a Global Platform STORE DATA command. The public key is stored in key set version 0x73 at index 1.
usage:store-dap-key [-i|--tokenpin PIN] tokenspec
store-data
Global Platform STORE DATA command used to transfer data to an application or Security Domain.
usage:store-data [-m|--more-blocks][-b|--block-number number] data
store-keyset
Add or replace one complete key set verison (keys at index 1,2 and 3) via a Global Platform STORE DATA command.
usage:store-keyset [-r|--replace-keySet replace-key-set] key-set
unblock-pin
Unblock the Open Platform 2.0.1 Global PIN (Authentication required).
usage: unblock-pin
upload
Load a package onto the card via the Card Manager.
usage: upload [-p|--progress][-c|--components][-r|--random][-l|--package package-name] [-s|--sd SD-AID][-m|--params parameters][-b|--block_length length][-a|--auto][-d|--load-debug] CAP-file

RMI CardManager Plugin

JCShell plugin representing JC RMI server applets, which might also be OPApplets. It's identification is rmi> and the following command sets are available if it is active, i.e., if the RMI-Javacard-Applet on the card has been activated by an explicit /select command.

Here is a list of currently active commands. For detailed command description see:
RMI CardManager Plugin detailed command description

clear
Clears the list of remote objects and methods currently known by the plugin..
usage: clear
invoke
Invokes a previously defined remote method. Optionally, the return value can be stored in a JCShell variablefor later referencing.
If a remote object reference is returned, it is automatically added to the list of objects known by this plugin.
usage: invoke [-r|--return-value variable-name] ID [parameter..]
list
Lists the remote objects and methods currently known by the plugin.
usage: list
method
Defines a remote method for a particular remote object. Optionally, the method ID can be stored in a JCShell variable for later referencing.
usage: method [-m|--method-id variable-name] OID method-name method-signature
object
Allows to explicitely define remote objects within the plugin. This command should not be used under normal cicumstances.
usage: object [-c|--with-class][-i|--ins-byte ins-byte] FCI-or-descriptor

Hex-Data Considerations

Some commands references data in form of 'HEX[|CHARS[|HEX...]]'.
HEX
Is a possibly empty sequence of pairs of hex digits forming a byte sequence.
CHARS
Is a possibly empty sequence of charaters. Their ASCII encoding forms a sequence of bytes.
|
The | switches modes (HEX/CHARS).
Additionally, nested elements of the form `#(...)' are parsed. Instead of () you can also use the braces [], {}, <>. The "#" element is replace by the number bytes enclosed in the matching braces.

Examples:
"0102|ab|03 04|cd"    ==> 01 02 61 62 03 04 63 64
"01#(|ab|#{FE FF})"   ==> 01 05 61 62 02 FE FF



A Sample JCShell Session

The following sequence of JCShell commands represents a typical shell session in which an applet is loaded onto a card, a command is sent to the applet for testing purposes and finally the applet is deleted.

Switch trace mode on and connect to a PC/SC smart card reader
/mode trace=on
/terminal

Reset the card (request ATR) and select the CardManager
/card

Set the keys in key set 255 of the JCShell for authentication later on
set-key 255/1/DES-ECB/404142434445464748494A4B4C4D4E4F
set-key 255/2/DES-ECB/404142434445464748494A4B4C4D4E4F
set-key 255/3/DES-ECB/404142434445464748494A4B4C4D4E4F

Begin authentication using the appropriate key set
init-update 255

Complete authentication
ext-auth

Upload the package holding the applet
upload c:/sample.cap

Install the applet in the package
install |PackageAID |AppletAID

Display the card registry to check if the applet is loaded and installed
card-info

Select the applet
/select |AppletAID

Send a command to the applet (e.g. for testing the applet)
/send 00CA000100

Select the CardManager again
select

Do authentication again
init-update 255
ext-auth

Delete the applet and the package
delete |AppletAID
delete |PackageAID

Display the card registry to check if the package/applet is gone
card-info