GPSHELL(1)

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>