JCOP Shell Tutorial

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

• Introduction
• Command Prompts
• Interactive Help
• Generic Commands
• JCShell Plugins
• A Sample JCShell Session
• Further Information

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

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

/atr
Resets the card (requests an ATR) without selecting an applet.

/cap-info
Displays information about a particular CAP-file.

/card
Resets the inserted card, gets the ATR and selects the Open Platform CardManager.

/close
Closes the connection to the terminal.

/list-vars
Displays JCShell internal variables, e.g. keys.

/set-var
Sets a JCShell internal variable.

/mode
Set the JCShell mode of operation, e.g., whether full APDU command tracing shall be enabled or not.

/select
Selects the applet with the given AID on the card.

/send
Send an APDU unconditional, bypassing the plugin(s).

/terminal
Connects to a given terminal (smart card reader device) or obtains status information if already connected.

/help
Displays help information for a particular command.

?
Displays syntax information for a particular command or the list of currently available commands if ? is used without parameters.

quit
Terminates the JCShell.

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 OpenPlatform CardManager. It's functionality allows to perform card management operations such as applet loading, installation or deletion.

Open Platform CardManager Plugin

This plugin handles all commands necessary to make effective use of an OpenPlatform 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.

init-update
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.

ext-auth
Complete the authentication to the CardManager with the EXTERNAL AUTHENTICATE command.

upload
Upload a package contained in a JavaCard 2.1.1 compliant CAP-file to the card (Authentication required).

install
Install an applet and register it under an AID (Authentication required). Be aware that the C9 tag needs to be specified manually during the passing of applet install parameters.

delete
Delete an applet or package from the card (Authentication required).

card-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).

set-applet
Set the Open Platform life cycle of an applet (Authentication required).

set-state
Set the CardManager life cycle state.

put-key
Load new keys or key sets into the card, possibly exchanging the currently active ones (Authentication required).

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

change-pin
Change the value of the Open Platform Global PIN and set it's max. false retry limit (Authentication required).

unblock-pin
Unblock the Open Platform Global PIN (Authentication required).

set-key
Registers the secret key(s) with the CardManager plugin for use in the secure messaging executed during authentication. No interaction with card.

get-cplc
Get CardProductionLifeCycle information from the card (as defined in Open Platform).

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

Further Information

JCShell is mainly intended for developers who have a good knowledge about smart cards and also about the JavaCard and Open Platform standards. For more information on the low-level capabilities, e.g. scripting capabilities, or control language syntax, we suggest the reading of the companion document providing more details on these aspects.