GPSHELL(1)

📦

version 2.4.2 · 7 versions

🎀 GPSHELL(1) 🎀

it's the gpshell page from the GPShell Documentation, bestie 💖 and yes it's long, so buckle up — this is part one of two, don't go anywhere 👑

🌸 NAME 🌸

gpshell — the command line tool for managing GlobalPlatform compliant smart cards 🃏✨

🦋 SYNOPSIS 🦋

gpshell scriptfile

✨ DESCRIPTION ✨

okay so gpshell can manage applications on smart cards that support the GlobalPlatform. we're talking installing and deleting applications, peeking at the applications' status, grabbing card data — the whole glow-up routine 🫶 these applications are, like, practically always Java Card applets no cap. and there are extra key management commands in the mix too 🔑

the most common way to run gpshell is honestly just with a script file 📜 but plot twist: if you don't hand it a script file, it'll read the commands straight from stdin instead. main character flexibility 💅

inside a script, your environment variables are reachable with the syntax ${ENV_VAR_NAME} — yes literally that.

reading commands from stdin lets you feed them in dynamically and use conditionals when you're working with the Expect pattern. tools exist for a whole bunch of script languages, shells and programming languages. the vibe? support environment variables, handle results and output conditionally. it's giving very versatile 🦋

there are several txt example scripts that ship with it — they get installed into /usr/share/doc/gpshell/examples/ and you can find them online too 🌈

💅 COMMANDS 💅

# — start a line with a comment 💬
// — also starts a line with a comment 💬
mode_201 — sets the protocol mode to OpenPlatform 2.0.1. this is the default, so if you say nothing, this is what you get ✨
mode_211 — sets the protocol mode to GlobalPlatform 2.1.1 and later 🚀
visa_key_derivation — for cards that use the VISA key derivation scheme for the key calculation — think GemXpresso Pro, Palmera Protect or some JCOP cards — you must set this 🔑
emv_cps11_key_derivation — for cards that use 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 — turns on the APDU trace 👀

you'll 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 ✨ anything else means an error. and ngl, that may be OK when you're deleting a non existing applet or package 🤷‍♀️

enable_timer — enables the logging of the execution times of commands ⏱️
establish_context — establishes context. this must always be executed before connecting to a card, no skips 🚨
list_readers — lists the card readers 📇
card_connect -reader readerName -protocol protocol — connect to the card in the reader with readerName. by default protocol is 0 = T0 🔌
card_connect -readerNumber x -protocol protocol — connect to the card in the x th reader in the system. by default protocol is 0 = T0 🔌
open_sc -keyind x -keyver x -key key -mac_key mac-key -enc_key enc-key -kek_key kek-key -security securityLevel -scp protocol -scpimpl impl -keyDerivation derivation — open a secure channel 🔐

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 in 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, so you're actually able to get the Secure Channel Protocol Implementation. no shortcuts bestie 😤

select -AID AID — select the AID instance 🎯
install -file appletFile -priv privilege -sdAID sdAID -AID AIDInPkg -pkgAID packageAID -instAID instanceAID -nvCodeLimit x -nvDataLimit y -instParam installationParams -uiccSystemSpecParam uiccSystemSpecParams -simSpecParam simSpecParams — loads and installs an applet in one step 📦✨

the parameters -AID -instAID -pkgAID -nvCodeLimit can be detected automatically, and -AID and -instAID get set to the first applet in appletfile.

for the sdAID, the AID selected with the select command is chosen if it's 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, for using 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. mind the tags, they're not optional 💅

install_for_load -pkgAID packageAID -sdAID sdAID -nvCodeLimit y — applet load preparation 🛠️

this command may be needed if the combined install command does not work. lowkey a rescue mission 😭

load -file appletFile — load applet 📥

this command may be needed if the combined install command does not work.

install_for_install -priv privilege -AID AIDInPkg -pkgAID pkgAID -instAID instanceAID -nvDataLimit x -instParam installationParams -uiccSystemSpecParam uiccSystemSpecParams -simSpecParam simSpecParams — instantiate applet 🌱

this command may be needed if the combined install command does not work. or if you want to install a pre-installed Security Domain 👑

install_for_make_selectable -priv privilege -instAID instanceAID — makes an installed applet instance selectable ✅

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.

card_disconnect — disconnect the card 👋
get_status -element e0 — list applets and packages and security domains 📋
get_status -element 20 — list packages 📦
get_status -element 40 — list applets or security domains 🗂️
get_status -element 80 — list Card Manager / Security Issuer Domain 👑
release_context — release context 🫳
put_sc_key -keyver keyver -newkeyver newkeyver -mac_key new_MAC_key -enc_key new_ENC_key -kek_key new_KEK_key — add or replace a key set version 🔑🔁

if a new key set version is to be added, keyver must be set to 0. if keyver equals newkeyver, an existing key version gets replaced. heads up: an existing key set version cannot be replaced with a key set version using a different key size 🚫

put_sc_key -keyver keyver -newkeyver newkeyver -key key -keyDerivation “derivation” — replace key set version keyver using key derivation derivation using the master (mother) key 🔑
put_dm_keys -keyver keyver -newkeyver newkeyver -file public_rsa_key_file -pass password -key new_receipt_generation_key — add a RSA delegated management key in version newkeyver 🔐
send_apdu -sc 0 -APDU apdu — send APDU apdu without a secure channel 📤

the APDU is given as hex without spaces and without a leading 0x.

send_apdu_nostop -sc 0 -APDU apdu — same as send_apdu but it does not stop in case of connection or GlobalPlatform errors 🚨

the APDU is given as hex without spaces and without a leading 0x.

get_data -identifier identifier — a GET DATA command returning the data for the given identifier. see the identifier options for details 👀
get_key_information_templates -keyTemplate index — a GET DATA command returning the key information templates in the selected security domain 🗝️

⚠️ NOTE: the security domain must be selected, and this only works outside of a secure channel.

get_extended_card_resources_information — a GET DATA command returning the extended card resources information in the issuer security domain 📊

⚠️ NOTE: the security domain must be selected, and this only works outside of a secure channel.

get_secure_channel_protocol_details — a GET DATA command returning the secure channel protocol details and remembering them for a later open_sc 🧠✨

⚠️ NOTE: the security domain must be selected, and this only works outside of a secure channel.

print — prints a line of text. prints an empty line if no text is given 📝
install_for_personalization -aid AID — prepare a security domain for the personalization of an applet with the following store_data commands 🎨

⚠️ NOTE: the security domain must be selected, and this only works outside of a secure channel.

store_data -dataFormat format -dataEncryption encryption -data data — executes a STORE DATA command passing the data to the selected applet 📮
get_card_recognition_data — a GET DATA command returning the card recognition data 🪪

⚠️ NOTE: the security domain must be selected.

delete -AID aid — deletes an applet or package with the specified AID 🗑️
delete_key -keyver keyver -keyind keyind — deletes a key set version with a DELETE command ✂️🔑

if only the keyver is passed, the complete key set version is deleted. by default keyind is 0xFF, which deletes the complete key set version. if keyver is 0, all key sets with the passed keyind are deleted.

gemXpressoPro — enables support for GemXPresso cards, which enables the visa2 key derivation mode 💎
exit — exit the shell. useful in interactive mode 🚪👋

okay that's the first chunk bestie, keep scrolling, there's more 💖

✨ OPTIONS ✨

okay bestie, deep breath, this is the big list — every single flag, no skipping, we're getting through all of it 💪

-keyind x — key index x, go off
-keyver x — key set version x
-newkeyver x — new key set version x
-key key — the 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 — the security level, and here are the takes: 0: clear, 1: MAC, 3: MAC+ENC, 51: MAC+ENC+R-MAC+E-ENC (SCP03 only), 19: MAC+ENC-R-MAC (SCP02+SCP03 only), 17: MAC+R-MAC (SCP02+SCP03 only)
-reader readerName — the smart card reader's name
-readerNumber x — which reader in the system to connect to, by number. Lowkey if -reader is given, this gets ignored entirely
-protocol x — the protocol: 0:T=0, 1:T=1. Ngl you probably shouldn't have to state this 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
-uiccSystemSpecParam param — UICC System Specific Parameters, per ETSI TS 102 226, sect. 8.2.1.3.2.2.
-simSpecParam param — SIM File Access and Toolkit Application Specific Parameters, per ETSI TS 102 226, sect. 8.2.1.3.2.1.
-element x — which element type to list, in hex 🌸
- 80 - Card Manager / Card Issuer Security Domain only.
- 40 - Applications (and Security Domains only in GP211 and later).
- 20 - Executable Load Files only.
- 10 - Executable Load Files and their Executable Modules only (Only GP211 and later)
-format x — sets the format of the response from the get_status command. This one is only for GlobalPlatform cards, and it's required, and you only need it if the default isn't supported by the smart card. Three conditions, bestie, it's giving ✨diva✨
-dataFormat x — sets the data format flag for the store_data command. Default 0.
- 0 - No general encryption information or non - encrypted data
- 0x20 - Application dependent encryption of the data
- 0x40 - RFU(encryption indicator)
- 0x60 - Encrypted data. Must be encrypted with data encryption key.
-dataEncryption x — sets the encryption format flag for the store_data command. Heads up bestie: this is just a flag and the data must already be passed in the correct encryption. Default 0.
- 0 - No general data structure information
- 0x08 - DGI format of the command data field
- 0x10 - BER-TLV format of the command data field
- 0x18 - RFU (data structure information)
-responseDataExpected x — sets whether response data is expected for the store_data command. 1 = yes, expecting response data. Default 0.
-keyTemplate x — sets the key template index to return for the get_key_templates command. Default 0.
- 0 - Deprecated format
- 2 - New format (default)
-sc x — Secure Channel mode (0 off, 1 on)
-APDU apdu — the APDU to send. Has to be in hex format, e.g. 80CA00CF00.
-priv x — Privilege. E.g. 0x04 Default Selected
-scp x — Secure Channel Protocol (1 SCP01, 2 SCP02, 3 SCP03, default: no set). Should not be necessary to state explicitly.
-scpimpl x — Secure Channel Implementation (default: not set). Should not be necessary to state explicitly. Peep the get_secure_channel_protocol_details command to detect the Secure Channel Protocol Implementation. NOTE: the value can be passed as a decimal value or as hex prefixed by 0x. The hexadecimal version is the common one.
-pass password — password for key decryption
-identifier identifier — the identifier for the tag for the get_data command. Must be in hex format, e.g. 9F7F.

There are several identifiers available, but in general not all cards support them (rude of them tbh). The GlobalPlatform specification v2.3.1 lists a few in section 11.3.3.1. It's useful to use some ASN.1 parser to interpret these data, like asn1js 👍

Some useful identifiers are:

9F7F - CPLC (Card Production Life Cycle) Data
00E0 - Key Information Templates. Instead of the first byte 00, 01, ... can also be used to get more key information templates if available. There's a dedicated command for getting this: get_key_information_templates
2F00 - List of applications
FF21 - Extended card resources. There's a dedicated command for getting this: get_extended_card_resources_information
0066 - Card Recogniti0on Data. There's a dedicated command for getting this: get_card_recognition_data
-data data — data in hex format for the store_data command.
-noStop — does not stop when there's an error. Iconic, honestly.
-keyType keyType — the type of the key for the put_sc_key command. Must be in hex format, e.g. 88.

💾 Format of CPLC data

Here you can see the command trace of a GET DATA command plus the interpreted result, and it's lowkey so satisfying to watch ngl:

=> 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 one specifies the year in the decade, and the last 3 bytes are the day within the year. Little time capsule moment 🕰️

-keyDerivation derivation method — the possible values are none, visa1, visa2 or emvcps11

Choose visa2 if you have a card that 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 that 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.

visa1 is an old VISA key derivation scheme and is only needed for older cards. Vintage behaviour, we respect it. 🫶

🌱 ENVIRONMENT

GLOBALPLATFORM_DEBUG — enables debugging output from the underlying GlobalPlatform library. Turn it on when you want the tea ☕
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.

emvcps11

For the key derivation according to EMV CPS 1.1 (CDK (CPG 2.04)), like Sm@rtCafe Expert 3.0 and later.

Known unsupported key derivation schemes are:

CDK (CPG 2.02)
ISK(D)

🎀 Supported Cards

bestie look at this roster, it's giving history museum of smart cards 🏛️✨

Gemalto IDCore 3010
Oberthur CosmopoliC 32K (OP201)
CosmopoliC 64K V5.2 (GP211, SCP01, Impl05)
Axalto Cyberflex e-gate 32k (OP201)
GemXpresso R3.2 E64
IBM JCOP v2.2 41 (GP211)
IBM JCOP 31 (36k)
Palmera Protect V5
JTopV15
Nokia 6131 NFC Phone (GP211)
Axalto Cyberflex Access 64k
Gemalto Generations Flexible
Sm@rtCafe Expert 3.0
Tongfang420
Infineon SECORA™ ID S
JCOP4 P71
JCPO3 P60 EMV
JCOP3 P60 SecID CS
JCOP3 P40 EMV
JCOP3 P40 SecID
JCOP2.4.x

🧰 Misc

🛠️ 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 also need to specify the Security Domain AID (Card Manager AID). For example,

install -file helloworld.cap -sdAID A000000018434D00 -nvCodeLimit 4000

🔐 JCOP cards

If you cannot authenticate to your card, it might not be fused. In this case you need the transport key from the vendor (yeah, you gotta go ask, no shortcut 💀). 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.

🦋 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.

💀 BUGS

JCOP 10

install_for_load fails for unknown reason, so nothing can be installed. Not me crying about 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 the open_sc command.

👑 AUTHOR

Karsten Ohme k_o_@users.sourceforge.net — Snit Mo snitmo@gmail.com

See the file AUTHORS for a complete list.

and that's the whole page, bestie, we ate and left no crumbs 🍓 this was the GPSHELL(1) manual, version 2.4.0 — stan the karsten, go touch some smart cards, mwah 💖🎀✨

📦 where this page comes from

ubuntu stonking: gpshell 2.4.2+dfsg-2build1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

GPSHELL(1)

🎀 GPSHELL(1) 🎀

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

✨ DESCRIPTION ✨

💅 COMMANDS 💅

✨ OPTIONS ✨

💾 Format of CPLC data

🌱 ENVIRONMENT

🗝️ Key Derivation

🎀 Supported Cards

🧰 Misc

🛠️ About install_for_load and install

🔐 JCOP cards

🦋 CyberFlex cards

💀 BUGS

👑 AUTHOR

🛠️ About `install_for_load` and `install`