You bought a YubiKey - now what?
The goal is to outline the steps to configure your YubiKey in a sane method and to use it to maximize your security.
This guide is for users who are comfortable with the command line and various technical jargon.
This is highly opinionated on how you should and should not use your YubiKey but is organized well enough that you should be able to modify if you have a need.
The instructions have been tested on macOS 10.12 (Sierra) with a YubiKey 4 and YubiKey Neo. While there are sections that are OS independent, most of the tricky bits are macOS specific.
To perform these instructions, the YubiKey should be plugged into your computer's USB port.
For ykman cli
brew install ykmanThis will turn off One-Time-Password. Most users will not find OTP useful and will be confused by the random letters that will appear when they accidentally touch the YubiKey.
Exception: LastPass supports OTP and TOTP as a two factor method and does not support U2F. If you plan on using OTP with LastPass, you will want to skip this step. If you choose TOTP (README.md#set-up-your-yubikey-at-totp---a-google-authenticator-replacement) and don't set up OTP, I'd suggest you disable OTP.
> ykman mode
Current connection mode is: OTP+FIDO+CCID
Supported connections are: OTP, FIDO, CCID
> ykman mode "FIDO+CCID"
Set mode of YubiKey to FIDO+CCID? [y/N]: Y
Mode set! You must remove and re-insert your YubiKey for this change to take
effect.Remove and re-insert the YubiKey.
> ykman mode
Current connection mode is: FIDO+CCID
Supported connections are: OTP, FIDO, CCIDFIDO/U2F is the recommended two factor method. It is phishing resistant unlike TOTP/Google Authenticator. It is much harder to compromise than SMS/Voice call methods.
The instructions below are specific to provider, but they are all similar enough.
- Go to your GitHub Security Settings
- Turn on
Two-factor Authenticationif it's not already enabled. You will need to set up either an SMS or TOTP (Google Authenticator) if it's not. - Under
Security keys, chooseRegister new device` - Type in a name:
yourname-yubikey-nano4or something else that will help you remember the key - Click
Add - Follow the instructions on screen - you'll probably need to tap the YubiKey for it to register.
Yubico has more detailed instructions.
- Go to your Google Sign-in & Security page
- Click
Two-step verificationand you may be prompted for your password. - Click
Add Security Keyand follow the on-screen instructions. You may need to tap or touch your YubiKey.
Yubico has a video
- Go to your Dropbox Security Settings
- Under
Security keys, clickAdd - Follow the on-screen instructions. You'll probably be prompted for your password and touch the YubiKey to complete registration.
Yubico has a video and more detailed instructions
Yubico has instructions You can also find a link of all supported Applications/Sites
-
Install GPG2 if you haven't already
Before you being, you'll need to install GPGTools GPG Suite. As you do this, here are a few notes about it:
- Stash the DMG somewhere if you ever need to uninstall it, as an uninstaller is in the DMG package
- After installation completes, you don't need to do anything via the GPG Keychain GUI
- Benefits (versus CLI-only apps): Launches gpg-agent automatically, has a GUI for management and PIN entry, doesn't require Yubikey modes to be changed during GPG setup, still installs the CLI apps
-
Configure your GPG conf at
~/.gnupg/gpg.confSuggested hardened configuration. Here's the minimum that makes sense:
use-agent personal-cipher-preferences AES256 AES192 AES CAST5 personal-digest-preferences SHA512 SHA384 SHA256 SHA224 cert-digest-algo SHA512 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed -
Generate Keys
Note: If you have a YubiKey 4, you should use 4096 as your key length. NEO owners should use 2048 as that is the maximum supported.
> gpg2 --card-edit [truncated...] gpg/card> admin Admin commands are allowed gpg/card> generate Make off-card backup of encryption key? (Y/n) n [PIN Entry pops up, enter 123456, which is the default pin] What keysize do you want for the Signature key? (2048) 4096 [YubiKey NEO max is 2048] [PIN Entry pops up, enter 12345678, which is the default admin pin] The card will now be re-configured to generate a key of 4096 bits What keysize do you want for the Encryption key? (2048) 4096 [YubiKey NEO max is 2048] [PIN Entry pops up, enter 12345678, which is the default admin pin] The card will now be re-configured to generate a key of 4096 bits What keysize do you want for the Authentication key? (2048) 4096 [YubiKey NEO max is 2048] [PIN Entry pops up, enter 12345678, which is the default admin pin] The card will now be re-configured to generate a key of 4096 bits Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) Key does not expire at all Is this correct? (y/N) Y GnuPG needs to construct a user ID to identify your key. Real name: <YOUR_NAME_HERE> Email address: <YOUR_EMAIL_HERE> Comment: You selected this USER-ID: "YOUR_NAME_HERE <YOUR_EMAIL_HERE>" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
The YubiKey will flash as it's creating the key. Mine took about 5 minutes. When complete, it will say something like
gpg: key 00000000 marked as ultimately trusted public and secret key created and signed. [truncated...]
You should change your PIN and Admin PIN. You can do that here with
passwdat thegpg/card>prompt:> gpg --card-edit ...truncated... gpg/card> admin Admin commands are allowed gpg/card> passwd 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? 1 [Enter 123456] [Enter your new PIN] [Enter your new PIN again] PIN changed. 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? 3 [Enter 12345678] [Enter your new Admin PIN] [Enter your new Admin PIN again] PIN changed. 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? Q
-
(Optional) Other GPG Setup
While you're here:
gpg/card> name Cardholder's surname: [Your last name] Cardholder's given name: [Your first name] [Enter your admin PIN] gpg/card> sex Sex ((M)ale, (F)emale or space): [Your gender] gpg/card> lang Language preferences: [Your two letter language code, example: en)
You can see the configuration by typing
liston thegpg/card>prompt.https://www.yubico.com/support/knowledge-base/categories/articles/use-yubikey-openpgp/
You can generate an SSH key from your PGP key and use it for SSH logins.
-
Identify your authentication key.
> gpg2 --card-status | grep Authentication Authentication key: AAAA BBBB CCCC DDDD EEEE FFFF GGGG HHHH IIII JJJJ
-
Generate the SSH Pub key
Take the last 16 digits and pass them to
gpg --export-ssh-key.> gpg --export-ssh-key GGGGHHHHIIIIJJJJ ssh-rsa AAAAG4AFq6wm1eCcRclsVOYcJf8y ... ... G46wm1eCcRclsVOYcJf8yPr1b+kzUpGQLw== -
Copy the public key and add it
~/.ssh/authorized_keysthe machine you want to SSH into -
You'll be using GPG keys as SSH keys, and we'll start by configuring GPG agent by adding the following block into
.gnupg/gpg-agent.conf:pinentry-program /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac enable-ssh-support write-env-file use-standard-socket default-cache-ttl 600 max-cache-ttl 7200
-
add the below block into
~/.bash_profileor~/.zshrc:#gpg-agent daemon export GPG_TTY="$(tty)" export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket) gpgconf --launch gpg-agent
-
Reboot to make sure everything starts up cleanly. Probalby doesn't take that much. But it won't kill you.
-
Verify the ssh-agent has your key from the gpg-agent
ssh-add -L
-
Attempt to login to the machine via SSH
You can have your YubiKey generate TOTP codes, just like Google Authenticator or Authy.
If you use it as a replacement for Google Authenticator, remember that you'll
be unable to get the code if you don't have your YubiKey with you and a
computer with ykman or Yubico Authenticator installed or an Android phone
with Yubico Authenticator installed.
You can also use both a phone based app and a YubiKey, knowing that either device will generate the same codes and will be able to access your account.
-
Choose to enable two factor.
-
Select
Use a mobile app -
Click
enter your secret key manuallyto display a 26 digit long base32 key. Note: The link text will differ by provider. The length of the base32 key may also differ. -
(Optional) If you also want to use your phone, you can scan the barcode or type in the code to
Google Authenticator. -
Copy the key below - don't forget to remove the spaces
% The `-t` will require a touch inorder for codes to be generated. % This prevent malware from generating codes without your knowledge. % YubiKey Neo's do not support this feature. Just remove the `-t` flag. > ykman oath add -t <SERVICE_NAME> <32 DIGIT BASE32 KEY NO SPACES> > ykman oath code <SERVICE_NAME> Touch your YubiKey... SERVICE_NAME 693720
-
Repeat for other providers.
The steps will be similar - the difference will be how to get the manual key instead of the QR code. When the QR code is displayed, there will often be a link to get the code. Here are some examples:
- Dropbox:
Enter your secret key manually - Gmail:
Can't scan it? - Github
Enter this text code
- Dropbox:
I wanted to require a touch any time I tried to use my YubiKey for ssh authentication to prevent rogue processes from using the key while it's plugged in.
You can use the YubiKey Manager CLI to require this; I installed it via Homebrew.
After installed, use the ykman openpgp touch subcommand to configure the touch settings:
$ ykman openpgp set-touch aut on
$ ykman openpgp set-touch enc on
$ ykman openpgp set-touch sig on