An Opinionated YubiKey Set-Up Guide

This guide assumes the primary reason why you want to use a YubiKey is that you fear at some point a remote adversary who’s targeting you specifically will gain root access on your local computer. With root on your computer, the adversary will be able to log your keystrokes and sift through your computer’s memory to identify and exfiltrate all the passwords and private keys you use regularly, as well as steal credentials stored on your computer’s hard drives (or remotely accessible from your computer).

Stealing your passwords, private keys, and other credentials would allow the adversary to use those credentials to log into any publicly-accessible web application or server at a later time from any other computer in the world. She would also be able to decrypt any files she had stolen previously (or steals later) that had been encrypted for your private keys. And she would be able to sign any messages, certificates, or other files at any time from any computer with the keys she had stolen.

By using a YubiKey to store your private keys, and by using your YubiKey for passwordless authentication or 2FA to various websites, you can limit an adversary’s use of your private keys and other credentials. Only while the adversary maintains her access on your local computer will she be able to use your private keys or be able to log into websites or other servers using your credentials.

Also, as long as you always keep your YubiKeys on your person whenever you’re away from your computer (or keep them in a secure location to which only you have access, like a personal safe), you can prevent an adversary from using your private keys and website credentials while you’re away from your computer — even for an adversary who has physical access to your computer. (Of course, an adversary with physical access can still do bad things to your computer, like set up permanent remote access for herself.)

This guide assumes that even if you store your credentials on a YubiKey, a remote adversary with access to your computer will be able to trick you into touching your YubiKey whenever she needs to use them. Therefore, the YubiKey’s touch requirements provide only a “defence in depth” benefit, forcing the adversary go to the trouble of ensuring that you’re at your computer and are expecting to have to touch your YubiKey whenever she needs to use a private key or other credential stored on your YubiKey.

Some other opinions that pervade this guide:

This guide will show you how to use the YubiKey Manager CLI (aka ykman) to set up each YubiKey application — see the YubiKey Manager Installation page for installation options. If you don’t use a package manager to install the ykman CLI, you most likely will have to install the pcsc-lite daemon (aka pcscd) separately.

On a Debian-based Linux distro (like Ubuntu and friends), if you don’t use a package manager to install the ykman CLI, you’ll have to install these dependencies in order to build and run the Python yubikey-manager package manually:

And on a Fedora-based distro (like RHEL and friends), if you don’t use a package manager to install the ykman CLI, you’ll have to install these dependencies for the Python yubikey-manager package:

Otherwise, on most Linux distributions, if you do use the distro’s package manager to install the ykman CLI, the package manager will automatically install the necessary dependencies for you; like on Debian:

Or on Fedora:

Once you have the ykman CLI installed, plug your YubiKey into your computer, and run the following command to see its details:

Each one of the listed applications has its own, separate PIN or passphrase that is set independently of the other applications (except for the FIDO U2F and FIDO2 apps, which share a single FIDO management interface). Each app’s PIN or passphrase controls access to the configuration and secrets stored by the app. The config and secrets of each app can be wiped independently of the other apps.

There is one PIN that rules them all, however. The YubiKey has a master config application that allows you to enable or disable each individual app on the YubiKey. When an application is disabled, its configuration and secrets cannot be accessed or changed — or wiped. This is particularly important to take note of, since otherwise wiping an app’s config and secrets (aka a “factory reset”) does not require the app’s own PIN or passphrase.

The YubiKey allows you to set a 128-bit “lock code” to protect changes to this master config app. By default, your YubiKey comes with no lock code set. However, in order to prevent an adversary who gains access to your computer while your YubiKey is plugged in from being able to lock you out of all your YubiKey secrets, you should set this lock code.

Unfortunately, you must always enter this lock code as a string of 32 hex digits, which makes it cumbersome to use. Fortunately, most people will need to use it rarely, if ever.

Run the following command to set the lock code for your YubiKey to a new random number:

This will generate a new random number (as 32 hex digits), and print it out:

Enter y at the prompt to set this as the new lock code. Write this code down on a piece of paper (along with all the other PINs and passphrases you set for the other apps on your YubiKey; see the Backing Up PINs section at the end of the article).

You’ll have to enter this lock code in the future to enable or disable any apps on your YubiKey. For example, to disable the NFC interface to the YubiHSM Auth app, run the following command:

Enter y to confirm, then enter your 32 hex-digit lock code (10a43eacde8630603fc15016bc508605 in this example):

If you do the same for the USB interface (ykman config usb --disable HSMAUTH), and then run the ykman info command again, you’ll see that the YubiHSM Auth app has been disabled completely on your YubiKey:

You can re-enable an app by running the same commands with the --enable option instead of the --disable option:

First, use the passwd command to change the existing PINs from their defaults:

The OpenPGP app has 3 PINs: the user PIN, the reset code (aka PUK, PIN Unblock Key), and the admin PIN. The user PIN is the one you use for day-to-day access to your OpenPGP private keys; you don’t need and won’t set a reset code; and the admin PIN is used to change the settings of the OpenPGP app itself (and to unblock or change the user PIN if you forget it or enter it incorrectly too many times in a row). When prompted to enter your “PIN” with no “admin” qualifier, this usually means your should enter the user PIN, not the admin PIN.

Enter 1 at the prompt for the passwd command, and then enter 123456 at the first PIN prompt (the default user PIN is 123456). Next, enter the new user PIN (you’ll be prompted for it twice). Do not use a number — instead use a simple passphrase (in the “correct horse battery staple” vein) that’s at least 6 characters long and easy to type (you’ll need to type it frequently, probably at least several times a day). Make sure it’s different than any other PIN or passphrase you’ve ever used before.

The CLI will output PIN changed if successful:

Next, enter 3 to set the admin PIN, and then enter 12345678 at the first PIN prompt (the default admin PIN is 12345678). Next, enter the new admin PIN (you’ll be prompted for it twice). Like with the user PIN above, do not use a number — instead use a simple passphrase at least 8 characters long. It doesn’t need to be any stronger than the user PIN, just different (enough so that an adversary wouldn’t be able to guess the admin PIN if she finds out your user PIN).

The CLI will again output PIN changed if successful:

Write down your new PIN passphrases on paper, along with the serial number of the YubiKey, and a note that these are for the OpenPGP application (each YubiKey app, like PIV, FIDO, OATH, etc, uses its own separate set of PINs or passwords). In particular, you will rarely use your admin PIN after you finish setting up the OpenPGP application the first time, so you will surely forget the admin PIN unless you write it down.

Enter q to return back to the main card-edit CLI:

Now, use the key-attr command so that when you generate your keys, it will generate Curve 25519 keys instead of RSA keys:

Select the ECC option:

Select Curve 25519:

Enter the admin PIN when prompted to save your changes for that key. Select the same options (ECC and Curve 25519) as the prompts continue for the encryption key and authentication key:

If you list the card info, you should now see the Key attributes setting listed as ed25519 cv25519 ed25519:

Now you’re ready to generate a new set of OpenPGP keys on the YubiKey, using the generate command:

Enter n to ensure that the private keys never leave the YubiKey, and enter the admin PIN when prompted:

Then enter 0 to prevent the keys from expiring:

When prompted for your real name, email address, and comment, use the “real name” field for the display name or alias you want associated with the OpenPGP key, the “email address” field for the email account associated with the key, and the “comment” field for a word or phrase that will distinguish this key from other keys you have used or will use in the future with the same name and email. For example, I might enter the following for real name, email address, and comment:

GnuPG will show this user identity (aka uid) as Justin Ludwig (work key 1) <justin.ludwig@example.com> when I later list all the keys I own on my keyring:

Continuing on with the generation process, confirm that you are happy with the uid values you selected by entering o when prompted:

Finally, you’ll be prompted to enter the admin PIN again, and then the user PIN. Then the ID of the newly generated master key will be printed:

Now if you list the card details, you’ll see the new keys listed:

And now if you run the quit command, GnuPG will print out your new keys in its usual format:

Finally, we’ll use the ykman CLI to adjust the PIN and touch policies for the new OpenPGP key. Run the following command to check their current settings:

Since you set a good random PIN for both the user and admin PINs earlier, you can relax the PIN-tries constraints a little, say to 9 each:

Enter the admin PIN when prompted, and y to confirm the change:

If sometime in the future you fail 9 times in a row to enter the user PIN correctly, the YubiKey will block you from accessing any of its OpenPGP private keys. If that happens, you can use the passwd sub-command of the gpg --edit-card command we saw earlier to “unblock” the user PIN to allow more attempts (or to change the user PIN to something else) — as long as you can correctly enter the admin PIN.

If you fail 9 times in a row to enter the admin PIN correctly, the YubiKey will block you from updating any of its OpenPGP settings, or unblocking the user PIN — permanently. As long as the user PIN itself isn’t blocked, however, even with the admin PIN blocked you can still use the OpenPGP private keys on the YubiKey. And you can always use the factory-reset sub-command of the gpg --edit-card command mentioned earlier to wipe the existing OpenPGP keys and start over from scratch, even if both user and admin PINs are blocked.

One last setting you should change for the OpenPGP app: run the following command to require a touch to access the OpenPGP signature key:

Enter the admin PIN when prompted, and y to confirm the change:

Do the same for the OpenPGP decryption and authentication keys:

Whenever you need to sign or decrypt something with your OpenPGP keys, the YubiKey will blink rapidly, and you must touch the key within 15 seconds or the attempt will be rejected by the YubiKey. Using cached instead of on for the above settings means that the YubiKey will allow the use of your OpenPGP keys for 15 seconds after a touch, without requiring more touches (otherwise signing a bunch of commits after a rebase or decrypting a bunch of individual files from an archive becomes a test of patience and fine-motor skills).

You can run a quick test of PGP signing and decryption by running the following command (replace key1 in the following command with the comment you used when generating your new key, or with its full key ID, like 0xABCDEF1234567890):

You’ll first be prompted for your user PIN (to sign the test), then your YubiKey will blink until you touch it. Once you touch it, you’ll be prompted again for your user PIN (this time to decrypt the test). Then you should see output like the following:

Finally, you’re ready to publish your new OpenPGP keys. You can export the public keys to a file that can be shared to other keyrings using the following command (replace key1 with the comment you used when generating your new key, or with its full key ID, like 0xABCDEF1234567890):

This file can be copied to another computer, and imported on that computer by running the inverse command:

You can also publish your OpenPGP keys publicly by sending them to a PGP keyserver. The following command will send them to the keyserver configured in your ~/.gnupg/gpg.conf file:

And if you want to use your new authentication key for SSH authentication, you can export it with the following command:

Copy the command output to a line in the ~/.ssh/authorized_keys file on any host with which you want to use your new OpenPGP key to authenticate. If your GnuPG agent is configured with SSH support, you should be able to SSH into one of those hosts (like bastion.example.com) with the following command:

The first thing to set up is to change the allowed number of PIN retries. Changing the number of retries automatically resets the PIN and PUK (PIN Unblock Key) to their factory defaults, so do this first before setting the PIN and PUK. Run the following command to set the PIN and PUK retries to 9:

Simply press enter at the management-key prompt, then enter 123456 at the PIN prompt:

Then enter y to confirm the change:

Next, run the following command to change the PIN:

The PIN must be 6-8 alphanumeric characters. You’ll use this PIN frequently if you use the PIV app regularly; it’s required to use the private keys stored in the PIV app, and to change any of its settings. It’s hard to choose a great PIN with so few letters available — but because an adversary will have only 9 attempts to guess it, it doesn’t have to be great — it just needs to be a password you’ve never used before, and isn’t related to any facts about yourself (like your birthday, your kid’s names, your favorite sports team, etc).

Enter the old PIN, 123456, first:

Then enter your new PIN, twice:

Next, run the following command to change the PUK (PIN unblock code):

The PUK must also be 6-8 alphanumeric characters. An adversary will also have only 9 attempts to guess it, so it doesn’t have to be great, either. However, since you should basically never have to enter it (it’s used only to unblock the PIN if you accidentally entered the wrong PIN 9 times in a row), and it can only be up to 8 characters long, you might as well use an 8-character random number for it.

Enter the old PUK, 12345678, first:

Then enter your new PUK, twice:

Write down your new PIN and PUK on the same piece of paper you wrote down your OpenPGP user PIN and admin PIN, noting that they’re for the YubiKey’s PIV application (each YubiKey app, like OpenPGP, FIDO, etc, uses its own separate set of PINs or passwords).

Next, run the following command to change the PIV management key:

Internally, the management key is required by the PIV application anytime the app’s settings are changed (like to generate a new key, or import certificates or other data into the app’s storage). Unlike the PIN or PUK, however, the number of consecutive wrong attempts to use it are not capped — so the key should be long and strong.

In lieu of having to enter in a long random string of characters every time you need to change a setting on the PIV app, YubiKeys have a feature that allow you to store a long, strong management key in the PIV app itself, and protect the key with the PIV application’s regular PIN (plus a YubiKey touch). The ykman CLI and the YKCS11 library will automatically detect when this feature is being used, and transparently request for and use the PIN to access the management key when needed (so you never need to know or enter the management key itself).

The --protect option in the above command directs the YubiKey PIV app to use this feature when setting up the new management key (and to automatically generate a new strong random key). The --touch option directs it to also save the key in a way that requires a touch to for each access.

Press enter when prompted, then enter the PIN (the new one you just set via the piv access change-pin command above):

Now when you run the following command, the output should show that you’re no longer using the default PIN or management key for the PIV application:

Now you’re ready to generate a new set of PIV keys for the YubiKey. There are 25 separate key slots (numbered with hex digits, like f9 or 9a etc) available on your YubiKey; 5 with a prescribed definition, and 20 miscellaneous slots:

The f9 slot (PIV Attestation) comes preloaded with a key and certificate generated and signed by Yubico. The PIV application automatically uses this key to sign the other PIV keys you generate on your YubiKey. It’s the only slot that isn’t wiped if you reset your PIV application, although it can be overwritten with a different key if you like. Unless you have a specific reason to change it, you should leave it as is (and not use it for anything other than key certification).

The 9e slot (Card Authentication) is intended to be used to unlock doors or other devices that don’t have a PIN pad (but if you don’t use your YubiKey for physical authentication, you can use it for whatever you want). We’ll skip it.

For example purposes, this guide will show you how to set up the 9a slot (PIV Authentication) with an SSH key, the 9c slot (Digital Signature) as signing key with a certificate signed by another CA, the 9d slot (Key Management) for key agreement (ie deriving a shared encryption/decryption key with another party), and the 82 slot (Retired Key 1) as a simple root CA.

Since you’re going to be saving a few public keys and other temporary files to disk for the next steps, for your convenience, create a new directory and change to it:

Now generate your first PIV key, entering your PIV PIN and touching the YubiKey when prompted:

This will generate a new P-384 key in the PIV app’s 9a slot (PIV Authentication). When using this private key in the future, you’ll have to provide the PIV PIN once per PKCS #11 client session, as well as touch your YubiKey once per use (if you hadn’t already touched it in the previous 15 seconds).

The new public key will be saved to the file key1-9a.pub:

We’ll use this file in the next step, but you don’t have to save it permanently — you can always ask the PIV application to export a new copy of the public key for you later. For example, the following command will export it to stdout:

Next, we’ll generate a self-signed certificate for the new key. You don’t necessarily need a certificate for every key, but some PKCS #11 clients may require it, so it’s nice to have. You can always replace it later with a different certificate (self-signed by the same key, or signed by some other CA).

To generate a new self-signed certificate, run the following command, entering your PIV PIN and touching the YubiKey when prompted:

You’ll need to specify a subject DN (Distinguished Name) for the certificate via the --subject option. If you don’t have a particular DN format required for your use of the key, you can just specify a CN (Common Name) component with whatever text will help you (or anyone else who views the certificate) disambiguate it from other certificates you may use. Using the same format as an OpenPGP UID (eg real name (comment) <email address>) can be a good starting point. You may also want to note the YubiKey and PIV slot in which the key can be found (like the (key1-9a) text from the example above).

You should also specify a validity time period for the certificate via the --valid-days option (the default is 365 days). The key will still be good after this period expires — but the certificate won’t be. While short validity periods in general are a good security practice, they provide limited practical benefits for a self-signed certificate (since the key holder can simply generate a new self-signed certificate on demand). A validity period of 4000 days (almost 11 years) should last you the lifetime of the key.

Whenever you need to access this certificate, just run the following command to save it to a file:

You can use OpenSSL to inspect the certificate details:

Generate a key and certificate for any other PIV keys you want the same way, such as for slot 9c (Digital Signature):

And slot 9d (Key Management — encryption/decryption):

And slot 82 (Retired Key 1 — a miscellaneous key we’ll use for an example CA):

Now if you run the following command, you’ll see the details listed for each of the 4 keys we just generated:

To use key 9a (PIV Authentication) that we generated above for SSH authentication, first run the following command to print out the available PIV keys on your YubiKey in SSH authorized-keys format:

Replace /usr/lib/x86_64-linux-gnu/libykcs11.so.2 with the path to your YKCS11 library (see the beginning of the PIV section) if different.

Find the line in the output with a comment containing “PIV Authentication” (the label for key 9a), and copy it to the ~/.ssh/authorized_keys file on any host with which you want to use the key to authenticate (like bastion.example.com).

Then you can SSH into that server by running the following command:

Enter your PIN when prompted, and then touch the YubiKey when it starts blinking:

To get a certificate from a real CA (Certificate Authority) for key 9c (Digital Signature) that we generated above, first run the following command to generate a CSR (Certificate Signing Request):

Set the --subject option to the appropriate subject DN for the certificate, and use the public key file key1-9c.pub you exported earlier (or re-export it if necessary). Enter your PIN, touch your YubiKey, and the command will save the CSR to the file key1-9c.csr:

View the CSR with the following OpenSSL command:

Provide the CSR to the CA operator; and when the CA operator returns the signed certificate, import it by running the following command (where the certificate file is named key1-9c.crt in this example):

Use the --verify option when importing a certificate to verify that the certificate matches the key stored in slot 9c (so you don’t accidentally import a certificate for some other key). Enter your PIN, touch your YubiKey, and the command will import the certificate (if it matches the key):

The command will fail with an error message if the certificate doesn’t match the key:

Your YubiKey will now provide the cert from the CA, instead of the self-signed certificate you generated originally, when queried:

If you want to use a PIV key like 9d (Key Management) for decryption, like to exchange messages with some other party, say your friend Alice, you’d first exchange public keys. You’d give her the key1-9d.pub public key file that you exported for your 9d key, and she’d give you her public key (it would have to be a public key of the same type as yours, for the P-384 curve).

She might create her key pair with the following OpenSSL commands:

Her private key was saved to the alice.key file, and her public key to the alice.pub file. With the key1-9d.pub file containing your public key, she can derive a shared secret with her private key by running the following command:

She can feed this shared secret into the openssl enc command to use it to encrypt a message that only you and she can read:

If she sends you the output of this command (U2FsdGVkX1/f6Cna6360s7SrA6zo0OY0mQ==), you can decrypt it by deriving the same shared secret with the private key stored in the 9d slot of your YubiKey, plus her alice.pub public key file:

Enter your PIV PIN at the prompt, touch your YubiKey, and you should see the message from Alice output as a result of the command:

To use key 82 (Retired Key 1) for a root CA, you can set up a simple CA with OpenSSL. First, you have to install the PKCS #11 Engine Plugin for OpenSSL. You can build it from source, or install it from your package manager.

On a Debian and friends, you can install it with the libengine-pkcs11-openssl package; on a Fedora and friends, you can install it with the openssl-pkcs11 package. The following command will output the engine’s name if installed:

Make sure you’ve also installed the YKCS11 library (as described at the beginning of the PIV section).

You can test that the engine and the YKCS11 library have been installed correctly and can access your PIV keys by running the following commands to sign a test file:

Replace /usr/lib/x86_64-linux-gnu/libykcs11.so.2 with the actual path to your YKCS11 library if different. The Private key for Retired Key 1 text in the command is the label for private key of slot 82. Many PKCS #11 clients, such as the OpenSSL plugin, refer to keys by label (aka key alias), rather than by slot number. You can look up the label for each PIV slot in the “Key Alias per Slot and Object Type” table of the YKCS11 Functions and values documentation.

The sign command should prompt you for your PIV PIN; enter it, then touch your YubiKey when it starts blinking:

This command will output a test.sig file. You can verify the signature using the key1-82.pub file that was output when you generated the key earlier:

To generate a simple root CA cert with key 82, run the following command:

Enter your PIN when prompted:

Then enter the default components for the subject DN of the new cert when prompted:

At the end of this process, your YubiKey will start to blink; touch it, and the new CA cert will be output to the file key1-82.crt.

Now import this new cert into the certificate slot for key 82 on your YubiKey with the following command:

Enter your PIN when prompted, then touch your YubiKey:

You can export this certificate at any time from your YubiKey by running the following command:

To sign someone else’s key with this CA, first have the holder of the other key generate a CSR with their key and provide it to you. For example, say your co-worker Bob generates a new private key and CSR with the following commands:

He’d provide the output file, bob.csr to you; from which you now can produce a signed certificate with your CA.

With a real CA, you’d have a custom OpenSSL config file and directory structure set up; but for this simple example, we’ll use OpenSSL’s default “demoCA” config and directory structure. Create the following directories and files:

Then you can sign Bob’s CSR with the following command:

Enter the PIV PIN when prompted:

OpenSSL will print the details of Bob’s CSR for you to review:

If that looks OK, enter y at the prompt; then your YubiKey will start blinking — touch it to sign the new certificate. OpenSSL will then prompt you to update the “database” files in the demoCA folder; enter y again:

The new certificate will be saved as with a file name matching its serial number — in this case, 01.pem. Give this file back to Bob. You (or anyone else with your public CA cert, key1-82.crt) can verify that it’s been signed by your private key by running the following command:

The YubiKey FIDO application allows you to generate a bunch of signing key-pairs, where the private key of the signing key-pair is accessible only to the YubiKey (each key pair, plus the metadata about it, comprise a FIDO credential). Each individual key-pair is intended to be used for one single purpose in coordination with one other single party (that party is called the “relying party”, aka RP). You use the private key of the key pair; the relying party uses the public key.

These key pairs come in two varieties: one variety is stored on the YubiKey itself, called “resident credentials” (aka “discoverable credentials”); and the other variety (non-resident credentials) is stored outside of the YubiKey, by the relying party. Even though the relying party stores the private key of non-resident credentials, it does not have access to use the private key — the private key is always exported in encrypted form, encrypted by a secret master key held by the YubiKey itself. Therefore, only the YubiKey can use the credential’s private key (and only when the credential is remembered and supplied by the relying party).

U2F (“FIDO 1.0”) supported only non-resident credentials; whereas FIDO2 supports both resident and non-resident credentials. Your YubiKey can store up to 25 resident credentials — but it can generate an infinite number of non-resident credentials. Resident credentials are primarily intended for use as WebAuthn Passkeys (where the FIDO credential is used as the primary, and often only, factor), as this allows a website to avoid publicly leaking the Passkeys it has stored.

With WebAuthn, non-resident credentials are generally expected to be used only for 2FA, where a website first requires a user to authenticate by some other means (like a password); and only if the first factor is successful will the website supply the user’s stored FIDO credentials to allow the user to attempt 2FA with them. However, with other applications like SSH or PAM, where enumerating users by username is not possible or not a concern, non-resident credentials are fine for use as the primary authentication factor.

You should set the PIN for the FIDO application, which will allow you to list and delete resident credentials (important since the YubiKey can hold only 25 of them). Before setting your PIN, the ykman CLI will display the following when you query the state of the FIDO app:

Run the following command to set your FIDO PIN:

The PIN must be between 4 and 64 characters. Don’t use a number — instead use a simple passphrase (in the “correct horse battery staple” vein) that’s at least 4 characters long and easy to type. Make sure it’s different than any other PIN or passphrase you’ve ever used before (including the OpenPGP or PIV PINs you set for this YubiKey). See the tip in the OpenPGP section for how to generate a good, random PIN.

Enter your new PIN when prompted, and then repeat it:

Write down your FIDO PIN on the same piece of paper you wrote down your OpenPGP and PIV PINs (be sure to note that it’s for the YubiKey’s FIDO application, as each application uses an independent set of PINs or passwords).

Once you’ve set your FIDO PIN, the ykman CLI will display this when you query the state of the FIDO app:

FIDO can be used to generate SSH authentication keys. You can in fact generate an infinite number of non-resident FIDO SSH keys, one for each host to which you connect via SSH (or you can generate just a single SSH key, and use it for all hosts).

You need to be running at least OpenSSH 8.2 on both client and server in order to use FIDO SSH keys. Run the following command to check your SSH client version:

Run the following ssh-keygen command to generate a non-resident key that your SSH client will present by default to all SSH servers:

Enter your FIDO PIN when prompted, then touch your YubiKey:

Like your other SSH keys, enter a strong, unique passphrase for it (use your password manager to generate and store a random password for the SSH key):

Copy the contents of the newly generated id_ed25519_sk.pub file:

And paste it in as a new line into the ~/.ssh/authorized_keys file on every remote host with which you want to use this SSH key (or use the ssh-copy-id command as a shortcut for every remote host to which you already have SSH access).

When you SSH into a host (for example, bastion.example.com) using this new SSH key, you’ll be prompted to enter the passphrase for the SSH key:

And then you’ll be prompted to touch your YubiKey:

If you’re using an SSH agent to cache your SSH credentials, you won’t have to enter the SSH key’s passphrase on subsequent log-ins (for as long as the key is cached) — you’ll just have to touch your YubiKey when it blinks:

To generate additional SSH keys, specify a custom private-key file (and optionally a custom comment to store in the public-key file). For example, I might run the following command to generate an SSH key specifically for the production SSH bastion host:

The -f option specifies the path at which to save the new private-key file (a .pub extension will be appended to this path for the public-key file), and the -C option specifies a new comment to store in the public-key file.

Copy the content of the ~/.ssh/bastion_key1.pub file, and paste it into the ~/.ssh/authorized_keys file on the host. Then you can SSH into the host by specifying the path to the private-key file via the -i option:

FIDO can be used to log into your local computer, or to run sudo commands on your local computer (or generally anything that uses PAM for authentication on your local computer) — either as a second factor, or as the only factor. You need to have the pam-u2f library installed on your computer in order to use FIDO PAM keys.

On Debian and friends, install the libpam-u2f and pamu2fcfg packages:

Or on Fedora and friends, install the pam-u2f and pamu2fcfg packages:

Then run the following pamu2fcfg command to generate a non-resident key that can be used for PAM:

The --type flag specifies the key type and algorithm (ie EdDSA vs conventional ECDSA vs RSA), and the --origin flag specifies the name of the host on which the key can be used. You don’t need to use the literal hostname of the computer in the origin string, but it must begin with the prefix pam://.

Enter the FIDO PIN when prompted, then touch your YubiKey:

Create a new /etc/u2f_mappings file as root on your local computer, and copy and paste the output of the above command (beginning with your username) into the file.

Next, edit the /etc/pam.d/sudo file as root. Add the following line to the top of it (but keep the rest of the file intact!):

Change the origin flag in the above example to match exactly the origin string you used when you generated your FIDO PAM keys (pam://mylaptop in this example).

Save the file — but don’t quit your editor yet! Test it by running sudo in a new terminal, like the following:

If all goes well, you should see a bunch of debug output sent to your terminal, and your YubiKey should start blinking:

Touch your YubiKey, watch more debug output scroll by, and you should at the end of the process see your test command execute successfully:

If the test command was successful, remove the debug flag from the end of the line in your /etc/pam.d/sudo file:

The above PAM control value sufficient allows your YubiKey to act as an optional primary factor for sudo authentication. If you fail to touch your YubiKey (or if it’s unplugged), you can still use your user account password for sudo authentication — and if you do touch your YubiKey, you won’t have to enter your password.

To configure sudo to use your YubiKey as a mandatory second factor, change the sufficient control value to requisite:

Now if you run a test sudo command, like the following:

First your YubiKey will blink, and the command will pause until you touch it; then you’ll be prompted for your user account password:

And then, once you enter your password, the test command will run:

If you don’t touch your YubiKey, or you don’t have it plugged in, you won’t be able to run any sudo commands.

You can apply the same configuration line to the various other files in your /etc/pam.d sudo directory to enable the use of your YubiKey as a second factor (or primary factor) for various other services (such as to log into your desktop environment).

You can delete any of the resident credentials stored on your YubiKey by first running the following command to look up the first few hex digits of the credential’s ID:

Specify the first few digits of the credential’s ID as the last argument to the following command to delete it:

Enter your FIDO PIN, and then y to confirm:

The credential will be permanently revoked, and impossible to use again:

You can’t delete any of the non-resident credentials you have created (since they are stored by the relying party). As long as the relying party continues to store the credential, it can always ask you (or whoever holds your YubiKey and knows its FIDO PIN) to use the credential sometime in the future.

The only way to fully revoke your non-resident credentials is to reset the FIDO app on your YubiKey. Not only will this delete all your resident credentials, but it will also wipe the secret master key needed to decrypt and use your existing FIDO credentials — both resident and non-resident:

The one set-up step you should take before using this app is to set a password for the app. Once set, your YubiKey will require this password to add or delete secrets, as well as to generate 2FA codes.

Run the following command to set a new OATH password:

There are no size or character constraints on this password. However, unlike the PINs of other YubiKey apps, there is no maximum limit on the number of consecutive wrong attempts an adversary can make — if given unfettered access to your YubiKey, an adversary would be limited only by the YubiKey hardware’s ability to process password attempts, allowing around 100,000 password attempts per day.

Therefore you should use a reasonably strong password of the “correct horse battery staple” variety.

Enter your new password at the prompt, and then repeat it for confirmation:

Write down the password on the same piece of paper where you wrote down your OpenPGP PIN and other YubiKey passphrases.

When you set up 2FA for a website using TOTP, the website usually will present you with a QR code to scan. This QR code embeds the TOTP secret (as well as some related metadata, such as the website’s name and your username on it). If the website also shows the secret itself (which will be a 32-character code like ABCDEFGHIJKLMNOPQRSTUVWXYZ234567), you can copy that secret and add it to your YubiKey OATH app via the ykman CLI.

Run the following command to save the secret in your YubiKey OATH app:

The --touch flag adds the requirement to touch your YubiKey whenever you want to generate a 2FA code from the secret. The secret will be stored using a combination of issuer (example.com in the above example) and username (justin above).

Enter the new secret when prompted, and then enter your OATH password:

You can view all the accounts for which you’ve stored secrets by running the following command:

When prompted, enter your OATH password:

All stored OATH accounts will be listed, each formatted with the issuer name, a colon, and then the account username:

You can generate a 2FA code for any account that matches a unique string from this list (like jl123) by running the following command:

Enter your OATH password and touch your YubiKey when prompted, and the matching account will be listed, along with the current 2FA code for the account:

Enter the code shown in the command’s output (904875 in the above example) into the website’s 2FA challenge form.

To set up OTP slot 1 to use a static secret, run the following command:

This will generate a random 38-character password (using Yubico’s custom modhex encoding by default), and store it in slot 1.

To view the password, enter the following command, and then press the YubiKey until it starts emitting text:

To protect a slot with an access code (after the slot has been configured with a secret), run the following command:

The above sets the access code for slot 1 (each slot has a separate access code). The access code must be 12 hex digits. You’ll only need it if you want to change the secret (or other config settings) of slot 1, or to delete the secret.

Enter the new access code once, then again, and then enter y to confirm:

The “existing settings will be overwritten” warning doesn’t apply to the secret itself, but to the other options that can be specified with the settings command:

Write down the access code (along with the slot number) on the same piece of paper on which you wrote your OpenPGP PINs. You’ll need it later if you want to overwrite the secret with something else (or delete it).

For example, to delete the secret in slot 1 now, run the following command:

If you don’t specify the --access-code option, the command will fail with an error. Supplying - to the --access-code option will cause the command to prompt for the access code. Enter it when prompted:

The slot’s secret (as well as the slot’s configuration settings, including access code), will be wiped from the YubiKey.

Make sure you write down all the PINs and passphrases that you use for your YubiKey’s apps on a piece of paper. (This same information is a good candidate to store in your password manager — but you may not be able to access your password manager without first having to enter one the very PINs that you have forgotten.)

Apply the same “rule of threes” that you use for other backups to paper copies of your PINs: Keep three copies, with at least one copy at a different geographical location than the other two. You will also want to have at least one copy near at hand to where you usually work, so you can refer to it easily whenever you need to enter a PIN that you’ve forgotten.

Here’s an example of what you should have written down: