******************************************************
Title : Global Platform Shell (gpshell)
Authors : snitmo@gmail.com
Karsten Ohme <k_o_@users.sourceforge.net>
License : See file COPYING
Requires : GlobalPlatform http://sourceforge.net/projects/globalplatform/
PC/SC Lite http://www.musclecard.com/ (for UNIXes)
OpenSSL http://www.openssl.org/
zlib http://www.zlib.net/
******************************************************
Version 1.1.1 9/24/2005
Version 1.3.0 02/09/2006
Version 1.3.1 3/24/2006
Version 1.4.0 12/28/2006
Version 1.4.1 08/22/2007
Version 1.4.2 01/20/2008
*** Summary
GPShell is a script interpreter which talks to a smart card. It is written on top of the GlobalPlatform library, which was developed by Karsten Ohme. It uses smart card communication protocols ISO-7816-4 and OpenPlatform 2.0.1 and GlobalPlatform 2.1.1. It can establish a secure channel with a smart card, load, instantiate, delete, list applets on a smart card.
You need also the libraries GlobalPlatform 4.3.2, zlib 1.2.3 (zlib1.dll) and OpenSSL 0.97e (libeay32.dll and ssleay32.dll) or compatible and must place them in the directory where GPShell is called or better the system directory (C:\Windows\System32 or /usr/(local/)lib usually).
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
PLEASE OBEY THAT EVERY CARD GETS LOCKED AFTER A FEW (USUALLY 10) UNSUCCESSFUL MUTUAL AUTHENTICATIONS. THE CONTENTS OF A LOCKED CARD CANNOT BE MANAGED ANYMORE (DELETED, INSTALLED)!!! IF YOU EXPERIENCE SOME UNSUCCESSFUL MUTUAL AUTHENTICATION ATTEMPS FIRST EXECUTE A SUCCESSFUL MUTUAL AUTHENTICATION WITH A KNOWN WORKING PROGRAM TO RESET THE RETRY COUNTER BEFORE YOU PROCEED WITH GPSHELL. CHECK THE PARAMETERS FOR MUTUAL AUTHENTICATION (KEYS, SECURITY PROTOCOL) AND ASK IF ANYBODY KNOWS IF THE CARD IS SUPPORTED.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
*** Usage
Make sure both GPShell.exe (or gpshell on UNIX) and GlobalPlatform.dll (or .so) are in your PATH.
UNIX:
gpshell scriptfile, or
gpshell < scriptfile
Win32:
GPShell.exe scriptfile, or
GPShell.exe < scriptfile
gpshell can take a script file from standard input, as well as from a file. This way, an application can feed commands to gpshell without creating a script file.
*** Scriptfile Commands
mode_201 // Set protocol mode to OpenPlatform 2.0.1
---
mode_211 // Set protocol mode to GlobalPlatform 2.1.1
---
gemXpressoPro // If you have a GemXpresso Pro card you must set this.
---
enable_trace // Enable APDU trace
You will see the sent APDUs in clear text. The last two bytes of the
reponse are the response code. A reponse code of 9000 means success,
otherwise the response code indicates an error. This may be OK when
deleting a non existing applet or package.
---
establish_context // Establish context
---
card_connect -reader [Reader Name] // Connect to card in the reader
card_connect -readerNumber [Reader Number x] // Connect to card in the
xth reader in the system
---
open_sc -keyind x -keyver x -key xyz -mac_key xyz -enc_key xyz -kek_key xyz -security x -scp x -scpimpl x // Open secure channel
For OpenPlatform 2.0.1' card only -keyind -keyver -mac_key and enc_key are necessary.
If you have an GemXpresso Pro card set gemXpressoPro and you MUST specify with -key the master (mother) key. -mac_key and -enc_key are not relevant.
For GlobalPlatform 2.1.1 cards -scp and -scpimpl should be not necessary to supply. You must also specify -kek_key. If your card supports a Secure Channel Protocol Implementation with only one base key, specify this key with -key and omit the others.
---
select -f AID // select applet instance
---
install -file appletfile -priv privilege -sdAID zzz -AID AID_in_pkg -pkgAID package_AID -instAID instanceAID -nvCodeLimit yyy -nvDataLimit xxx // Load and installs in one step
The parameters -AID -instAID -pkgAID -nvCodeLimit can be detected automatically and the -AID and -instAID is set to the first applet in appletfile.
for the sdAID the AID selected with the select command is chosen if not given. Otherwise the default Card Manager / Security Issuer Domain AID is chosen. So usually you do not have to pass it.
---
install_for_load -pkgAID xxx -sdAID zzz -nvCodeLimit yyy // Install for Load
for the sdAID the AID selected with the select command is chosen if not given. Otherwise the default Card Manager / Security Issuer Domain AID is chosen. So usually you do not have to pass it.
---
load -file appletfile // Load applet
---
install_for_install -priv privilege -AID AID_in_pkg -pkgAID package_AID -instAID instanceAID -nvDataLimit xxx // Instantiate applet
---
card_disconnect // Disconnect card
---
get_status -element e0 // list applets
---
release_context // Release context
---
put_sc_key -keyver 0 -newkeyver 0 -mac_key $new_MAC_key -enc_key $new_ENC_key -kek_key $new_KEK_key -cur_kek $current_KEK_key // add new key set version 2
put_sc_key -keyver 1 -newkeyver 0 -mac_key $new_MAC_key -enc_key $new_ENC_key -kek_key $new_KEK_key -cur_kek $current_KEK_key // replace key set version 1
---
send_apdu -sc 0 -APDU xxx // Send APDU xxx without secure channel
send_apdu_nostop -sc 0 -APDU xxx // Does not stop in case of an error
---
Options:
-keyind Key index
-keyver Key set version
-newkeyver New key set version
-key Key value in hex
-mac_key MAC key value in hex
-enc_key ENC key value in hex
-kek_key KEK key value in hex
-security 0: clear, 1: MAC, 3: MAC+ENC
-reader Smart card reader name
-readerNumber Number of the reader in the system to connect to.
If -reader is given this is ignored.
-protocol Protocol, 0:T=0, 1:T=1
Should not be necessary to be stated explicitly.
-AID Applet ID
-sdAID Security Domain AID
-pkgAID Package AID
-instAID Instance AID
-nvCodeLimit Non-volatile code size limit
-nvDataLimit Non-volatile data size limit
-vDataLimit Volatile data size limit
-file File name
-instParam Installation parameter
-element Element type to be listed in hex
80 - Card Manager / Card Issuer Security Domain only.
40 - Applications (and Security Domains only in GP211).
20 - Executable Load Files only.
10 - Executable Load Files and their Executable Modules only (Only
GP211)
-sc Secure Channel mode (0 off, 1 on)
-APDU APDU to be sent
-priv (DWORD) Privilege. // e.g. 0x04 Default Selected
-scp Secure Channel Protocol (1 SCP01, 2 SCP02, default no set).
Should not be necessary to be stated explicitly.
-scpimpl Secure Channel Implementation (default not set)
Should not be necessary to be stated explicitly.
Parameters containing spaces, e.g. file names or reader names must be quoted in "".
*** Sample / Testing
Tested cards:
Oberthur CosmopoliC 32K (OP201)
CosmopoliC 64K V5.2 (GP211, SCP01, Impl05)
Axalto Cyberflex e-gate 32k
GemXpresso R3.2 E64
IBM JCOP v2.2 41 (GP211)
IBM JCOP 31 (36k)
Nokia 6131 NFC Phone (GP211)
Axalto Cyberflex Access 64k
Gemalto Generations Flexible
We have tested this with GlobalPlatform.dll and HelloWorld.cap (sample applet from JavaCard development kit 2.1.2). See helloInstall.txt, helloDelete.txt, and list.txt and the other script files (.txt) for samples. If a CAP file cannot be used, please see the later section (How to convert a .cap file into a .bin file).
GPShell.exe helloInstall.txt // install HelloWorld.cap
GPShell.exe helloDelete.txt // delete HelloWorld.cap
GPShell.exe list.txt // list applets on a smart card
Make sure the script file (helloInstall.txt, etc.) and applet file HelloWorld.cap are in your current directory.
It should work with other smart cards that support JavaCard 2.x.y and OpenPlatform 2.0.1 or GlobalPlatform 2.1.1. You need to tweak options in the script files. Please let us know how it works with the smart cards you have.
* About put_sc_key
We have tested put_sc_key with Oberthur CosmopoliC 64K card and Cyberflex Access e-gate 32K.
For Cyberflex example, please see:
replacekey-cflex.txt // Replace the default key set (key set version 1, value 404142...4f) with a new key (505152...5f)
putdefault-cflex.txt // Replace the new key (505152...5f) with the default key (404142...4f)
For CosmopoliC 64K, you need to add a key set first. See
replacekey-cosmo-gp211.txt. I have not tested this particular sample. Please use it as a sample.
This would add a key set 1, and at the same time delete the initialization key set. After the initialization key set is used, you can replace and add key sets as in Cyberflex.
* About install_for_load and install
For CosmopoliC 64K (tested on V5.2), you need to specify the Security Domain AID. For example,
install -file HelloWorld.cap -sdAID A000000003000000 -nvCodeLimit 4000
For GemXpresso R3.2 E64, you need to specify the Security Domain AID (Card Manager AID). For example,
install -file HelloWorld.cap -sdAID A000000018434D00 -nvCodeLimit 4000
* CyberFlex cards
For the Cyberflex you also need the CAP transformer (I believe this is
a kind of obfuscator) which you must apply to the CAP file. Download it
from http://www.trusted-logic.fr/down.php and use it. For Cyberflex
e-gate 32k the simple install command does not work. Unfortunately some
parameters are not accepted by the card. You must execute the single
steps:
install_for_load
load
install_for_install
See the sample file helloInstallCyberflexe-gate32k.txt.
*** How to convert a .cap file into a .ijc (.bin) file
JavaCard applets are in CAP files. For example, JavaCard Toolkit generates one. CAP files are the official container format for JavaCard applets and they should work with GPShell. This was tested successfully with all of the above cards. The actual load format which is used to bring the applet to the card is the IJC format. If this does not work here is an guide how to transform a CAP file into a IJC file. Sometimes for IJC files the extension .bin is used.
Fortunately, the conversion is straightforward.
Take the cap file, unjar it. This results in many smaller cap files. Concatenate all of them into one .bin file. Here's an example.
cp com/sun/javacard/samples/HelloWorld/javacard/HelloWorld.cap .
jar xvf HelloWorld.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Header.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Directory.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Applet.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Import.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/ConstantPool.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Class.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Method.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/StaticField.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/RefLocation.cap
extracted: com/sun/javacard/samples/HelloWorld/javacard/Descriptor.cap
cat com/sun/javacard/samples/HelloWorld/javacard/Header.cap
com/sun/javacard/samples/HelloWorld/javacard/Directory.cap
com/sun/javacard/samples/HelloWorld/javacard/Import.cap
com/sun/javacard/samples/HelloWorld/javacard/Applet.cap
com/sun/javacard/samples/HelloWorld/javacard/Class.cap
com/sun/javacard/samples/HelloWorld/javacard/Method.cap
com/sun/javacard/samples/HelloWorld/javacard/StaticField.cap
com/sun/javacard/samples/HelloWorld/javacard/ConstantPool.cap
com/sun/javacard/samples/HelloWorld/javacard/RefLocation.cap
com/sun/javacard/samples/HelloWorld/javacard/Descriptor.cap >
HelloWorld.bin
I have run this in cygwin. You can see I have opened up HelloWorld.cap and concatanated all the resulting .cap files into one file, HelloWorld.bin. Try the same thing to your .cap file, and please let us know if it doesn't work.
*** Contact
For more information contact the authors through the mailinglist at:
http://sourceforge.net/projects/globalplatform/
