To create cryptographic keys, a secure environment that can be reasonably assured to be free of adversarial control is recommended. Here is a general ranking of environments most to least likely to be compromised:

1. Daily-use operating system
2. Virtual machine on daily-use host OS (using virt-manager, VirtualBox, or VMWare)
3. Separate hardened Debian or OpenBSD installation which can be dual booted
4. Live image, such as Debian Live or Tails
5. Secure hardware/firmware (Coreboot, Intel ME removed)
6. Dedicated air-gapped system with no networking capabilities

Boot the live image and configure networking.

Note If the screen locks, unlock with user/live.

Open the terminal and install required software packages.

• Debian and Ubuntu
• Arch
• RHEL7
• NixOS
• OpenBSD
• macOS
• Windows

Generating cryptographic keys requires high-quality randomness, measured as entropy.

• YubiKey
• OneRNG

• Temporary working directory
• Harden configuration

The first key to generate is the master key. It will be used for certification only: to issue sub-keys that are used for encryption, signing and authentication.

Important The master key should be kept offline at all times and only accessed to revoke or issue new sub-keys. Keys can also be generated on the YubiKey itself to ensure no other copies exist.

You'll be prompted to enter and verify a passphrase - keep it handy as you'll need it multiple times later.

• Signing
• Encryption
• Authentication
• Add extra identities

Although we will backup and store the master key in a safe place, it is best practice to never rule out the possibility of losing it or having the backup fail. Without the master key, it will be impossible to renew or rotate subkeys or generate a revocation certificate, the PGP identity will be useless.

Even worse, we cannot advertise this fact in any way to those that are using our keys. It is reasonable to assume this will occur at some point and the only remaining way to deprecate orphaned keys is a revocation certificate.

Once keys are moved to YubiKey, they cannot be moved again! Create an encrypted backup of the keyring on removable media so you can keep it offline in a safe place.

Tip The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD. Consider using a FAT32/NTFS filesystem for MacOS/Windows compatibility instead.

Important Without the public key, you will not be able to use GPG to encrypt, decrypt, nor sign messages. However, you will still be able to use YubiKey for SSH authentication.

Create another partition on the removable storage device to store the public key, or reconnect networking and upload to a key server.

• Change PIN
• Enable KDF
• Set information

Important Transferring keys to YubiKey using keytocard is a destructive, one-way operation only. Make sure you've made a backup before proceeding: keytocard converts the local, on-disk key into a stub, which means the on-disk copy is no longer usable to transfer to subsequent security key devices or mint additional keys.

• Signin
• Encryption
• Authentication

Verify the sub-keys have been moved to YubiKey as indicated by ssb>:

To provision additional security keys, restore the master key backup and repeat the Configure Smartcard procedure.

Important Make sure you have securely erased all generated keys and revocation certificates if an ephemeral enviroment was not used!

Ensure you have:

• Saved encryption, signing and authentication sub-keys to YubiKey (gpg -K should show ssb> for sub-keys).
• Saved the YubiKey user and admin PINs which you changed from defaults.
• Saved the password to the GPG master key in a permanent location.
• Saved a copy of the master key, sub-keys and revocation certificate on an encrypted volume, to be stored offline.
• Saved the password to that encrypted volume in a separate location.
• Saved a copy of the public key somewhere easily accessible later.

Download drduh/config/gpg.conf:

Install the required packages and mount the non-encrypted volume created earlier:

PGP does not provide forward secrecy - a compromised key may be used to decrypt all past messages. Although keys stored on YubiKey are difficult to steal, it is not impossible - the key and PIN could be taken, or a vulnerability may be discovered in key hardware or the random number generator used to create them, for example. Therefore, it is good practice to occassionally rotate sub-keys.

When a sub-key expires, it can either be renewed or replaced. Both actions require access to the offline master key. Renewing sub-keys by updating their expiration date indicates you are still in possession of the offline master key and is more convenient.

Replacing keys, on the other hand, is less convenient but more secure: the new sub-keys will not be able to decrypt previous messages, authenticate with SSH, etc. Contacts will need to receive the updated public key and any encrypted secrets need to be decrypted and re-encrypted to new sub-keys to be usable. This process is functionally equivalent to "losing" the YubiKey and provisioning a new one. However, you will always be able to decrypt previous messages using the offline encrypted backup of the original keys.

Neither rotation method is superior and it's up to personal philosophy on identity management and individual threat model to decide which one to use, or whether to expire sub-keys at all. Ideally, sub-keys would be ephemeral: used only once for each encryption, signing and authentication event, however in practice that is not really feasible nor worthwhile with YubiKey. Advanced users may want to dedicate an offline device for more frequent key rotations and ease of provisioning.

• Setup environment
• Renewing sub-key
• Rotating keys

Notations can be added to user ID(s) and can be used in conjunction with Keyoxide to create OpenPGP identity proofs.

Adding notations requires access to the master key so we can follow the setup instructions taken from this section of this guide.

Please note that there is no need to connect the Yubikey to the setup environment and that we do not need to generate new keys, move keys to the YubiKey, or update any SSH public keys linked to the GPG key.

After having completed the environment setup, it is possible to follow any of the guides listed under "Adding proofs" in the Keyoxide "Guides" page up until the notation is saved using the save command.

• Create configuration
• Replace agents
• Copy public key
• (Optional) Save public key for identity file configuration
• Connect with public key authentication
• Import SSH keys
• Remote machines (SSH Agent Forwarding)
  • Use ssh-agent
  • Use S.gpg-agent.ssh
  • Chained SSH Agent Forwarding
• GitHub
• OpenBSD
• Windows
  • WSL
    • Use ssh-agent or use S.weasel-pegant
    • Prerequisites
    • WSL configuration
    • Remote host configuration
• macOS

This section is different from ssh-agent forwarding in SSH as gpg-agent forwarding has a broader usage, not only limited to ssh.

To use YubiKey to sign a git commit on a remote host, or signing email/decrypt files on a remote host, configure and use GPG Agent Forwarding. To ssh through another network, especially to push to/pull from GitHub using ssh, see Remote Machines (SSH Agent forwarding) for more info.

To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine.

After gpg-agent forwarding, it is nearly the same as if YubiKey was inserted in the remote. Hence configurations except gpg-agent.conf for the remote can be the same as those for the local.

Important gpg-agent.conf for the remote is of no use, hence $GPG_TTY is of no use too for the remote. The mechanism is that after forwarding, remote gpg directly communicates with S.gpg-agent without starting gpg-agent on the remote.

On the remote machine, edit /etc/ssh/sshd_config to set StreamLocalBindUnlink yes

Optional If you do not have root access to the remote machine to edit /etc/ssh/sshd_config, you will need to remove the socket (located at gpgconf --list-dir agent-socket) on the remote machine before forwarding works. For example, rm /run/user/1000/gnupg/S.gpg-agent. Further information can be found on the AgentForwarding GNUPG wiki page.

• Steps for older distributions
• Chained GPG Agent Forwarding

To use a single identity with multiple YubiKeys - or to replace a lost card with another - issue this command to switch keys:

$ gpg-connect-agent "scd serialno" "learn --force" /bye

Note This is not possible on YubiKey NEO.

By default, YubiKey will perform encryption, signing and authentication operations without requiring any action from the user, after the key is plugged in and first unlocked with the PIN.

To require a touch for each key operation, install YubiKey Manager and recall the Admin PIN:

Note Older versions of YubiKey Manager use touch instead of set-touch in the following commands.

GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and attachments using Thunderbird, Enigmail and Mutt. Thunderbird supports OAuth 2 authentication and can be used with Gmail. See this guide from EFF for detailed instructions. Mutt has OAuth 2 support since version 2.0.

If PIN attempts are exceeded, the card is locked and must be reset and set up again using the encrypted backup.

Copy the following script to a file and run gpg-connect-agent -r $file to lock and terminate the card. Then re-insert YubiKey to reset.

If for whatever reason you need to reinstate your YubiKey from your master key backup (such as the one stored on an encrypted USB described in Backup), follow the following steps in Rotating keys to setup your environment, and then follow the steps of again Configure Smartcard.

Before you unmount your backup, ask yourself if you should make another one just in case.