This is a guide to using [YubiKey](https://www.yubico.com/products/yubikey-hardware/) as a [SmartCard](https://security.stackexchange.com/questions/38924/how-does-storing-gpg-ssh-private-keys-on-smart-cards-compare-to-plain-usb-drives) for storing GPG encryption, signing and authentication keys, which can also be used for SSH. Many of the principles in this document are applicable to other smart card devices.
Keys stored on YubiKey are [non-exportable](https://support.yubico.com/support/solutions/articles/15000010242-can-i-duplicate-or-back-up-a-yubikey-) (as opposed to file-based keys that are stored on disk) and are convenient for everyday use. Instead of having to remember and enter passphrases to unlock SSH/GPG keys, YubiKey needs only a physical touch after being unlocked with a PIN code. All signing and encryption operations happen on the card, rather than in OS memory.
Keys stored on YubiKey are [non-exportable](https://support.yubico.com/support/solutions/articles/15000010242-can-i-duplicate-or-back-up-a-yubikey-) (as opposed to file-based keys that are stored on disk) and are convenient for everyday use. Instead of having to remember and enter passphrases to unlock SSH/GPG keys, YubiKey needs only a physical touch after being unlocked with a PIN. All signing and encryption operations happen on the card, rather than in OS memory.
**New!** [drduh/Purse](https://github.com/drduh/Purse) is a password manager which uses GPG and YubiKey.
@ -8,15 +8,23 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
- [Purchase YubiKey](#purchase-yubikey)
- [Verify YubiKey](#verify-yubikey)
- [Download OS image](#download-os-image)
- [Download OS Image](#download-os-image)
- [Required software](#required-software)
* [Entropy](#entropy)
* [Debian/Ubuntu](#debian-ubuntu)
* [Arch](#arch)
* [RHEL7](#rhel7)
* [OpenBSD](#openbsd)
* [macOS](#macos)
* [Windows](#windows)
- [Entropy](#entropy)
- [Creating keys](#creating-keys)
- [Master key](#master-key)
- [Sign with an existing key (optional)](#sign-with-an-existing-key--optional-)
- [Sub-keys](#sub-keys)
* [Signing](#signing)
* [Encryption](#encryption)
* [Authentication](#authentication)
* [Add extra emails](#add-extra-emails)
- [Verify](#verify)
- [Export](#export)
- [Backup](#backup)
@ -38,10 +46,11 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
* [(Optional) Save public key for identity file configuration](#-optional--save-public-key-for-identity-file-configuration)
* [Connect with public key authentication](#connect-with-public-key-authentication)
+ [Steps for older distributions](#steps-for-older-distributions)
* [GitHub](#github)
* [OpenBSD](#openbsd)
* [Windows](#windows)
* [OpenBSD](#openbsd-1)
* [Windows](#windows-1)
+ [WSL](#wsl)
- [Prerequisites](#prerequisites)
- [WSL configuration](#wsl-configuration)
@ -49,6 +58,7 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
- [Multiple Keys](#multiple-keys)
- [Require touch](#require-touch)
- [Email](#email)
* [Mailvelope on macOS](#mailvelope-on-macos)
- [Reset](#reset)
- [Notes](#notes)
- [Troubleshooting](#troubleshooting)
@ -70,52 +80,54 @@ You will need several small storage devices for booting a temporary operating sy
It is recommended to generate cryptographic keys and configure YubiKey from a secure operating system and using an ephemeral environment ("live image"), such as [Debian](https://www.debian.org/CD/live/), [Tails](https://tails.boum.org/index.en.html), or [OpenBSD](https://www.openbsd.org/) booted from a USB drive.
Depending on your threat model and/or level of inherent trust in your own system. It is also a valid option to run the "live image" within a VM using something like Virtualbox or VMWare
Depending on your threat model and/or level of inherent trust in your own system, it may also be a valid option to run the live image within a virtual machine using VirtualBox or VMWare software.
$ doas dd if=debian-live-10.1.0-amd64-xfce.iso of=/dev/rsd2c bs=4m
$ doas dd if=debian-live-10.2.0-amd64-xfce.iso of=/dev/rsd2c bs=4m
465+1 records in
465+1 records out
1951432704 bytes transferred in 139.125 secs (14026448 bytes/sec)
```
Shut down the computer and disconnect internal hard drives and all unnecessary peripheral devices. If being run within a VM this part can be skipped as no such devices should be attached to the VM since the image will still be run as a "live image"
Shut down the computer and disconnect internal hard drives and all unnecessary peripheral devices. If being run within a VM, this part can be skipped as no such devices should be attached to the VM since the image will still be run as a "live image".
If on physical hardware consider using secure hardware like a ThinkPad X230 running [Coreboot](https://www.coreboot.org/) and [cleaned of Intel ME](https://github.com/corna/me_cleaner).
# Required software
Boot the OS image and configure networking.
Boot the live image and configure networking.
**Note** If the screen locks, unlock with `user`/`live`.
Open the terminal and install required software packages.
**Debian/Ubuntu**
## Debian/Ubuntu
**Note** Live Ubuntu images [may require modification](https://github.com/drduh/YubiKey-Guide/issues/116) to `/etc/apt/sources.list`
**Note** An additional Python package dependency may need to be installed to use `[ykman](https://support.yubico.com/support/solutions/articles/15000012643-yubikey-manager-cli-ykman-user-guide)` - `pip install yubikey-manager`
## Windows
Download and install [Gpg4Win](https://www.gpg4win.org/) and [PuTTY](https://putty.org).
You may also need more recent versions of [yubikey-personalization](https://developers.yubico.com/yubikey-personalization/Releases/) and [yubico-c](https://developers.yubico.com/yubico-c/Releases/).
## Entropy
# Entropy
Generating cryptographic keys requires high-quality [randomness](https://www.random.org/randomness/), measured as entropy.
Most operating systems use software-based pseudorandom number generators. A hardware random number generator like [OneRNG](http://onerng.info/onerng/) will [increase the speed](https://lwn.net/Articles/648550/) of entropy generation and possibly the quality.
Most operating systems use software-based pseudorandom number generators. A hardware random number generator like [OneRNG](https://onerng.info/onerng/) will [increase the speed](https://lwn.net/Articles/648550/) of entropy generation and possibly the quality.
Install and configure OneRNG software:
```console
$ sudo apt install -y \
at rng-tools python-gnupg openssl
$ sudo apt install -y at rng-tools python-gnupg openssl
Once GPG keys are moved to YubiKey, they cannot be moved again! Create an **encrypted** backup of the keyring and consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys as an additional backup.
Once keys are moved to YubiKey, they cannot be moved again! Create an **encrypted** backup of the keyring and consider using a [paper copy](https://www.jabberwocky.com/software/paperkey/) of the keys as an additional backup measure.
**Tip**: The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD.
@ -1329,8 +1333,7 @@ Install the required packages and mount the non-encrypted volume created earlier
**Important** The `cache-ttl` options do **NOT** apply when using a YubiKey as a smartcard as the PIN is [cached by the smartcard itself](https://dev.gnupg.org/T3362). Therefore, in order to clear the PIN from cache (smartcard equivalent to `default-cache-ttl` and `max-cache-ttl`), you need to unplug the YubiKey.
**Tip** Set `pinentry-program /usr/bin/pinentry-gnome3` for a GUI-based prompt. If the _pinentry_ graphical dialog doesn't show and you get this error: `sign_and_send_pubkey: signing failed: agent refused operation`, you probably need to install the `dbus-user-session` package and might have to restart the computer for the `dbus` user session to be fully inherited; this is because behind the scenes, `pinentry` complains about `No $DBUS_SESSION_BUS_ADDRESS found`, falls back to `curses` but doesn't find the expected `tty`.
**Tip** Set `pinentry-program /usr/bin/pinentry-gnome3` for a GUI-based prompt. If the _pinentry_ graphical dialog doesn't show and you get this error: `sign_and_send_pubkey: signing failed: agent refused operation`, you may need to install the `dbus-user-session` package and restart the computer for the `dbus` user session to be fully inherited; this is because behind the scenes, `pinentry` complains about `No $DBUS_SESSION_BUS_ADDRESS found`, falls back to `curses` but doesn't find the expected `tty`.
On macOS, use `brew install pinentry-mac` and adjust the program path to suit.
Note that `SSH_AUTH_SOCK` normally only needs to be set on the *local* laptop (workstation), where the YubiKey is plugged in. On the *remote* server that we SSH into, `ssh` will automatically set `SSH_AUTH_SOCK` to something like `/tmp/ssh-mXzCzYT2Np/agent.7541` when we connect. We therefore do **NOT** manually set `SSH_AUTH_SOCK` on the server. (Doing so would break [SSH Agent Forwarding](#remote-machines-agent-forwarding).)
Note that `SSH_AUTH_SOCK` normally only needs to be set on the *local* laptop (workstation), where the YubiKey is plugged in. On the *remote* server that we SSH into, `ssh` will automatically set `SSH_AUTH_SOCK` to something like `/tmp/ssh-mXzCzYT2Np/agent.7541` when we connect. We therefore do **NOT** manually set `SSH_AUTH_SOCK` on the server - doing so would break [SSH Agent Forwarding](#remote-machines-agent-forwarding).
## Copy public key
**Note** It is *not* necessary to import the corresponding GPG public key in order to use SSH.
**Note** It is **not** necessary to import the corresponding GPG public key in order to use SSH.
Copy and paste the output from `ssh-add` to the server's `authorized_keys` file:
@ -1938,7 +1941,7 @@ By default, YubiKey will perform encryption, signing and authentication operatio
To require a touch for each key operation, install [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and recall the Admin PIN:
**Note** Older versions of the YubiKey Manager used`touch` instead of `set-touch` in the below commands.
**Note** Older versions of YubiKey Manager use `touch` instead of `set-touch` in the following commands.
Authentication:
@ -1964,11 +1967,12 @@ YubiKey will blink when it is waiting for a touch. On Linux you can also use [yu
GPG keys on YubiKey can be used with ease to encrypt and/or sign emails and attachments using [Thunderbird](https://www.thunderbird.net/) and [Enigmail](https://www.enigmail.net). Thunderbird supports OAuth 2 authentication and can be used with Gmail. See [this guide](https://ssd.eff.org/en/module/how-use-pgp-linux) from EFF for detailed instructions.
## mailvelope on MacOS
## Mailvelope on macOS
[Mailvelope](https://www.mailvelope.com/en) allows GPG keys on YubiKey to be used with Gmail and others.
On MacOS install gpgme using homebrew:
On macOS, install gpgme using Homebrew:
```console
$ brew install gpgme
```
@ -2056,7 +2060,7 @@ scd apdu 00 44 00 00
- If SSH authentication still fails - add up to 3 `-v` flags to the `ssh` client to increase verbosity.
- If it still fails, it may be useful to stop the background `sshd` daemon process service on the server (e.g. using `sudo systemctl stop sshd`) and instead start it in the foreground with extensive debugging output, using `sshd -eddd`. Note that (quote `man sshd`) _The server also will not fork and will only process one connection._, and therefore has to be re-started after every `ssh` test.
- If it still fails, it may be useful to stop the background `sshd` daemon process service on the server (e.g. using `sudo systemctl stop sshd`) and instead start it in the foreground with extensive debugging output, using `/usr/sbin/sshd -eddd`. Note that the server will not fork and will only process one connection, therefore has to be re-started after every `ssh` test.
drduh
5 years ago