drduh/yubikey-guide

Guide to using YubiKey for GnuPG and SSH

yubikey-guide's Issues

GPG can't read card

I'm trying to get the WSL integration working and everything seems to be in place but I'm not reading any identities with ssh-add and when I try gpg --card-status I get:
gpg: WARNING: program may create a core file!

and it just hangs there forever.

Any ideas on what I could try?

test issue

"Key does not match the card's capability" on Yubikey Neo - not just a 4096/2048 issue

I encountered this error even though I knew to select 2048 bit keys. The version of gpg I have is 1.4.20 - and if I switch to using gpg2 (version 2.1.11) the keys save correctly.

Temporary working directory should be RAMFS

It is safer to use ramfs when creating the working directory because it will never be swapped to disk, unlike tmpfs etc.

yubikey4 with openpgp decrption

Hi, I'm a new user of yubikey 4 from Chinese student. I mainly use the opengpg function, but I have a question about the process of decryption is inside yubikey?

Q: Storing backup disk image in the cloud

First of all, thank you for this document, it's awesome.

In the guide, you write:

Important The master key should be kept offline at all times and only accessed to revoke or issue new sub-keys.

I intend to back the secret keys up to a USB drive on a LUKS-encrypted partition as you describe. I then plan on taking an image of that drive (with dd, for example) and backing it up to the cloud (AES encrypted, FWIW).

I take your statement to mean that the master key should only ever be decrypted in a live CD environment without an Internet connection. But storing an image of the backup drive in the cloud as I plan to do should be fine.

Does that make sense? Am I missing something and incurring risk?

Cannot add new identities with offline secret key

Say that you have a GPG key generated as per the instructions. If you want to add any additional email addresses (i.e. you want both [email protected] and [email protected], to make Github email verification of the GPG keys easier) then you MUST specify adduid when you have the secret key material available -- i.e. before you move everything to the card and use it.

It would be good to add a "add additional identities" before the "Using GPG keys" section.

ssh-add -L provides unexplained output

https://github.com/drduh/YubiKey-Guide#copy-public-key-to-server has the following text:

Copy public key to server

Copy and paste the following output to the server authorized keys file:

$ ssh-add -L
ssh-rsa AAAAB4NzaC1yc2EAAAADAQABAAACAz[...]zreOKM+HwpkHzcy9DQcVG2Nw== cardno:000605553211

It's not explained how ssh-add uses -L to show the public key: something like http://unix.stackexchange.com/a/82494 would help.

Sometimes prompted for password rather than PIN

Thank you for this guide!

I use the setup described in this guide at work and at home. At work, I'm prompted for the smartcard PIN and everything works fine. At home, more often than not I am prompted for the passphrase rather than the PIN. I followed the guide to generate a long, random passphrase so this means I am prompted for something I don't have in my limited memory.

Does anyone know why I would be prompted for the passphrase rather than the PIN?

I do use the recommended .bashrc lines to set GPG_TTY and call gpg-connect-agent updatestartuptty /bye. Both systems are Debian testing.

Thanks.

Extra encryption key generated

When I generated the master key, an extra encryption key was generated, offsetting all the key numbers near the end by 1.

gpg2 for Yubikey 4

Great guide, but I found that I was unable to sign git commits using the signing key unless I repeated all these steps using gpg2 (and set gpg2 as the default program in .gitconfig), as recommended by the official docs (https://www.yubico.com/support/knowledge-base/categories/articles/use-yubikey-openpgp/).

ECC partly for key creation instead of RSA.

I was wondering about the selection for encryption keys on the creation part of the tutorial. Isn't it a better idea to recommend here ECC keys instead of RSA? There is a lot of discussion I remember about RSA which is going to be kind of deprecated. Honestly, I have to research it again, but my gut tells me it makes more sense. Is there a good reason, not to do it?

coexistence with keychain

at first: thanks for that cool howto, very helpful!

I am on Fedora 28 and use keychain in my .bashrc
Now I have in my configfile:

# if keychain is used:                                                                                                                                                           
eval $(keychain --eval -Q --agents gpg,ssh --quiet id_ed25519 id_rsa)                                                                                                            
                                                                                                                                                                                 
# enable ssh to read keys from gpg-agent                                                                                                                                         
#export SSH_AUTH_SOCK=~/.gnupg/S.gpg-agent.ssh                                                                                                                                   
#                                                                                                                                                                                
export GPG_TTY="$(tty)"                                                                                                                                                          
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"                                                                                                                      
gpg-connect-agent updatestartuptty /bye

and "ssh-add -L" only lists my id_rsa.pub, but not my (second) id_ed25519.pub (but yes, the key on the yubikey is listed).

How to set that up to have all 3 keys available?
Does it make sense to change the start order of the agents/keychain?

I will test some things ... thanks!

Windows key export command

The mention windows command for exporting the keys didn't work for me using powershell or cmd.
The command should be the same as the Linux command using a ">" instead of "-o".

Just for your information.

Regards,
joko

Mention key linting in generate keys section

From https://riseup.net/en/security/message-security/openpgp/best-practices#openpgp-key-checks

Should mention that after generating GPG keys, should be checked with tool:

sudo apt-get install hopenpgp-tools
hkt export-pubkeys '<fingerprint>' | hokey lint

gpg.conf does not include default-recipient-self

Similar to previous issue, https://github.com/drduh/YubiKey-Guide#create-gpg-configuration should have

default-recipient-self
default-key $KEYID

https://www.gnupg.org/gph/en/manual/r1235.html

Renewing subkeys not covered

Recently my subkeys expired and working through how to properly update these keys proved a little trickier than expected. I've taken some detailed notes, but before submitting a PR I wanted to know if that is something that people would find useful and/or if it belongs in this guide?

Thanks so much again for making this resource available, its greatly improved my security posture and understanding of GPG and Yubikeys. 🙇

Describe Yubikey card status if public key not imported

In section https://github.com/drduh/YubiKey-Guide#insert-yubikey

Should mention that if you did NOT import the public key for the key card, you will see

General key info..: [none]

It's only when you have the public key available that the Yubikey 4 will show that info.

Using two yubikeys not covered under guide

So, this might require more feedback, as am currently flummoxed.

If you want to use a Yubikey for Windows / MacOS / Linux login as part of a multi-factor authentication, then Yubico advises having a second Yubikey as backup. This works fine, since I can use a Yubikey Nano for the Macbook Pro, and leave the desktop one plugged in.

However, if you try copying the GPG secret key and subkeys onto a second Yubikey, "keytocard" will not let you. You'll get "secret key already stored on a card" and other similar warnings. Is it not a good idea to use two Yubikeys?

Two Yubikeys with unique subkeys are causing conflict

I have 2 Yubikey 5Cs.

I followed the guide creating a master key pair. Then I created six subkeys (S E A) and put 3 of each on two Yubikeys.

When I got to the part where it asked me to encrypt and decrypt a message I put in my backup Yubikey first. It decrypted the message successfully.

When I put in my regular Yubikey and tried to decrypt the message I got an error "Please insert the card with serial number xxxxx".

Does anyone know how to resolve this issue?

Specify "default-key" in gpg.conf

Examples should specify default key in gpg.conf, in full fingerprint mode rather than specifying it on the command line. Specifying it on the command line means people without coffee will (incorrectly) copy and paste without checking the key id is correct.

echo "default-key <myfingerprint>" >> ~/.gnupg/gpg.conf

Error when attempting to disable OTP via USB

I only use YubiKeys for GPG. Since OTP via YubiKey isn't supported in Firefox or Safari as of this writing I don't use it. Unfortunately when I attempt to disable OTP via USB it throws this error.

$ ykman config usb --disable OTC
Usage: ykman [OPTIONS] COMMAND [ARGS]...

Error: No PyUSB backend detected!

I tried to follow the instructions at the bottom of the README to disable it but failed. After much internet searching I'm still at a loss on how to disable OTC via USB (I keep accidentally touching the YubiKey and it prints all those characters and it's driving me mad!)

I was hoping you could update the README with instructions on how to turn this off that won't cause this error.

Addition for MacOS Section

Mac users should also brew install ykman if they want to be able to use the ykman openpgp x commands. Might as well throw in the brew install pinentry-mac towards the top there with the rest of the install commands.

Might consider telling users that an expected change when using the yubikey will be the need to enter the PUK for common operations like signing instead of the master key passphrase.

Good guide: But it should be implemented in used friendly software

Please don't see this as a rant - I really appreciate that good, detailed and working guides like this are around.

But the real major issue (which the author of this guide is not to blame for) with pgp / email encryption and such things as the yubikey is the "user-experience", which is just horrible. The yubikey is a good step forward in many things, but implementing / using the smart-card function as it is now is something only a few nerds and power users will do.

What we really need is to obsolete such guides by making it easy and intuitive to use the yubikey for pgp keys from kleopatra and other key management software. This is when we will see more adoption.

Broken command for sending key to specific public key server

In the section https://github.com/drduh/YubiKey-Guide#export-public-key I ran into an issue when using the example command for sending the public key to a specific public key server host:

gpg --send-key $KEYID --keyserver pgp.mit.edu
gpg: Note: '--keyserver' is not considered an option
gpg: "--keyserver" not a key ID: skipping
gpg: "pgp.mit.edu" not a key ID: skipping
gpg: sending key 0x90F75EF0DED58298 to hkps://hkps.pool.sks-keyservers.net

I wonder if this is an issue with newer version of GPG perhaps. This may not be an issue for others. It did work when I ran this instead: gpg --send-key --keyserver pgp.mit.edu $KEYID.

gpg.conf does not include require-cross-certification

The gpg.conf file is missing a couple of things:

https://github.com/drduh/YubiKey-Guide#create-gpg-configuration

This does not include the require-cross-certification option

# When verifying a signature made from a subkey, ensure that the cross
# certification "back signature" on the subkey is present and valid.
# This protects against a subtle attack against subkeys that can sign.
# Defaults to --no-require-cross-certification.  However for new
# installations it should be enabled.

require-cross-certification

Generate Keys on Yubikey

Hi!

Just a suggestion -- maybe mention the possibility of generating keys directly on the Yubikey?

As noted in the support article, this does come with limitations -- e.g. you can never backup the keys. But this is also part of the point of generating keys on the YubiKey: you can never backup the keys... meaning they never exist anywhere else at any time (e.g. even in memory while you're generating the keys and before you transfer them to the Yubikey).

Part of the beauty of hardware cryptography (whether a smart card or a Yubikey) is the very ability to have keys that only exist on that device and cannot be retrieved. (And further, having strong locking policies that cause the device to erase or destroy itself if a PIN/PUK is entered too many times incorrectly.)

Just a thought :)

https://support.yubico.com/support/solutions/articles/15000006420-using-your-yubikey-with-openpgp#Generating_Your_PGP_Key_Directly_on_Your_YubiKey8gpnr

Troubleshooting should include guide to using USB correctly

Troubleshooting: "Yubikey core error: no yubikey present" should also mention turning the yubikey around so it's facing the right way.

Paper backup instructions and pitfalls

@drduh, would you mind including instructions on best practices to perform a secure backup of the master key on paper? Would be wise to also store a copy of the subkeys (S E A) stored on the yubikey? How hard would it be to password-protect them with a different password?

Use secure location for GNUPGHOME

Maybe instead of local temp directory (and later backup/secure delete) use safe storage from the start? "Safe storage" can be encrypted USB (prepared according to the guide) or hardware-encrypted external drive.

Just start the guide with Prepare safe storage location (now named Backup everything) and then use it:

$ export GNUPGHOME=$(mktemp -d -p /path/to/safe/storage); echo $GNUPGHOME

You will still need to create backup copy before moving keys to card but it will be as simple as using tar in place. But "secure delete" will not be required anymore.

Suggestions

Two suggestions:

1. If you want to add your keys to multiple yubikeys you will need to restore a copy of your backup and repeat the process. This would have been nice if it was mentioned in the guide.
2. The guide should also show how to add multiple identities. Often times with version control systems your primary email for the version control system must be in the key or you will get an "Unverified " badge on commit signing. This should be addressed in the guide.

Primary key paper backup guide

Hello! Thank you for writing this detailed guide. I see that paperkey is mentioned in the backup section:

Also consider using a paper copy of the keys as an additional backup measure.

It would be wonderful if the guide had a detailed section about this. It is easy to export and print secret keys for offline storage but it is not so obvious how to get them back online. Given the importance of the primary key, I think it is important to know how to correctly restore and test the backup in order to prevent accidental loss of the key.

Cannot sign keys without offline secret key

If you are creating new GPG key for a Yubikey Nano, you need to have the master key available. You cannot sign with the "signing" or "authentication" key.

This means in the guide, if you've got hold of a new Yubikey, you need to have the secret key material for both keys available in order to bring the new GPG key and Yubikey fully online.

Per http://forum.yubico.com/viewtopic.php?p=8911&sid=f0304ff17fcd6863f7ee3db99a8bd7dc#p8911

[b]EDIT: Final note: only a key with the C(ertification) usage can be used to sign keys (including the signature required to extend the expiry or add new subkeys), and per RFC 4880, only the master key should be permitted to Certify. This means that you will need to use the backup in order to perform those actions or sign other people's keys. This is feasible because, in general, these activities are relatively rare. A more secure setup would involve the use of a second token (such as yubikey) in which you store the master key, so that your master is not exposed when you need to use it (in theory it would take destructive methods and probably a SEM to extract the secret key from the secure module, and let's be honest, that means your adversary is a government, in which case they've got far more effective methods of getting you to turn it over, and you've got far bigger problems than losing your keys).

hkt ignores custom GPG path ($GNUPGHOME)

Which makes the linting useless and not working

Git cannot access SSH Key

Hi,

Steps to reproduce:

• Reboot
• Log in
• Open Terminal, cd into Repo
• Plug In Yubikey
• git pull

Result:

[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Git somehow does not recognize the key. Nevertheless, it is visible by ssh-add -l.

I can get Git to know about the key by e.g. using pass. Once I have unlocked my Yubikey with pinentry via pass, I can make git pull

Any Ideas why?

For Frodo!

keytocard: Key does not match the card's capability.

When I try run the command
gpg> keytocard
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]

Please select where to store the key:
(1) Signature key
(3) Authentication key
Your selection? 1
Key does not match the card's capability.
Your selection?

I get this error.

I did a search on this and according to this article (link below in quotes) the error is a result of keysize apparently.

"http://forum.yubico.com/viewtopic.php?f=26&t=1832&p=7191&hilit=keytocard#p7191"

The article says that Yubikey only allows 2048 keysize. However it seems 4096 worked for you.

Please help. Also please know, I am very noobish with gpg and advanced yubikey configuration.

Probably a simple explanations/fix

Thanks

Difficulty with Windows integration

I followed the tutorial carefully and even then when I try to use SSH with a program other than PuTTY nothing works.

The image below shows me using SSH in 3 programs. Has anyone ever experienced this? Do you know how to solve it?

gpg-agent with OpenSSH_7.6p1

When using the gpg-agent as describen on macOS High Sierra with OpenSSH_7.6p1 it fails with

error fetching identities: Invalid key length

Any idea how to fix this?

revoke.txt not found

In https://github.com/drduh/YubiKey-Guide#backup-keys "Backup all GPG files to it:" file revoke.txt mentioned, but actually, file located in dir openpgp-revocs.d:

gpg: revocation certificate stored as '/tmp.FLZC0xcM/openpgp-revocs.d/011CE16BD45B27A55BA8776DFF3E7D88647EBCDB.rev'

Some warnings on gpg import

gpg: WARNING: unsafe permissions on homedir '/home/stu/.gnupg'
gpg: keyserver option 'ca-cert-file' is obsolete; please use 'hkp-cacert' in dirmngr.conf
gpg: keyserver option 'debug' is unknown
gpg: keyserver option 'verbose' is unknown
gpg: key 0x238694028858ED5A: public key "Stuart Axon <[email protected]>" imported
gpg: Total number processed: 1
gpg:               imported: 1

Windows ssh-add -L replacment

I am trying to get my ssh key with ssh-add -L but I am unable to do this. I am getting the agent has no identities. Then I changed my gpg agent to use putty and i exported my key with gpg --export-ssh-key but I get key with end opengpg which is different then cardno as in example. I change manually key to cardno:..... (of course i changed number to card number) and uploaded to github but I am getting error:

How to sign third party keys?

I cannot "trust" third party pgp keys because trusting them needs signature which is only possible with the offline master key. I do not want to bring the master key hot for every signature that I plan to make. Is there a workaround?

Download from keyserver requires gnupg-curl on Linux

Uname is: "4.4.0-36-generic #55-Ubuntu SMP Thu Aug 11 18:01:55 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux"

In the section https://github.com/drduh/YubiKey-Guide#import-public-key

There's a bit where you're supposed to use the key

 gpg --recv

When I tried this, I got the following error:

gpgkeys: HTTP fetch error 1: unsupported protocol
gpg: no valid OpenPGP data found.

I fixed this error by installing a special version of curl:

sudo apt-get install gnupg-curl

after which everything worked fine.

minimal GPG/SSH for OSX (fish)

brew install gpg pinentry-mac ykman
ykman mode "CCID"
gpg --card-edit
> admin

# change card pin
> passwd
> 1

# change admin password
> passwd
> 3

# generate keys
> generate

# exit
> quit

tee ~/.config/fish/conf.d/gnupg.fish <<EOF
# Start or re-use a gpg-agent.
gpgconf --launch gpg-agent

# Ensure that GPG Agent is used as the SSH agent
set -xg SSH_AUTH_SOCK ~/.gnupg/S.gpg-agent.ssh

EOF
tee ~/.gnupg/gpg-agent.conf <<EOF
pinentry-program /usr/local/bin/pinentry-mac
enable-ssh-support

EOF

command + t for new terminal

Is the keyserver CA file still required?

The documentation here indicates this step isn't required for gpg versions 2.1.11 and newer. Is this step still required?

Best way to trigger prompt for pin?

Thanks to this guide, I am now using my yubikey-based GPG credentials for encryption, signing and ssh. I've noticed that inserting the Yubikey and attempting to ssh does not trigger gpg-agent to prompt me for a pin though. Explicitly gpg-based operations like decryption do prompt me, so I have resulted to doing gpg -d dummy.gpg after inserting the card in order to get the pin prompt (which gpg agent then caches for the configured amount of time).

• Am I doing something wrong that is preventing ssh requests from triggering a request for my pin? Any pointers to fix that?
• Also, is there a more generic way to ping the opengpg card to prompt me for a pin, rather than running a dummy decryption or signing request?

Thanks!

Automatic primary key generation script

I wrote a bash script that automatically generates a 4096 bit RSA certification key in batch mode. The new key does not expire and has sensible algorithm and keyserver preferences. Automation can prevent mistakes and make things easy and reproducible.

Do you think something like this is a good fit for the guide? I think this is more user friendly compared to navigating menus. The current version of my script obtains user credentials from git but I could make it so that it prompts the user instead.

It is also possible to generate primary and subordinate keys with a few commands:

algo=rsa4096
uid='name <email>'
expire=0

gpg --batch --quick-generate-key "$uid" $algo cert $expire

# FPR should be set to the fingerprint of the key generated above.
# Maybe gpg --list-keys --with-colons can help automate this.

for cap in sign encrypt auth; do
  gpg --batch --quick-add-key $FPR $algo $cap $expire
done

Update Request

Is this information still accurate after two years?

Also, could there be a section on getting SSH authentication to work with Putty and Git Bash. I've been fighting that for nearly two weeks now with no luck.

Thanks for putting this together. I originally used Simon Josefsson's blog post that you referenced but your information seemed more up-to-date the last time I needed to do it. I know this is a moving target and I'd be willing to help test any of the steps. I'd also be willing to help script some of it if you think we could automate the process.

Edit uid after moving private key to yubikey

Thank you for this guide. I followed it and got a basic setup working. I'm trying to add a uid to my key with --edit-key, but I keep seeing "Need the secret key to do this." Is there something simple that I am missing?

Agent Forwarding

This is a fantastic guide, thanks!

The only area that I couldn't successfully follow was regarding the configuration in the section on agent forwarding to use my gpg (and ssh authentication) on remote machines. IIUC, your guide suggests this should work merely by including the -A flag in the ssh command. Following the gpg wiki I found I had to look up my local extra socket, gpgconf --list-dirs agent-extra-socket, look up my remote socket, gpgconf --list-dirs agent-socket, and add RemoteForward <remote socket> <extra-socket> to my ~/.ssh/config, and also add extra-socket (and fix my pinentry-program line) in ~/.gnupg/gpg-agent.conf. On the remote host, I had to import my public key first, and add StreamLocalBindUnlink yes in /etc/ssh/sshd_config and re-load the config (something you cover in the previous section but seemingly only for some Windows-only tool). After that I could decrypt from a remote host.

Not sure if there is a way to get this to work without needing root access on the remote machine.
(In my experiment I also needed to reboot the remote machine first, though probably that could be avoided by using some appropriate service reload commands.... Also would need further steps to enable the ssh from the remote machine, probably similar to what you already document for the local machine(?)

Is there a better way than the above, e.g. that lets you get this to work with just ForwardAgent yes and not mucking around for sockets? Is this something you would consider extending in the guide, or would entertain a PR for?