Global Platform GUI

A cross-platform GUI wrapper for Global Platform Pro by Martin Paljak, geared towards the flexSecure.

Tons of credit go to @Stargate01, @GrimEcho, and @pilgrimsmaster.

Looking for more information? Check out the flexSecure repo docs.

Caution

Disclaimer: Use at your own risk. I'm not liable for bricked chips.

The risk is no greater than using Global Platform Pro. During every call to gp, this app checks its config to see if the smart card scanned: A, has been scanned before, and B, has a default key. If either condition is false, it bails. However, if you give it an incorrect key, it will send it. Enough consecutive, incorrect key entries will brick your device.

Note

If you do accidentally enter an invalid key, entering the correct key will reset the counter.

Features

• Supports non-default master keys
• Supports changing master keys
• Can store keys securely--or not
• Decodes AIDs to names of flexSecure apps
• Displays descriptions of apps (where provided)
• Reports available memory (if app is installed)
• Installs the latest version of an app
• Can uninstall apps
• YAML Plugin System - Create custom plugins declaratively or with the visual designer wizard
  • Define applet sources (GitHub releases, HTTP, local files)
  • Visual 10-page plugin designer wizard for point-and-click plugin creation
  • Custom management actions, multi-step workflows, and menu items
  • Parameter encoding (template, TLV, or custom Python script)
  • Auto-discovery: Repos with gp-plugin.yaml are automatically detected
• Supports NDEF Installation
  • Container Size
  • Permissions
  • Initial Record (Text and URI)
• Secure Storage Backup & Restore
  • Export encrypted backups with password or GPG encryption
  • Import backups with conflict resolution
  • Change encryption method (System Keyring or GPG)
• VivoKey Apex / Fidesmo Support
  • Auto-detection of Fidesmo-based devices
  • Browse and install apps from the Fidesmo store
  • Install custom CAP files via FDSM (with Fidesmo auth token)
  • Manage installed applets (list, uninstall)

Quick Start

Binary

Check the latest release for pre-built binaries:

• Linux: AppImage
• Windows: Portable executable
• macOS: DMG with signed app bundle

From Source

Requirements:

• Python 3.9+ (Linux/macOS)
• Python 3.9 only (Windows) - PyQt5 wheels for Windows require Python 3.9
• Java 8+ (for GlobalPlatformPro), Java 21+ (for Fidesmo/FDSM support)

Important

Windows users: You must use Python 3.9 and requirements-win.txt. The main requirements.txt contains Linux-only packages (SecretStorage, jeepney) that will fail to install on Windows.

# Clone the repository
git clone https://github.com/DangerousThings/global-platform-gui.git
cd global-platform-gui

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate        # Linux/macOS
venv\Scripts\activate           # Windows

# Install dependencies
pip install -r requirements.txt          # Linux/macOS
pip install -r requirements-win.txt      # Windows (Python 3.9)

# Run
python main.py

Building

A Makefile is provided for building on all platforms:

# Show all build options
make help

# Build for current platform
make all

# Platform-specific builds
make linux          # Linux AppImage
make linux-signed   # Linux AppImage with GPG signature
make macos          # macOS .app bundle + DMG
make macos-signed   # macOS with GPG signature
make windows        # Windows executable (requires Python 3.9)

Signing

Builds can be signed for distribution:

# GPG signing (all platforms, works with hardware tokens)
GPG_KEY=your-key-id make linux-signed

# macOS code signing + notarization
CODESIGN_IDENTITY="Developer ID Application: Name (TEAMID)" make macos-signed

# Windows Authenticode (run on Windows)
set SIGNTOOL_CERT=path\to\cert.pfx
set SIGNTOOL_PASSWORD=password
build_scripts\windows\build_windows.bat

Development

# Install dev dependencies
make dev

# Run tests
make test

# Format code
make format

# Check code style
make lint

For CAP File Providers

If you host JavaCard applets (CAP files), you can provide a plugin definition that users can automatically import. Add a gp-plugin.yaml file to your repository root:

schema_version: "1.0"

plugin:
  name: my-applet
  description: Description of what the applet does
  version: "1.0.0"
  author: Your Name

applet:
  source:
    type: github_release
    owner: your-username
    repo: your-repo
    asset_pattern: "*.cap"  # Pattern to match CAP files in releases

  metadata:
    name: My Applet
    aid: D276000085304A434F9001  # Applet AID
    storage:
      persistent: 10000  # Bytes of persistent memory required

# Optional: Custom installation UI
install_ui:
  form:
    fields:
      - id: pin
        label: "Initial PIN"
        type: text
        validation:
          pattern: "^[0-9]{4,8}$"
          message: "PIN must be 4-8 digits"

# Optional: How form values become install params
parameters:
  encoding: template
  template: "{pin_hex}"

# Optional: Management actions for installed applet
management_ui:
  actions:
    - id: change_pin
      label: "Change PIN"
      dialog:
        fields:
          - id: old_pin
            type: password
            label: "Current PIN"
          - id: new_pin
            type: password
            label: "New PIN"
      apdu_sequence:
        - apdu: "0020008204{old_pin_hex}"
          description: "Verifying current PIN..."
        - apdu: "0024008204{new_pin_hex}"
          description: "Setting new PIN..."

When users point Global Platform GUI at your repository, it will detect the plugin definition and offer to import it automatically.

Supported locations:

• gp-plugin.yaml or .gp-plugin.yaml in repo root
• *.gp-plugin.yaml in GitHub release assets

Secure Storage

Global Platform GUI stores card keys securely using AES-256-GCM encryption. Keys are protected using either your system's keyring or a GPG key.

Encryption Methods

• System Keyring (recommended): Uses your operating system's credential manager (GNOME Keyring, macOS Keychain, Windows Credential Manager)
• GPG: Uses a GPG key for encryption, allowing hardware token integration (YubiKey, etc.)

Backup & Restore

You can create encrypted backups of your stored keys from Settings → Storage → Backup & Restore:

Export Backup:

1. Click "Export Backup..."
2. Choose encryption method:
   • Password: Encrypt with a password you choose (PBKDF2-SHA256 with 600,000 iterations)
   • GPG Key: Encrypt with a GPG public key
3. Choose save location (.gpbackup file)

Import Backup:

1. Click "Import Backup..."
2. Select the backup file
3. Enter password (if password-protected) or confirm GPG decryption
4. Resolve any conflicts (keep existing, use backup, or skip)

Changing Encryption Method

To switch between System Keyring and GPG encryption:

1. Go to Settings → Storage
2. Click "Change Encryption Method..."
3. Select the new method and configure (GPG key ID if needed)
4. Confirm the change

Note

Changing the encryption method re-encrypts all stored data. Make sure you have a backup first.

VivoKey Apex / Fidesmo Devices

Global Platform GUI supports Fidesmo-based devices like the VivoKey Apex using FDSM instead of GlobalPlatform Pro.

How Detection Works

When a card is presented, the app reads the JavaCard memory applet and compares the persistent_total value against a known Fidesmo fingerprint. If it matches, a confirmation dialog asks whether to enable Fidesmo mode.

Once confirmed, the card is remembered and will automatically enter Fidesmo mode on future scans.

Warning

Auto-detection relies on a specific memory value (persistent_total = 84336). If your device has a different memory profile (e.g., after significant applet installation), detection may not trigger automatically. Use the manual override described below.

Manual Override

If auto-detection does not recognize your Fidesmo device, you can manually enable Fidesmo mode:

1. When prompted for a key, type FIDESMO (not a hex key)
2. Confirm the Fidesmo mode dialog
3. The app will remember this card for future use

Requirements

• Java 21+ is required for FDSM (GlobalPlatform Pro works with Java 8+)
• fdsm.jar must be present in the application directory
• A Fidesmo auth token is required to install or uninstall apps (configure in Settings > Fidesmo)
• Browsing the Fidesmo store and listing installed apps works without authentication

Fidesmo Store + GP Plugins

When a Fidesmo auth token is configured, the available apps list shows both Fidesmo store apps and standard GP plugins (label: "Fidesmo Apps+"). Without a token, only Fidesmo store apps are shown (label: "Fidesmo Apps"). GP plugins can be installed on Fidesmo devices via FDSM's --install command, which uploads the CAP file to the Fidesmo backend for installation.

Known Issues

• No real validation for URI record creation

Roadmap

• Encrypted NDEF records
• Multiple NDEF records
• MIME records
• VivoKey Apex / Fidesmo support
• CAP file caching
• Export/backup of app config and secure storage
• YAML-based extensible plugin system
• Visual plugin designer wizard