| GPSHELL(1) | GPShell Documentation | GPSHELL(1) |
gpshell - command line tool for the management of GlobalPlatform compliant smart cards
gpshell scriptfile
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 applications are practical always Java Card applets. Additional key management commands are provided.
The most common way to use gpshell is a script file. But it is also possible to read the commands from stdin if no script file is provided.
Within a script environment variables can be accessed with the syntax ${ENV_VAR_NAME}.
Reading the commands from stdin allows one to feed in the commands dynamically and use conditionals when using the Expect (https://en.wikipedia.org/wiki/Expect) pattern. Tools are available for a variety of script languages, shells and programming languages. Example are to support environment variables and handle results and output conditionally.
There are several txt example scripts provided which gets installed into usr/local/share/docs or /home/linuxbrew/.linuxbrew/opt/globalplatform/share/doc/gpshell1/ or can be found online (https://github.com/kaoh/globalplatform/tree/master/gpshell).
You will see the sent APDUs in clear text. The last two bytes of the response are the response code. A response code of 9000 means success, otherwise the response code indicates an error. This may be OK when deleting a non existing applet or package.
For OpenPlatform 2.0.1’ cards only -keyind -keyver -mac_key and -enc_key are necessary.
For GlobalPlatform 2.1.1 and later cards -scp and -scpimpl should not be necessary to supply. You must also specify -kek_key.
If the card supports a Secure Channel Protocol Implementation with only one base key, specify this key with -key and omit the others.
If the card uses a key derivation mechanism 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 is this case. See the section Options and Key Derivation. NOTE: If the secure channel is going to be opened when no security domain is selected then the command get_secure_channel_protocol_details must be executed before to be able to get the Secure Channel Protocol Implementation.
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. Usually you do not have to pass it.
-instParam specifies applet installation parameters for the install() method -uiccSystemSpecParam specifies parameters according to ETSI TS 102 226, sect. 8.2.1.3.2.2 to use the Card Application Toolkit (CAT) functionality or to access the UICC file system. The parameters have to be already encoded without the outer tag `EA'. -simSpecParam specifies parameters according to ETSI TS 102 226, sect. 8.2.1.3.2.1 to use the SIM Application Toolkit (STK) functionality or to access the SIM file system. The parameters have to be already encoded without the outer tag `CA'.
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. Usually you do not have to pass it.
This command may be needed if the combined install command does not work.
This command may be needed if the combined install command does not work.
This command may be needed if the combined install command does not work. Or you want to install a pre-installed Security Domain.
This command may be needed if the combined install command does not work. Typically this is used after an install_for_install followed by personalization.
If a new key set version is to be added keyver must be set to 0. If keyver equals newkeyver an existing key version is replaced. An existing key set version cannot be replaced with a key set version using a different key size.
The APDU is given as hex without spaces and without leading 0x.
-keyver x Key set version x
There are several identifiers available but in general not all cards are supporting them. The GlobalPlatform specification v2.3.1 lists a few in section 11.3.3.1. It is useful to use some ASN.1 parser to interpret these data, like asn1js (https://lapo.it/asn1js)
Some useful identifier are:
You see the command trace of a GET DATA command and the interpreted result.
=> 80 CA 9F 7F 00 .....
(12102 usec)
<= 9F 7F 2A 47 90 50 40 47 91 81 02 31 00 83 58 00 ..*G.P@G...1..X.
11 68 91 45 81 48 12 83 65 00 00 00 00 01 2F 31 .h.E.H..e...../1
30 31 31 36 38 00 00 00 00 00 00 00 00 90 00 01168..........
Status: No Error
IC Fabricator : 4790
IC Type : 5040
Operating System ID : 4791
Operating System release date : 8102 (11.4.2008)
Operating System release level : 3100
IC Fabrication Date : 8358 (23.12.2008)
IC Serial Number : 00116891
IC Batch Identifier : 4581
IC Module Fabricator : 4812
IC Module Packaging Date : 8365 (30.12.2008)
ICC Manufacturer : 0000
IC Embedding Date : 0000
IC Pre-Personalizer : 012F
IC Pre-Perso. Equipment Date : 3130 (10.5.2003)
IC Pre-Perso. Equipment ID : 31313638
IC Personalizer : 0000
IC Personalization Date : 0000
IC Perso. Equipment ID : 00000000
Dates are stored as 2 bytes, the first specifying the year in the decade and the last 3 bytes the day within the year.
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 and later you must set this. Also for put_sc_key this is necessary for Sm@rtcafe 5.0 (and earlier(?)) cards
Known unsupported key derivation schemes are:
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
If you cannot authenticate to your card it might be not fused. In this case you need the transport key from the vendor. Execute the JCOP IDENTIFY command.
select -aid A000000167413000FF Offset 14 (decimal) of the response has the pre-personalized state. 00h means not fused (not personalized), 01h means fused.
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.
Some cards are not supporting the GET DATA command. This command is used by GPShell for retrieving the secure channel parameters. So you have to pass -scp 2 -scpimpl 0x15 to open_sc command.
Karsten Ohme k_o_@users.sourceforge.net Snit Mo snitmo@gmail.com
See the file AUTHORS for a complete list.
| 2.2.0 |