Creating GPG keys with YubiKey (HOWTO)

Creating GPG keys with YubiKey (HOWTO)

This is a LINUX version guide, based 99.99% on “Dr. Duh’s outstanding post on the topic”. I have read many such HowTo’s, and this one is, by far, the best I’ve seen (for my needs/preferences).

The screens in his article contain the actual screens you’ll see when you run the commands needed. For me, that obscured the key parts in verbosity, so I highlight particular/relevant line ONLY – and remove the others. In theory, when you look at the full screen-data, you’ll then know what to look for.
I have removed the index section which allows you to jump around, but which also takes up screen space. I also removed the BSD/Windows pieces since I don’t have any use/interest in those, and the section on hardware entropy (I don’t have access to such toys).

I recommend that IF you don’t go straight to his guide, that you read the whole post to get a basic idea of the process – and then go to his article/post and do the full setup.
I have NOT added to or improved his post – my only contribution is a handful of annotations/comments [*] (which are highlighted in purple) to explain things that caused me some confusion (though that’s not that hard at this guys level).

I also recommend doing a practice run-through (excluding the yubikey part which is “destructive”) – several times if necessary – to get comfortable with it all, before doing your “live” setup.

Below this line, is the “trimmed” version of his truly awesome post.

This is a guide to using YubiKey as a SmartCard for storing GPG encryption, signing and authentication keys, which can also be used for SSH. Many of the principles in this document are applicable to other smart card devices.

Keys stored on YubiKey are non-exportable (as opposed to file-based keys that are stored on disk) and are convenient for everyday use. Instead of having to remember and enter passphrases to unlock SSH/GPG keys, YubiKey needs only a physical touch after being unlocked with a PIN code. All signing and encryption operations happen on the card, rather than in OS memory.

New! drduh/Purse is a password manager which uses GPG and YubiKey.

Purchase YubiKey
All YubiKeys except the blue “security key” model are compatible with this guide. NEO models are limited to 2048-bit RSA keys. Compare YubiKeys.
You will also need several small storage devices for booting a live image, and for creating backups of private and public keys.

Verify YubiKey
To verify a YubiKey is genuine, open a browser with U2F support [1] to Insert a Yubico device, and select Verify Device to begin the process. Touch the YubiKey when prompted, and if asked, allow it to see the make and model of the device. If you see Verification complete, the device is authentic.
This website verifies the YubiKey’s device attestation certificates signed by a set of Yubico CAs, and helps mitigate supply chain attacks.
[1] Though I tried this several times (in FireFox) with several of the keys I bought from YubiKey directly, as well as some I got via Amazon, it initially didn’t succeed. After I RTFS’d properly, I saw that you have to configure FireFox to allow this, so I retried in Chromium, and all worked fine.

Live image

It is recommended to generate cryptographic keys and configure YubiKey from a secure operating system and ephemeral environment, such as Debian Live.

To use Debian, download the latest live image [*] 9.9.0 at the time of this post:

Mount a storage device and copy the image to it [2]
[2] my dmesg log showed no USB related info, so I changed to lsblk instead. You’re just finding the device name onto which to put the ISO file – it’ll be the same size as the USB device you connect. In my case, it is /dev/sdb

Required software

Boot the live image and configure networking.
Note If the screen locks, unlock with user/live.
Open the terminal and install several required packages:

[3] Here I removed the piece on OneRNG entropy hardware/software, since I don’t have access to any such lovely toys.

Generating cryptographic keys requires high-quality randomness, measured as entropy. [4] Higher is nicer, but also slower unless you have that hardware thingy from [3] 🙂

To check the available entropy available on Linux:

Creating keys
Create a temporary directory which will be cleared on reboot

Disable networking for the remainder of the setup.

Master key

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. [5]
[5] He means this – keep it handy – if you are too slow inputting
the password on several of the prompts, the command just times out and exits itself

To generate a strong passphrase which could be written down in a hidden or secure place, or memorized:

On Linux or OpenBSD, select the password with the mouse to copy it to the clipboard and paste using the middle mouse button or Shift-Insert.
Generate a new key with GPG, selecting (8) RSA (set your own capabilities), Certify capability only and 4096 bit key size.
Do not set the master key to expire.

[6] Below is the trimmed output that I mentioned I would use – to show JUST the items you are setting/adjusting instead of the full screen texts.

It shows: Current allowed actions: Sign Certify Encrypt
Since you want to ONLY CERTIFY with this Master Key, you need to toggle the pieces you do/don’t want until you’re left with just Certify

Now reduced to: Current allowed actions: Sign Certify

Further reduced to: Current allowed actions: Certify which is what you want, so you can move to “Finished”

Select a name and email address – neither has to be valid nor existing. [*]
[*] I’ll state the obvious here (because someone asked me this) – you should use your own details – not his

[7] The “blah blah blah” is to save screen space – also be aware that it DOES TAKE LONG to finish the entropy pieces

Export the key ID as a variable KEYID for use later:

Additional identities:
[9] This is mentioned lower down in his article (after all the subkeys have been created), but not covered in any detail.

It made sense (to me anyway) to do this before the sub-keys, so that (IF applicable) the subkeys could “inherit” the UIDs – but I cannot [YET] confirm if this is true/correct or not.

I have several different emails/ids. When I initially started with GPG, I created a full set of master/sub-keys for each one. This is just waaaay too much work from both a creation, and a usage perspective. Not to mention you then need a YubiKey for each one, and have to remember which key goes with which ID etc.
Luckily, you can add additional UserIDs to the keys.
The convention I personally use is to have “Real Name (ABBR)” where the (ABBR) is just some text to help me identify which one I am working on/with.

By way of example, for
– personal, I set the Name:Trent Murgatroyd (THM)
– office email:, I set the Name:Trent Murgatroyd (IKFF)

You would do this for each of your keys to which you’d like to add UIDs, and you would do the adduid per additional UID(email). (Similarly, you could remove UIDs using deluid)


Edit the master key to add sub-keys:

Use 4096-bit key sizes. Use a 1 year expiration for sub-keys – they can be renewed using the offline master key.

[8] I personally chose to set these to NOT expire. I know that 2048 bit keys are regarded as defunct by 2030, but I’m guessing/hoping that 4096 will last long enough to outlive say, ME. If not, just as easily as generating a new one for expiry purposes, I could just revoke these at that time and create them then. Later in his article he actually says the revocation is better suited for certain purposes than expiry. Maybe in time YubiKeys will support ecdsa or other technologies, and the whole expiry/revocation discussions will cease to be relevant

Create a signing key by selecting (4) RSA (sign only):
[*] Get your MasterKey password ready on the clipboard

Next, create an encryption key by selecting (6) RSA (encrypt only):
[*] Get your MasterKey password ready on the clipboard again

Finally, create an authentication key.
[*] Get your MasterKey password ready on the clipboard again

GPG doesn’t provide an authenticate-only key type, so select (8) RSA (set your own capabilities) and toggle the required capabilities until the only allowed action is Authenticate:

Finish by saving the keys.

List the generated secret keys and verify the output:

Add any additional identities or email addresses you wish to associate using the adduid command [9].

[9] He mentions this, but doesn’t cover this aspect in any detail, so I added in a small piece on the topic higher up (right after the initial Master Key creation).

  I placed it up there because it made sense (to me) to have all the UIDs set before adding sub-keys. I don’t think it makes any difference to inheritance though, so it might be OK to do this after creating the sub-keys, and/or to only add UIDs to specific keys when you invoke the
gpg2 --edit-key KEY_TO_ADD_UIDS_TO
(eg. You might want multiple UIDs on only the Signing key)

Tip Verify with a OpenPGP key best practice checker

The output will display any problems with your key in red text. If everything is green, your key passes each of the tests. If it is red, your key has failed one of the tests.

hokey may warn (orange text) about cross certification for the authentication key. GPG’s Signing Subkey Cross-Certification documentation has more detail on cross certification, and gpg v2.2.1 notes “subkey does not sign and so does not need to be cross-certified”. hokey may also indicate a problem (red text) with Key expiration times: [] on the primary key.

The master key and sub-keys will be encrypted with your passphrase when exported.

Save a copy of your keys:

Once GPG keys are moved to YubiKey, they cannot be moved again! Create an encrypted backup of the keyring and consider using a paper copy of the keys as an additional backup.
Tip: The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD.

Attach another external storage device and check its label [10]:

Write it with random data to prepare for encryption:

Erase and create a new partition table:

[10] In my case I used an SD card, which after altering the partitions, had to be ejected and re-inserted before it would do the “Syncing disks” part.

Create a new n within fdisk partition with a 10 Megabyte size:

Use LUKS to encrypt the new partition:

Mount the partition:

Create a filesystem:

Mount the filesystem and copy the temporary directory with the keyring:

Keep the backup mounted if you plan on setting up two or more keys [11] as keytocard will delete the local copy on save.

[11] Since I’m a bit paranoid, and a cheapskate who generally buys low end gear to experiment on, I prefer to make to backup copies onto multiple, separate media, just in case one is lost or damaged. It just means doing the above process multiple times BEFORE the keytocard section.
I guess you could equally make a duplicate of the first card/device after you’re done. **I don’t (YET) know if one can mirror an encrypted partition??

Otherwise, unmount and disconnected the encrypted volume:

Create another partition to store the public key, or skip this step if you plan on uploading it to a key server.

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.

Configure Smartcard
Use GPG to configure YubiKey as a smartcard:

Change PIN
The default PIN is 123456 and default Admin PIN (PUK) is 12345678. CCID-mode PINs can be up to 127 ASCII characters.

The Admin PIN is required for some card operations and to unblock a PIN that has been entered incorrectly more than three times. See the GnuPG documentation on Managing PINs for details.

A note from the “Managing PINs” page: Warning: It is also important to know that entering a wrong AdminPIN three times in a row destroys(!) the card.
There is no way to unblock the card when a wrong AdminPIN has been entered three times.

Set information
Some fields are optional.

Transfer keys

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.
Previous GPG versions required the toggle command before selecting keys. The currently selected key(s) are indicated with an *. When moving keys only one key should be selected at a time.

[*] Get your MasterKey password ready on the clipboard again

Select and move the signature key [12]. You will be prompted for the key passphrase and Admin PIN.

[12] It wasn’t obvious/intuitive (to me), so a note:
Within the GPG command-prompts, you need to select the key you’re going to work on. The default is ‘none’, so you would type key 1 to toggle the active key. To change the key you’re working on, first un-toggle the active key back to ‘none’ by typing key 1. The ssb* indicates the key that is active – I mark the line with > so you can see where it is, just in case it isn’t clear

Type key 1 again to de-select and key 2 to select the next key:

Type key 2 again to deselect and key 3 to select the last key:

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

Ensure you have:

  • Saved the encryption, signing and authentication sub-keys to YubiKey.
  • Saved the YubiKey PINs which you changed from defaults.
  • Saved the password to the master key.
  • Saved a copy of the master key, sub-keys and revocation certificates 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.

Reboot or securely delete $GNUPGHOME and remove the secret keys from the GPG keyring:

Important Make sure you have securely erased all generated keys and revocation certificates if a Live image was not used!

[13] If all went well, you should now have completed the creation of your PGP keys, have (some) encrypted offline Master + Sub-Keys which you can safely/securely use from your YubiKey
Dr. Duh (in his article/post) goes on to show how you can use them, but I will keep that for a separate post which will probably (again) be heavily based on his post.

3 thoughts on “Creating GPG keys with YubiKey (HOWTO)

  1. I ᴡas wondering if you ever considereԁ changіng
    the structure of your website? Its very well written; I love what
    youve got to say. But maybe you could a little more in the way of
    content ѕo people could conneⅽt with it better. Ⲩouve got an awfuⅼ lot
    of text for only having 1 or 2 images. Maybе
    you could ѕpace it օut better?

  2. Great post. I waѕ checking continuously this blog and I’m impressed!

    Extremely helpful info speciaⅼly tһe last part :
    ) I maintain such info much. I used to be seeking this particular information for
    a very long time. Thank you and goⲟd luck.

  3. Nice post. I learn sⲟmething new and challengіng on blⲟgs I stumbleupоn everyday.
    It’s always interesting to read articles from other auth᧐rs and practice a little sometһing from other

Leave a Reply

Your email address will not be published. Required fields are marked *

6 + 8 =