Getting started

Before you begin ...

Important

You really-really-really need to know the (I)SD keys of your card ...

Installing

GlobalPlatformPro requires Java and a smart card reader (PC/SC).

Tip

🍺 Homebrew users can install the latest gp command from the master branch of GitHub with

brew install martinpaljak/brew/gppro --HEAD # installs the master branch

Java

JDK 11 LTS or later is required (for JavaCard development, see JavaCard SDK and JDK version compatibility).

Temurin and Zulu are used and recommended. When installing the JDK on Windows and you want to use the packaged .exe, be sure to select the installation option JavaSoft (Oracle) registry keys or the .exe will not be able to find the JRE!

GPPro is distributed as a self-contained JAR file, to be executed with java -jar gp.jar. On Windows, gp.exe is equivalent to java -jar gp.jar.

Tip

On Linux/macOS it is easier to add an alias for your shell, like this:

alias gp="java -jar $PWD/gp.jar"

Now you can avoid typing java -jar gp.jar and gp works from any folder.

Note

All invocation methods are equivalent and shorthanded as gp in samples and documentation!

Choosing the reader

Most users have only a single smart card reader connected to the system at a time. Some people have several readers visible on the PC/SC layer: an embedded 3G/4G modem which exposes its SIM slot as a reader, always connected Yubikey, virtual readers created by SDK-s, or an embedded reader in a laptop that is not suitable for some operations. GlobalPlatformPro allows to fine tune the default reader via environment variables.

Tip

For a non-conclusive list of tested contactless readers check out this nfc4pc wiki page: Supported Readers

To manually select the reader, specify it as an argument to -r / --reader. To list available readers, run gp -r without an argument.

$GP_READER

If you know that you would always want to use a specific reader with GPPro, specify the name of it in $GP_READER. It will always be chosen if available.

$ export GP_READER="ACS ACR122U PICC Interface"

$GP_READER_IGNORE

To always ignore certain readers with GPPro, specify fragments of their names in $GP_READER_IGNORE, separated by semicolon(s). With the example below the built-in reader and always connected Yubikey will be ignored and a connected external USB reader will be used, no matter its name.

$ export GP_READER_IGNORE="Yubikey;Alcor"

Tip

Instead of the full reader name, you can always use a case-insensitive substring of the reader name, for as long as it uniquely identifies a single reader in the reader list.

Debugging tips

By default, GlobalPlatformPro tries to tell you only relevant information about the operation at hand, and be relatively silent.

• To make it more verbose about the protocol and what is parsed to/from APDU-s, add -v / --verbose to the command.
• To see even more information, including the full APDU communication, add -d / --debug to the command
• To see the trace logging of GlobalPlatformPro with all the noisy details, set the $GP_TRACE variable to true:

$ export GP_TRACE=true

It is not uncommon to run all commands by starting with gp -dv ..., especially when starting to work with new cards.

Head to Support & questions if you get stuck and need help.