Mind Dump, Tech And Life Blog
written by Ivan Alenko
published under license CC4-BY
posted in category Linux Software / Yubikey
posted at 14. Nov '26

Yubikey Linux Setup

This article will describe the software and configuration needed to get Yubikey working for regular user and to sign commits. I still don't have it in my Ansible local setup and it just breaks each couple of months of after I have to reinstall a system.

Install Software Support

Use a package manager of your operating system.

apt-get install libyubikey-udev scdaemon gnupg pinentry-tty
  • libyubikey-udev - "udev rules for unprivileged access to YubiKeys" - allows regular user to use Yubikey, otherwise you have to use sudo. Restart udev or reboot to see the changes.
  • scdaemon - "GNU privacy guard - smart card support" - Yubikey is handled as a smart card, without scdaemon Yubikey will be registered in Linux, but gnupg won't see it
  • gnupg - "GNU privacy guard - a free PGP replacement" - software suite to use PGP encryption
  • pinentry-tty - "minimal dumb-terminal PIN or pass-phrase entry for GnuPG" - the private key in Yubikey is (optionally) protected by PIN code (one normal, one for keys management)

File Configuration

~/.gnupg/gpg-agent.conf

pinentry-program /usr/bin/pinentry-tty
allow-loopback-pinentry

This sets up pinentry program - you can use also pinentry-qt, curses and other. Without allow-loopback-pinentry it is not able to start pinentry and will complain.

~/.gnupg/gpg.conf - unmodified from https://github.com/drduh/config/blob/main/gpg.conf

# https://github.com/drduh/config/blob/main/gpg.conf
# https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html
# 'gpg --version' to get capabilities
# Use AES256, 192, or 128 as cipher
personal-cipher-preferences AES256 AES192 AES
# Use SHA512, 384, or 256 as digest
personal-digest-preferences SHA512 SHA384 SHA256
# Use ZLIB, BZIP2, ZIP, or no compression
personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed
# Default preferences for new keys
default-preference-list SHA512 SHA384 SHA256 AES256 AES192 AES ZLIB BZIP2 ZIP Uncompressed
# SHA512 as digest to sign keys
cert-digest-algo SHA512
# SHA512 as digest for symmetric ops
s2k-digest-algo SHA512
# AES256 as cipher for symmetric ops
s2k-cipher-algo AES256
# UTF-8 support for compatibility
charset utf-8
# No comments in messages
no-comments
# No version in output
no-emit-version
# Disable banner
no-greeting
# Long key id format
keyid-format 0xlong
# Display UID validity
list-options show-uid-validity
verify-options show-uid-validity
# Display all keys and their fingerprints
with-fingerprint
# Display key origins and updates
#with-key-origin
# Cross-certify subkeys are present and valid
require-cross-certification
# Enforce memory locking to avoid accidentally swapping GPG memory to disk
require-secmem
# Disable caching of passphrase for symmetrical ops
no-symkey-cache
# Output ASCII instead of binary
armor
# Enable smartcard
use-agent
# Disable recipient key ID in messages (WARNING: breaks Mailvelope)
throw-keyids
# Default key ID to use (helpful with throw-keyids)
#default-key 0xFF00000000000001
#trusted-key 0xFF00000000000001
# Group recipient keys (preferred ID last)
#group keygroup = 0xFF00000000000003 0xFF00000000000002 0xFF00000000000001
# Keyserver URL
#keyserver hkps://keys.openpgp.org
#keyserver hkps://keys.mailvelope.com
#keyserver hkps://keyserver.ubuntu.com:443
#keyserver hkps://pgpkeys.eu
#keyserver hkps://pgp.circl.lu
#keyserver hkp://zkaan2xfbuxia2wpf7ofnkbz6r5zdbbvxbunvp5g2iebopbfc4iqmbad.onion
# Keyserver proxy
#keyserver-options http-proxy=http://127.0.0.1:8118
#keyserver-options http-proxy=socks5-hostname://127.0.0.1:9050
# Enable key retrieval using WKD and DANE
#auto-key-locate wkd,dane,local
#auto-key-retrieve
# Trust delegation mechanism
#trust-model tofu+pgp
# Show expired subkeys
#list-options show-unusable-subkeys
# Verbose output
#verbose

This configuration allows smart cards (use-agent) and sets some other stuff.

~/.gnupg/scdaemon.conf

reader-port Yubico Yubi
disable-ccid

USB Interface: CCID

The CCID USB interface causes the YubiKey to act as a smart card reader. It can be used to communicate with several of the YubiKey Applications.

For some reason CCID is fucked (or used to be, I don't have energy right now to allow it).

See more troubleshooting, but this article pretty much sums them up:

And now you have to basically set up private keys and add public keys to GnuPG - only private keys are stored in Yubikey (4, 5). I have an article in works about this (for 4 years ;-( already)), it will be released "soon". But the process starts with gpg --card-edit, setup up information, private, public keys, then export public keys to back them up and also upload keys to a keyserver if you want.

Add Comment