gpg-card

Manage GPG keys on a smart card

TLDR

Start in interactive mode

$ gpg-card

Invoke one or more commands non-interactively

$ gpg-card [command1] -- [command2] -- [command3]

Show information about a smart card

$ gpg-card list

Retrieve the public key using the URL stored on an OpenPGP card

$ gpg-card fetch

Set the URL used by the fetch command

$ gpg-card url

Change or unblock PINs (uses the default action for the card in non-interactive mode)

$ gpg-card passwd

Toggle the forcesig flag of an OpenPGP card (i.e. require entering the user PIN for signing)

$ gpg-card forcesig

Factory reset a smart card (i.e. delete all data and reset PINs)

$ gpg-card factory-reset

-h, --help
    Displays a help message with available options and exits.

--status
    Shows the current status and detailed information of the OpenPGP smart card, including card serial number, key IDs, application details, and remaining PIN tries.

--list
    Lists the cryptographic keys (Signature, Encryption, Authentication) currently stored on the smart card, along with their key IDs and capabilities.

--change-pin [user|admin|reset]
    Allows changing the specified PIN: the user PIN (for daily operations), the admin PIN (for administrative tasks), or the reset code (to unblock a locked user PIN).

--admin
    Enters administrative mode, enabling access to advanced card management functions and configuration. This operation typically requires the Admin PIN.

--import
    Imports existing GnuPG keys from the local keyring onto the smart card. This process securely transfers the private key material to the hardware token.

--export
    Exports public keys from the smart card. In some cases, it can prepare private keys for secure export, depending on card capabilities and security policy.

--gen-key
    Generates new cryptographic keys (Signature, Encryption, Authentication) directly on the smart card. The private keys are created and stored exclusively on the card, never leaving the hardware, which offers maximum security.

--factory-reset
    Performs a destructive factory reset of the smart card, which permanently erases all data, keys, and configurations on the card. Use with extreme caution! This action is irreversible.

--send-apdu APDU
    Sends a raw Application Protocol Data Unit (APDU) command directly to the smart card. This option is intended for advanced users, diagnostics, and debugging purposes.

--fingerprint FINGERPRINT
    Specifies the full fingerprint of a particular key to operate on, which is useful when dealing with multiple keys or for specific key management operations.

--card-no NUMBER
    Selects a specific smart card by its serial number if multiple smart card readers or cards are detected, allowing precise control over which card to interact with.

DESCRIPTION

gpg-card is a command-line utility within the GnuPG suite designed to interact with and manage OpenPGP smart cards. It acts as a user-friendly interface to scdaemon, the smart card daemon, enabling users to view card status, manage PINs (User, Admin, Reset Code), import or generate cryptographic keys directly on the card, and perform administrative tasks such as resetting the card to factory defaults. This tool is essential for users leveraging hardware security modules to protect their GnuPG keys and enhance their cryptographic operations, providing a robust layer of security for digital signatures and encryption. It simplifies complex interactions with the card hardware, making advanced cryptographic key management accessible from the command line.

CAVEATS

Using gpg-card inherently requires a compatible OpenPGP smart card and a functioning smart card reader connected to the system.

Administrative operations, particularly --factory-reset, are highly sensitive and irreversible. Incorrect usage can lead to permanent data loss on the card. Always ensure you have backups of your keys if needed before performing destructive actions. Repeated incorrect entries of the Admin PIN can permanently lock the card from certain administrative functions.

SECURITY IMPLICATIONS

Leveraging gpg-card with an OpenPGP smart card significantly boosts the security of your GnuPG keys. By moving private keys into a tamper-resistant hardware module, they are protected from software-based attacks, malware, and unauthorized access, making them more resilient than keys stored solely on a computer's file system. This hardware-backed security is crucial for high-value cryptographic operations.

PIN MANAGEMENT BEST PRACTICES

Proper management of the User PIN, Admin PIN, and Reset Code is paramount for the security and usability of your OpenPGP smart card.
The User PIN protects day-to-day operations like signing or decrypting.
The Admin PIN controls sensitive administrative functions such as key generation, import, and card resets.
The Reset Code can unblock a locked User PIN without a factory reset.
Forgetting the Admin PIN or exceeding the number of incorrect PIN entries can render parts of the card unusable or even permanently lock it, potentially requiring a factory reset and loss of all stored keys.

HISTORY

gpg-card emerged as a vital utility within the GnuPG project, which was initiated by Werner Koch in 1997. As the adoption of OpenPGP smart cards grew for secure key storage, GnuPG integrated robust support for these hardware tokens. gpg-card became the primary command-line interface for managing these devices, evolving alongside the OpenPGP card specifications to provide a secure and user-friendly method for handling cryptographic keys directly on hardware, enhancing the overall security posture of GnuPG users.