A Logo

Feel free to include my content in your page via my
RSS feed

Help Irongeek.com pay for
bandwidth and research equipment:

Subscribestar or Patreon

Search Irongeek.com:

Affiliates:
Irongeek Button
Social-engineer-training Button

Help Irongeek.com pay for bandwidth and research equipment:

paypalpixle


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

15 most recent posts on Irongeek.com:


If you would like to republish one of the articles from this site on your webpage or print journal please contact IronGeek.

Copyright 2020, IronGeek
Louisville / Kentuckiana Information Security Enthusiast