Man page of GPSHELL
GPSHELL
Section: User Manuals (1)
Updated: MARCH 2010
Index of this MAN page
Back To MAN Pages From BackTrack 5 R1 Master List
NAME
gpshell - command line tool for the management of GlobalPlatform compliant smart cards
SYNOPSIS
gpshell [
scriptfile
]
DESCRIPTION
gpshell
gpshell can manage applications on smart cards supporting the GlobalPlatform.
This comprises the installation and deletion of applications, getting the
applications status and card data. These appications are practical always Java Card applets.
Additional key management commands are provided.
The most common way to use gpshell is a scriptfile. But it is also possible to read the commands from stdin.
COMMANDS
- mode_201
-
Set protocol mode to OpenPlatform 2.0.1
- mode_211
-
Set protocol mode to GlobalPlatform 2.1.1
- visa_key_derivation
-
If you have a card which uses the VISA key derivation scheme for the key calculation,
like GemXpresso Pro or some JCOP cards you must set this.
- emv_cps11_key_derivation
-
If you have a card which uses the EMV CPS 1.1 key derivation scheme for the key calculation, like a Sm@rtCafe Expert 3.0 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.
- enable_timer
-
Enables the logging of the execution time of a command.
- establish_context
-
Establish context
- card_connect
-
-reader readerName
Connect to card in the reader with readerName
- card_connect
-
-readerNumber 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 -keyDerivation x
Open secure channel
For OpenPlatform 2.0.1' card only -keyind -keyver -mac_key and enc_key are necessary.
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.
If you have a card which uses key derivation you must enable the derivation mode with the -keyDerivation option and you must specify with -key the master (mother) key.
-kek_key, -mac_key and -enc_key are not relevant. See the section Options and Key derivation.
- select
-
-AID AID
Select AID instance
- install
-
-file appletFile -priv privilege -sdAID sdAID -AID AIDInPkg -pkgAID packageAID -instAID instanceAID -nvCodeLimit x -nvDataLimit x
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 x -sdAID sdAID -nvCodeLimit y
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.
You may need to use this command if the combined install command does not work.
- load
-
-file appletFile
Load applet
You may need to use this command if the combined install command does not work.
- install_for_install
-
-priv privilege -AID AIDInPkg -pkgAID pkgAID -instAID instanceAID -nvDataLimit x
Instantiate applet
You may need to use this command if the combined install command does not work. Or you want to install a preinstalled Security Domain.
- card_disconnect
-
Disconnect card
- get_status
-
-
-element e0
List applets and packages and security domains
-
-element 20
List packages
-
-element 40
List applets or security domains
-
-element 80
List Card Manager / Security Issuer Domain
- release_context
-
Release context
- put_sc_key
-
-keyver 0 -newkeyver 2 -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 1 -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
- put_dm_keys
-
-keyver 0 -newkeyver 2 -file public_rsa_key_file -pass password -key new_receipt_generation_key
Put delegated management keys for GP 2.1.1 in version 2
- put_dm_keys
-
-keyver 0 -newkeyver 2 -file public_rsa_key_file -pass password -key new_receipt_generation_key -cur_kek current_KEK_key
Put delegated management keys for OP 2.0.1' in version 2
- send_apdu
-
-sc 0 -APDU xxx
Send APDU xxx without secure channel
The APDU is given as hex without spaces and without leadings 0x.
- send_apdu_nostop
-
-sc 0 -APDU xxx
Does not stop in case of an error
The APDU is given as hex without spaces and without leadings 0x.
- get_data
-
-identifier identifier
A GET DATA command returning the data for the given identifier.
OPTIONS
- -keyind
-
x
Key index x
- -keyver
-
x
Key set version x
- -newkeyver
-
x
New key set version x
- -key
-
key
Key value in hex
- -mac_key
-
key
MAC key value in hex
- -enc_key
-
key
ENC key value in hex
- -kek_key
-
key
KEK key value in hex
- -security
-
x
0: clear, 1: MAC, 3: MAC+ENC
- -reader
-
readerName
Smart card reader name
- -readerNumber
-
x
Number of the reader in the system to connect to.
If -reader is given this is ignored.
- -protocol
-
x
Protocol, 0:T=0, 1:T=1
Should not be necessary to be stated explicitly.
- -AID
-
aid
Applet ID
- -sdAID
-
aid
Security Domain AID
- -pkgAID
-
aid
Package AID
- -instAID
-
aid
Instance AID
- -nvCodeLimit
-
x
Non-volatile code size limit
- -nvDataLimit
-
x
Non-volatile data size limit
- -vDataLimit
-
x
Volatile data size limit
- -file
-
name
File name
- -instParam
-
param
Installation parameter
- -element
-
x
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
-
x
Secure Channel mode (0 off, 1 on)
- -APDU
-
apdu
APDU to be sent. Must be in hex format, e.g. 80CA00CF00.
- -priv
-
x
Privilege. E.g. 0x04 Default Selected
- -scp
-
x
Secure Channel Protocol (1 SCP01, 2 SCP02, default no set).
Should not be necessary to be stated explicitly.
- -scpimpl
-
x
Secure Channel Implementation (default not set)
Should not be necessary to be stated explicitly.
- -pass
-
password
Password for key decryption
- -identifier
-
identifier
Identifer for the tag for the get_data command. Must be in hex format, e.g. 9F7F.
- -keyDerivation
-
derivation method
Possible values are "none", "visa2" or "emvcps11"
Choose "visa2" if you have a card which uses the VISA key derivation scheme for the key calculation, like GemXpresso Pro or some JCOP cards you must set this.
Choose "emvcps11" If you have a card which uses the EMV CPS 1.1 key derivation scheme for the key calculation, like a Sm@rtCafe Expert 3.0 you must set this.
ENVIRONMENT
- GLOBALPLATFORM_DEBUG
-
Enables debugging output from the underlying GlobalPlatform library.
- GLOBALPLATFORM_LOGFILE
-
Sets the log file name for the debugging output.
Key Derivation
- VISA2
-
For the VISA2 key derivation scheme, like used in a GemXpresso Pro or some JCOP cards, you have to enable it with the -keyDerivation set to "visa2" during open_sc.
- EMV CPS 1.1 / CDK (CPG 2.04)
-
For the key derivation according to EMV CPS 1.1 (CDK (CPG 2.04)), like Sm@rtCafe Expert 3.0, enable it by passing "emvcps11" to -keyDerivation during open_sc.
Known unsupported key derivation schemes are:
- CDK (CPG 2.02)
-
- ISK(D)
-
BUGS
- JCOP 10
-
install_for_load fails for unknown reason, so nothing can be installed.
AUTHOR
Karsten Ohme <k_o_@users.sourceforge.net>
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- COMMANDS
-
- OPTIONS
-
- ENVIRONMENT
-
- Key Derivation
-
- BUGS
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 07:34:21 GMT, September 13, 2011
Printable version of this article
