drduh/YubiKey-Guide

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/drduh/YubiKey-Guide.svg?style=card)](https://bestofgithub.dev/repo/drduh/YubiKey-Guide)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/drduh/YubiKey-Guide.svg)](https://bestofgithub.dev/repo/drduh/YubiKey-Guide)

Loading README…

Name	Default	Capability
User PIN	`123456`	routine key operations (decrypt, sign, authenticate)
Admin PIN	`12345678`	manage card settings (reset PIN, change Reset Code, add keys and owner information)
Reset Code	None	reset PIN (more information)

Symptom or error	Recommended action
General GnuPG questions or unfamiliar options	Use `man gpg` to review GnuPG options and command-line flags.
Need more diagnostic detail	Restart `gpg-agent` with verbose debug output: `pkill gpg-agent; gpg-agent --daemon --no-detach -v -v --debug-level advanced --homedir ~/.gnupg`
General YubiKey or GnuPG issue	Remove and reinsert the YubiKey, or restart `gpg-agent`.
`Yubikey core error: no yubikey present`	Confirm that the YubiKey is inserted correctly. It should blink once when plugged in.
`Yubikey core error: no yubikey present` persists	Install a newer version of `yubikey-personalization`, as described in Install software.
`General key info..: [none]` in card-status output	Import the public key.
The public key is lost	Follow Recovering lost GPG public keys from your YubiKey.
`gpg: decryption failed: secret key not available`	Install GnuPG 2.x. Also verify that the PIN is correct and that the required private Subkey is available on the YubiKey.
`Yubikey core error: write error`	The YubiKey may be locked. Install and run `yubikey-personalization-gui` to unlock it.
`Key does not match the card's capability`	Use 2048-bit RSA key sizes.
`sign_and_send_pubkey: signing failed: agent refused operation`	Verify that `ssh-agent` has been replaced with `gpg-agent`, as described in Replace agents.
`sign_and_send_pubkey: signing failed: agent refused operation` persists	Run `gpg-connect-agent updatestartuptty /bye`.
`sign_and_send_pubkey: signing failed: agent refused operation` persists after updating the startup TTY	Set a valid `pinentry` program path in `~/.gnupg/gpg-agent.conf`. A related error may be `gpg: decryption failed: No secret key`.
`sign_and_send_pubkey: signing failed: agent refused operation` with OpenSSH 8.9p1 or later	This may be a known OpenSSH issue. Review the linked Arch Linux discussion.
`The agent has no identities` from `ssh-add -L`	Install and start `scdaemon`.
`Error connecting to agent: No such file or directory` from `ssh-add -L`	Ensure that the agent's UNIX socket is configured and available. Review Replace agents.
`Permission denied (publickey)`	Run SSH with verbosity, for example `ssh -v host`, and confirm that the card's public key is offered: `Offering public key: RSA SHA256:... cardno:00060123456`. Also verify the user exists on the target system (different from the user on the local system).
SSH authentication still fails	Increase SSH verbosity with up to three flags: `ssh -vvv host`.
SSH authentication still fails after reviewing verbose client output	On the server, stop the background SSH service, for example with `sudo systemctl stop sshd`, then run `/usr/sbin/sshd -eddd` in the foreground with extensive debug logging to inspect the authentication attempt. Note that the server will not fork and will only process one connection and has to be restarted after every SSH connection test.
`Please insert the card with serial number ...`	See Using multiple YubiKeys.
`There is no assurance this key belongs to the named user`, `encryption failed: Unusable public key`, or `No public key`	Run `gpg --edit-key` and set owner trust to `5 = I trust ultimately`.
`Need the secret key to do this` while setting trust	Specify trust for the identity with the `trust-key [key ID]` directive.
`pass insert` reports `There is no assurance this key belongs to the named user` and `encryption failed: Unusable public key`	Adjust the identity's trust level as described above.
`gpg: ... skipped: Unusable public key`, `signing failed: Unusable secret key`, or `encryption failed: Unusable public key`	The Subkey may have expired. Follow Updating keys to renew or rotate the Subkeys.
The pinentry dialog does not appear and SSH signing fails with `agent refused operation`	Install the `dbus-user-session` package, then restart the session or system.
Lost, stolen, damaged, or destroyed YubiKey	Restore from the encrypted backup to a new YubiKey. See Backup keys and Updating keys.
Unexpected PIN prompts during SSH authentication	Add `disable-application piv` to `~/.gnupg/scdaemon.conf`.
`gpg: selecting card failed: No such device` or `gpg: OpenPGP card not available: No such device`	The local `pcscd` service may lack permission to access the card. Create the Polkit rule shown below, replacing `wheel` if the system uses a different administrative group.

Purchase YubiKey

Prepare setup environment

Download and verify Debian

Create bootable USB device

Prepare hardware

Install software

Prepare GnuPG

Configuration

Identity

Key algorithm

Expiration

Passphrase

Create Certify key

Create Subkeys

Verify keys

Backup keys

Export public key

Configure YubiKey

Change PIN

Set attributes

Transfer Subkeys

Signature key

Encryption key

Authentication key

Verify transfer

Finish setup

Using YubiKey

Encryption

Signature

Configure touch

SSH

Replace agents

Copy public key

Import SSH keys

SSH agent forwarding

Use ssh-agent

Use S.gpg-agent.ssh

Chained forwarding

GitHub

GnuPG agent forwarding

Legacy distributions

Chained GnuPG agent forwarding

Using multiple YubiKeys

Email

Thunderbird

Mailvelope

Mutt

Keyserver

Updating keys

Renew Subkeys

Rotate Subkeys

Reset YubiKey

Optional hardening

Improving entropy

Enable KDF

Network considerations

Notes

Troubleshooting

Alternative solutions

Additional resources

Footnotes