Table of contents
- Summary
- Estimated burden and prerequisites
- GPG
- git
- U2F
- SSH
- Keybase
- VMware Fusion
- Docker Content Trust
- Troubleshooting
- TODO
- Acknowledgements
- References
GPG is useful for authenticating yourself over SSH and / or GPG-signing your git commits / tags. However, without hardware like the YubiKey, you would typically keep your GPG private subkeys in "plain view" on your machine, even if encrypted. That is, attackers who personally target [1, 2, 3, 4] you can compromise your machine can exfiltrate your (encrypted) private key, and your passphrase, in order to pretend to be you.
Instead, this setup lets you store your private subkeys on your YubiKey. Actually, it gives you much stronger guarantees: you cannot authenticate over SSH and / or sign GPG commits / tags without: (1) your YubiKey plugged in and operational, (2) your YubiKey PIN, and (3) touching your YubiKey. So, even if there is malware trying to get you to sign, encrypt, or authenticate something, you would almost certainly notice, because your YubiKey will flash, asking for your attention. (There is the "time of check to time of use" issue, but that is out of our scope.)
About 2-3 hours. 15 minutes could save you 15% or more on cybersecurity
insurance.
You will need macOS, Homebrew, a password manager, and a YubiKey 5.
Please read and follow all of the instructions carefully.
$ ./gpg.sh
(Protip: set TEMPDIR=1
when preparing YubiKey for someone else to avoid
polluting your default GPG homedir.)
STRONGLY RECOMMENDED: signing all your git commits across all repositories.
$ ./git.sh
The script can setup your Git installation so that all your commits and tags will be signed by default with the key contained in the YubiKey. We strongly recommend that you turn on this option. If you have done so, please stop reading here.
Otherwise, one reason for declining this option may be that you wish to sign
for different repositories with different keys. There are a few ways to handle
this. Perhaps the simplest is to let the script assign the YubiKey to all git
repositories, and then use git config --local
to override user.signingkey
for different repositories.
Alternatively, let us say you use your personal key for open source projects, and the one in the YubiKey for Datadog proprietary code. One possible solution is to setup git aliases. First, make sure signing is turned on globally:
git config --global commit.gpgsign true
git config --global tag.forceSignAnnotated true
Then you can tell git to use a specific key by default, depending on which one is the one you use the most:
git config --global user.signingkey <id_of_the_key_you_want_to_use_by_default>
You can alias the commit
command to override the default key and use another
one to sign that specific commit:
git config --global alias.dd-commit '-c user.signingkey=<id_of_the_yubikey_key> commit'
git config --global alias.dd-tag '-c user.signingkey=<id_of_the_yubikey_key> tag'
With this setup, every time you do git commit
or git tag
, the default key
will be used while git dd-commit
and git dd-tag
will use the one in the
YubiKey.
STRONGLY recommended: configure U2F for GitHub and Google.
NOT recommended unless you plan to use your GPG authentication subkey as your only SSH authentication key.
You must have first set up GPG. Then:
$ ./ssh.sh
Optional: verify public key on Keybase. You can now do this using the
command-line option, with only curl
and gpg
, and without installing any
Keybase app, or uploading an encrypted copy of your private key. For example,
see this profile.
Optional: using YubiKey inside GNU/Linux running on VMware Fusion.
-
Shut down your VM, find its .vmx file, edit the file to the add the following line, and then reboot it:
usb.generic.allowHID = "TRUE"
-
Connect your YubiKey to the VM once you have booted and logged in.
-
Install libraries for smart card:
-
Ubuntu 17.10:
apt install scdaemon
-
Fedora 27:
dnf install pcsc-lite pcsc-lite-ccid
-
-
Import your public key (see Step 13).
-
Set ultimate trust for your key (see Step 20).
-
Configure GPG (see Step 22).
-
Test the keys (see Step 23). On Fedora, make sure to replace
gpg
withgpg2
. -
Use the absolutely terrible kludge in Table 5 to make SSH work.
-
Spawn a new shell, and test GitHub SSH (see Step 26).
-
Test Git signing (see Step 28). On Fedora, make sure to replace
gpg
withgpg2
:git config --global gpg.program gpg2
# gpg-ssh hack
gpg-connect-agent killagent /bye
eval $(gpg-agent --daemon --enable-ssh-support --sh)
ssh-add -l
Table 5: Add these lines to ~/.bashrc
.
Optional: using YubiKey to store the root role key for Docker Notary.
-
Assumption: you are running all of the following under Fedora 27.
-
Install prerequisites:
dnf install golang yubico-piv-tool
-
Set GOPATH (make sure to update PATH too), and spawn a new
bash
shell. -
Check out the Notary source code:
go get github.com/theupdateframework/notary
-
Patch source code to point to correct location of shared library on Fedora.
-
cd ~/go/src/go get github.com/theupdateframework/notary
-
git pull https://github.com/trishankatdatadog/notary.git trishank_kuppusamy/fedora-pkcs11
-
-
Build and install the Notary client:
go install -tags pkcs11 github.com/theupdateframework/notary/cmd/notary
-
Add the lines in Table 6 to your
bash
profile, and spawn a new shell. -
Try listing keys (there should be no signing keys as yet):
-
dockernotary key list -D
-
If you see the line
"DEBU[0000] Initialized PKCS11 library /usr/lib64/libykcs11.so.1 and started HSM session"
, then we are in business. -
Otherwise, if you see the line
"DEBU[0000] No yubikey found, using alternative key storage: found library /usr/lib64/libykcs11.so.1, but initialize error pkcs11: 0x6: CKR_FUNCTION_FAILED"
, then you probably need togpgconf --kill scdaemon
(see this issue), and try again.
-
-
Generate the root role key (can be reused across multiple Docker repositories), and export it to both YubiKey, and keep a copy on disk:
-
Choose a strong passphrase.
-
dockernotary key generate -D
-
Commit passphrase to memory and / or offline storage.
-
Try listing keys again, you should now see a copy of the same private key in two places (disk, and YubiKey).
-
Backup private key in
~/.docker/trust/private/KEYID.key
unto offline, encrypted, long-term storage. -
Securely delete this private key on disk.
-
Now if you list the keys again, you should see the private key only on YubiKey.
-
-
Link the yubikey library so that the prebuilt docker client can find it:
sudo ln -s /usr/lib64/libykcs11.so.1 /usr/local/lib/libykcs11.so
-
Later, when you want Docker to use the root role key on your YubiKey:
-
When you push an image, you may have to kill
scdaemon
(in a separate shell) right after Docker pushes, but right before Docker uses the root role key on your YubiKey, and generates a new targets key for the repository. -
Use
docker -D
to find out exactly when to do this. -
This is annoying, but it works.
-
# docker notary stuff
alias dockernotary="notary -s https://notary.docker.io -d ~/.docker/trust"
# always be using content trust
export DOCKER_CONTENT_TRUST=1
Table 6: Add these lines to ~/.bashrc
.
-
If you are blocked out of using GPG because you entered your PIN wrong too many times (3x by default), don’t panic: just follow the instructions here. Make sure you enter your Admin PIN correctly within 3x, otherwise your current keys are blocked, and you must reset your YubiKey to use new keys.
-
Combined with the touch requirement for all signing operations,
git rebase
might require you to touch the YubiKey too many times. A workaround is to pass the--no-gpg-sign
.
-
Instructions for revoking and / or replacing keys.
-
Procedures for recovering from key compromise / theft / loss.
I developed this guide while working at Datadog, in order to use it in various product security efforts. Thanks to Ayaz Badouraly, Arthur Bellal, Forrest Buff, Alex Charrier, Jules Denardou, Ivan DiLernia, Hippolyte Henry, David Huie, Cody Lee, Ofek Lev, Yann Mahé, Cara Marie, Justin Massey, Rishabh Moudgil, Maxime Mouial, Nicholas Muesch, Julien Muetton, Massimiliano Pippi, Thomas Renault, Pratik Guha Sarkar, and Santiago Torres-Arias (NYU), all of whom who were at Datadog (unless specified otherwise), and who helped me to test these instructions.