Skip to content

OpenPGP Smart Cards

A smart card is a small piece of hardware, such as a YubiKey or a Nitrokey, that holds your private key and does the signing and decrypting itself.

The point is simple: the private key never leaves the card. Even if someone takes over your computer, they cannot copy the key. They can only use it while the card is plugged in, and only if they know your PIN.

GpgFrontend can read your card, change its settings, make new keys on it, and move an existing key onto it. All of this happens in one window:

  1. In the main window, open the Advanced menu.
  2. Choose Open Smart Card Controller. The Smart Card Controller window opens.

This window is not available in sandboxed builds (Flatpak and the Mac App Store edition).

Your card has two codes, and they do different jobs.

PIN

Also called the User PIN. The everyday one. You type it to sign or decrypt. A new card often comes with a PIN of six digits.

Admin PIN

The one for changing the card itself, such as making keys or resetting the PIN. A new card often comes with an Admin PIN of eight digits.

Change both from their factory values before you start using the card for real work. See Access Codes under Finding Your Way Around.

Your public key is not stored on the card, and does not need to be. Share it the usual way. See Import and Export Keys.

You can store a public key URL on the card. It tells other software where to fetch your public key from. This is handy, but you do not have to do it.

A key that lives on a card still shows up in your key list. Your computer keeps a small placeholder for it, called a stub. The stub is not the key. It just tells GnuPG “this one lives on a card, go ask the card”.

In the key list, the type of such a key ends with ^, for example pub/sec^.

If you lose the card, the stub stays behind but is useless. Keep this in mind before you move your only copy of a key onto a card.

The window has three parts:

  1. At the top: the Card list. If you have more than one card plugged in, pick the one you mean here. The cardholder name and a status light sit next to it.
  2. In the middle: what the card says about itself. This includes who it belongs to, its serial number, how many PIN tries are left, and the keys it holds.
  3. Along the bottom: the buttons.

If no card is found, the window says No OpenPGP Smart Card Found instead.

The buttons are:

  • Cardholder: choose Change Name, Change Language, Change Sex, Change Login Data or Change Public Key URL.
  • Access Codes: choose Change PIN, Change Admin PIN or Change Reset Code.
  • Generate Card Keys: make brand new keys on the card itself.
  • Move Key to Card: put a key you already have onto the card.
  • Fetch: download your public key from the public key URL stored on the card, and import it into your key list. This needs an internet connection, and a URL must be set on the card (Cardholder > Change Public Key URL).
  • Refresh: reload what is shown in this window.

There is also a More button with two items:

  • Restart All Gpg-Agents: worth trying if your card is plugged in but not detected.
  • Open GnuPG Smart Card HOWTO: opens the GnuPG guide to smart cards in your web browser.

Generate Card Keys creates the keys on the card itself, so the private key has never existed anywhere else. This is the safest way to use a card.

  1. Open the Smart Card Controller window and click Generate Card Keys. The Card Key Generation window opens.

  2. Type your Name. Email and Comment are optional.

  3. Pick an Expire Date, or tick Non Expire for keys that never expire. The earliest date you can pick is two years from today.

  4. Click Generate. This replaces any keys that are already on the card.

  5. Wait for the message “Card key generation completed successfully.”

The catch is that you cannot back the key up, because it cannot be copied off the card. If the card is lost or breaks, that key is gone. Plan for that. Many people keep a separate key that is stored offline, and treat the card keys as ones they can replace.

New in v2.2.2. Use this when you already have a key and want to move it onto a card.

  1. Open the Smart Card Controller window and click Move Key to Card. The Select Key to Move to Card window opens.

  2. Pick the key Database. Then select the one key or subkey you want to move, and click Confirm. To choose a subkey, expand its key first. Only GnuPG key databases can do this.

  3. Read the warning. Click Yes to go on.

  4. GpgFrontend asks if you want to back up the secret key. Click Back Up First and save the file somewhere safe. This backup is your only way back if the card fails.

    Continue Without Backup moves the key without saving a copy. Cancel stops, and nothing is moved.

  5. If the key could go in more than one slot, the Select Card Slot window asks where to store it: Signature (OPENPGP.1), Encryption (OPENPGP.2) or Authentication (OPENPGP.3).

  6. Wait for the message “The key was moved to the smart card successfully.” Your key list is updated on its own.

You can also start this from a single subkey: open the key’s details, go to the Keychain tab, right-click the subkey, and choose Move to Card. If more than one card is plugged in, the Select Smart Card window asks which card to use.

Most OpenPGP cards have three slots: one for signing, one for encryption, and one for authentication. Some cards differ, so check the maker’s documentation.

My card is plugged in but nothing shows up

Section titled “My card is plugged in but nothing shows up”

Try, in this order:

  1. Refresh.
  2. More, then Restart All Gpg-Agents.
  3. Unplug the card and plug it back in.
  4. Check that your key database is using the GnuPG engine.

I changed my default key database, and the card still uses the old one

Section titled “I changed my default key database, and the card still uses the old one”

Smart cards stay with the previous default key database until GpgFrontend restarts. To switch them sooner, open the Smart Card Controller window, click More, then Restart All Gpg-Agents. See Multi-Key Database.

Yes. Devices like a YubiKey usually hold several separate applications at once. Examples are OpenPGP for GpgFrontend, FIDO2 for website logins without a password, and PIV for smart card logins at work.

These applications do not affect each other. Making an OpenPGP key does not touch your passkeys, and each application has its own PINs. You need different software for each one.

The device’s total storage is shared, though, so each application has its own limits.