gpg-card
Manage GPG keys on a smart card
TLDR
Start in interactive mode
Invoke one or more commands non-interactively
Show information about a smart card
Retrieve the public key using the URL stored on an OpenPGP card
Set the URL used by the fetch command
Change or unblock PINs (uses the default action for the card in non-interactive mode)
Toggle the forcesig flag of an OpenPGP card (i.e. require entering the user PIN for signing)
Factory reset a smart card (i.e. delete all data and reset PINs)
SYNOPSIS
gpg-card
PARAMETERS
--help
Display usage information and quit
--version
Show version number
--verbose
Enable more detailed output
--quiet
Suppress normal output
--reader
Specify reader port number (e.g., 0 for first reader)
--status-only
Print card status and exit (non-interactive)
--debug
Set debug level for troubleshooting
DESCRIPTION
The gpg-card command provides an interactive interface for managing GnuPG-compatible smart cards, such as OpenPGP cards (e.g., YubiKey, Nitrokey). It allows users to configure card settings, change PINs, generate subkeys, upload public keys, and perform administrative tasks.
Usage requires a compatible card reader and the PC/SC daemon (via pcscd) or scdaemon from GnuPG. Insert the card, ensure GnuPG agent is running, and invoke gpg-card to enter a menu-driven prompt. Common operations include verifying the card status, entering admin mode with 'admin', changing PINs with 'passwd', generating keys with 'generate', and quitting with 'quit'.
This tool integrates with the GnuPG ecosystem for seamless key management, ensuring cryptographic operations remain secure on hardware tokens. It supports standard OpenPGP card v2/v3 specs, handling authentication, signing, and encryption keys separately. Always back up keys before modifications.
CAVEATS
Requires inserted smart card and running pcscd or scdaemon. Admin operations need correct Admin PIN. Key generation may take time. Not all cards fully support all features. Conflicts possible with other card-using apps.
INTERACTIVE COMMANDS
help: List available commands.
status: Show card info.
admin: Commands "passwd", "name", "url", "fetch".
generate: Create subkeys.
backup: Backup keys.
quit: Exit.
REQUIREMENTS
GnuPG 2.1+, libccid, pcscd service active. Run gpg-connect-agent 'scd getinfo reader_list' /bye to verify readers.
HISTORY
Introduced in GnuPG 2.0 (2006) as part of enhanced smart card support, evolving from gpg's --edit-key for cards. Major updates in GnuPG 2.1+ for better OpenPGP card v3 compliance and touch policies. Widely used in Linux distros via gnupg2 package.
SEE ALSO
gpg(1), gpg-agent(1), scdaemon(8), pcsc_scan(1)
