drduh / yubikey-guide Goto Github PK
View Code? Open in Web Editor NEWGuide to using YubiKey for GnuPG and SSH
Home Page: http://drduh.github.io/YubiKey-Guide/
License: MIT License
Guide to using YubiKey for GnuPG and SSH
Home Page: http://drduh.github.io/YubiKey-Guide/
License: MIT License
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?
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.
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.
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).
When I generated the master key, an extra encryption key was generated, offsetting all the key numbers near the end by 1.
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.
It is safer to use ramfs when creating the working directory because it will never be swapped to disk, unlike tmpfs etc.
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.
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
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?
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).
Thanks!
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.
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.
@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?
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
Two suggestions:
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.
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.
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.
Hi,
Steps to reproduce:
cd
into Repogit 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!
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
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?
The documentation here indicates this step isn't required for gpg versions 2.1.11 and newer. Is this step still required?
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?
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/).
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!
Troubleshooting: "Yubikey core error: no yubikey present" should also mention turning the yubikey around so it's facing the right way.
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 :)
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?
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?
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?
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'
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
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
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. ๐
Similar to previous issue, https://github.com/drduh/YubiKey-Guide#create-gpg-configuration should have
default-recipient-self
default-key $KEYID
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?
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
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
.
Which makes the linting useless and not working
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?
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.
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.
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?
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.
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
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:
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.