GlobalPlatform Pro (GPPro) Guide

GlobalPlatform Pro (GPPro) Guide

GlobalPlatform Pro (gp.jar, commonly called GPPro) is the de facto open-source command-line tool for managing GlobalPlatform-compliant smart cards. Written in Java, it handles Security Domain authentication, applet installation, key management, and card content audit — tasks that would otherwise require writing low-level APDU sequences by hand.

GPPro is available at github.com/martinpaljak/GlobalPlatformPro under the LGPL license.

Installation

# Download latest release jar
curl -LO https://github.com/martinpaljak/GlobalPlatformPro/releases/latest/download/gp.jar
# Verify Java 11+
java -version
# List connected readers and cards
java -jar gp.jar --list

Connecting to a Card

GPPro connects via PC/SC. By default it targets the first available reader:

java -jar gp.jar --list            # show readers and card ATR
java -jar gp.jar --reader "ACS"    # select reader by substring match
java -jar gp.jar --list --debug    # APDU trace

Before any card management operation, GPPro must authenticate to the card's Issuer Security Domain (ISD) using the Card Manager keys.

Default Test Keys

Most development cards ship with well-known test keys:

Never use default keys on production cards. GPPro will warn if default keys are in use.

Listing Card Content

java -jar gp.jar --list
# Output:
# ISD: A000000003000000 (OP_READY)
# PKG: D276000085010100 v1.0 (LOADED)
#   APP: D27600008501010001 (SELECTABLE)

The output shows all Security Domains, loaded packages, and installed applets with their AIDs and lifecycle states.

Installing an Applet

java -jar gp.jar --install MyApplet.cap
# GPPro performs:
# 1. INSTALL [for load] — allocate EEPROM for package
# 2. LOAD — split .cap into LOAD blocks, transmit each
# 3. INSTALL [for install] — instantiate the applet

With explicit AID control:

java -jar gp.jar \
  --install MyApplet.cap \
  --package D276000001 \
  --applet D27600000101 \
  --create D27600000101 \
  --params 01020304   # install parameters (hex)

Applet Lifecycle Management

Delete order matters: delete the applet instance before deleting the package. A package with active instances cannot be deleted.

Key Management with SCP03

For production deployments using SCP03 (AES-based Secure Channel Protocol), GPPro supports key rotation:

# Change Card Manager keys to new AES-128 keys
java -jar gp.jar \
  --key-enc 404142434445464748494A4B4C4D4E4F \
  --key-mac 404142434445464748494A4B4C4D4E4F \
  --key-kek 404142434445464748494A4B4C4D4E4F \
  --put-key \
  --new-key-enc AABBCCDDEEFF00112233445566778899 \
  --new-key-mac AABBCCDDEEFF00112233445566778899 \
  --new-key-kek AABBCCDDEEFF00112233445566778899

After key rotation, all subsequent commands must use the new keys. Losing the production keys permanently locks the card — maintain a key escrow in an HSM.

Supplementary Security Domains (SSD)

An SSD provides an isolated key hierarchy for a specific service provider, independent of the Card Manager:

# Create an SSD
java -jar gp.jar --create-sd --sdaid A00000000101 --privileges SecurityDomain
# Install applet under the SSD
java -jar gp.jar --install MyApplet.cap --sd A00000000101

The SSD model is central to GlobalPlatform multi-tenancy — different service providers load their own applets into their own SSDs without access to each other's content.

See the Smart Card Debugging Guide for APDU-level troubleshooting, and the JCOP Development Guide for NXP-specific tooling that integrates with GPPro workflows.