Mention Thunderbird, clean up agent forwarding. Fix #85.

1 files changed, 49 insertions, 39 deletions

diff --git a/README.md b/README.md
index 00ca01d..0b51c91 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Keys stored on YubiKey are non-exportable (as opposed to file-based keys that ar
 
 **New!** [drduh/Purse](https://github.com/drduh/Purse) is a password manager which uses GPG and YubiKey.
 
-If you have a comment or suggestion, please open an [issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub.
+If you have a comment or suggestion, please open an [Issue](https://github.com/drduh/YubiKey-Guide/issues) on GitHub.
 
 - [Purchase YubiKey](#purchase-yubikey)
 - [Verify YubiKey](#verify-yubikey)
@@ -34,38 +34,39 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
   * [Create configuration](#create-configuration)
   * [Replace agents](#replace-agents)
   * [Copy public key](#copy-public-key)
-  * [(Optional) Save public key for identity file configuration](#optional-save-public-key-for-identity-file-configuration)
+  * [(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)
   * [Touch to authenticate](#touch-to-authenticate)
   * [Import SSH keys](#import-ssh-keys)
-  * [Remote Machines (agent forwarding)](#remote-machines-agent-forwarding)
+  * [Remote Machines (agent forwarding)](#remote-machines--agent-forwarding-)
   * [GitHub](#github)
-  * [OpenBSD](#openbsd-1)
+  * [OpenBSD](#openbsd)
   * [Windows](#windows)
     + [WSL](#wsl)
       - [Prerequisites](#prerequisites)
       - [WSL configuration](#wsl-configuration)
       - [Remote host configuration](#remote-host-configuration)
       - [Final test](#final-test)
-- [Troubleshooting](#troubleshooting)
+- [Email](#email)
 - [Notes](#notes)
+- [Troubleshooting](#troubleshooting)
 - [Links](#links)
 
 # Purchase YubiKey
 
-All YubiKeys except the blue "security key" model are compatible with this guide. NEO models are limited to 2048-bit RSA keys. See [Compare YubiKeys](https://www.yubico.com/products/yubikey-hardware/compare-yubikeys/).
+All YubiKeys except the blue "security key" model are compatible with this guide. NEO models are limited to 2048-bit RSA keys. Compare YubiKeys [here](https://www.yubico.com/products/yubikey-hardware/compare-products-series/).
 
 You will also need several small storage devices for booting a live image, creating backups of private and public keys.
 
 # Verify YubiKey
 
-To confirm your YubiKey is genuine, open a [browser with U2F support](https://support.yubico.com/support/solutions/articles/15000009591-how-to-confirm-your-yubico-device-is-genuine-with-u2f) to [https://www.yubico.com/genuine/](https://www.yubico.com/genuine/). Insert your Yubico device, and select *Verify Device* to begin the process. Touch the YubiKey when prompted, and if asked, allow it to see the make and model of the device. If you see *Verification complete*, your device is authentic.
+To verify a YubiKey is genuine, open a [browser with U2F support](https://support.yubico.com/support/solutions/articles/15000009591-how-to-confirm-your-yubico-device-is-genuine-with-u2f) to [https://www.yubico.com/genuine/](https://www.yubico.com/genuine/). Insert a Yubico device, and select *Verify Device* to begin the process. Touch the YubiKey when prompted, and if asked, allow it to see the make and model of the device. If you see *Verification complete*, the device is authentic.
 
 This website verifies the YubiKey's device attestation certificates signed by a set of Yubico CAs, and helps mitigate [supply chain attacks](https://media.defcon.org/DEF%20CON%2025/DEF%20CON%2025%20presentations/DEFCON-25-r00killah-and-securelyfitz-Secure-Tokin-and-Doobiekeys.pdf).
 
 # Live image
 
-It is recommended to generate cryptographic keys and configure YubiKey from a secure operating system and ephemeral environment, such as [Debian Live](https://www.debian.org/CD/live/) or [Tails](https://tails.boum.org/index.en.html).
+It is recommended to generate cryptographic keys and configure YubiKey from a secure operating system and ephemeral environment, such as [Debian Live](https://www.debian.org/CD/live/), [Tails](https://tails.boum.org/index.en.html), or [OpenBSD](https://www.openbsd.org/).
 
 To use Debian, download the latest live image:
 
@@ -105,7 +106,7 @@ $ grep $(sha512sum debian-live-9.9.0-amd64-xfce.iso) SHA512SUMS
 SHA512SUMS:ae064cc399126214e4aa165fdbf9659047dd2af2d3b0ca57dd5f2686d1d3730019cfe3c56ac48db2af56eb856dbca75e642fadf56bc04c538b44d3d3a2982283 debian-live-9.9.0-amd64-xfce.iso
 ```
 
-If the key cannot be received, try changing your DNS resolver and/or specific keyserver:
+If the key cannot be received, try changing the DNS resolver and/or specific keyserver:
 
 ```console
 $ gpg --keyserver hkps://keyserver.ubuntu.com:443 --recv DF9B9C49EAA9298432589D76DA87E80D6294BE9B
@@ -163,18 +164,18 @@ Open the terminal and install several required packages:
 
 ```console
 $ sudo apt-get update && sudo apt-get install -y \
-    curl gnupg2 gnupg-agent dirmngr \
+    gnupg2 gnupg-agent dirmngr \
     cryptsetup scdaemon pcscd \
-    yubikey-personalization \
-    secure-delete hopenpgp-tools
+    secure-delete hopenpgp-tools \
+    yubikey-personalization
 ```
 
 **Arch**
 
 ```console
 $ sudo pacman -Syu \
-    gnupg2 pcsclite ccid \
-    yubikey-personalization hopenpgp-tools
+    gnupg2 pcsclite ccid hopenpgp-tools \
+    yubikey-personalization
 ```
 
 **RHEL7**
@@ -223,7 +224,7 @@ Plug in the device, then install and configure OneRNG software:
 $ sudo apt-get install -y \
     at rng-tools python-gnupg openssl
 
-$ curl -LfO https://github.com/OneRNG/onerng.github.io/raw/master/sw/onerng_3.6-1_all.deb
+$ wget https://github.com/OneRNG/onerng.github.io/raw/master/sw/onerng_3.6-1_all.deb
 
 $ sha256sum onerng_3.6-1_all.deb
 a9ccf7b04ee317dbfc91518542301e2d60ebe205d38e80563f29aac7cd845ccb  onerng_3.6-1_all.deb
@@ -258,14 +259,15 @@ An entropy pool value greater than 2000 is sufficient.
 Create a temporary directory which will be cleared on [reboot](https://en.wikipedia.org/wiki/Tmpfs):
 
 ```console
-$ export GNUPGHOME=$(mktemp -d) ; echo $GNUPGHOME
-/tmp/tmp.aaiTTovYgo
+$ export GNUPGHOME=$(mktemp -d)
+
+$ cd $GNUPGHOME
 ```
 
-Create a hardened configuration for GPG with the following options or by downloading [drduh/config/gpg.conf](https://github.com/drduh/config/blob/master/gpg.conf):
+Create a hardened configuration in the temporary directory with the following options:
 
 ```console
-$ curl -o $GNUPGHOME/gpg.conf https://raw.githubusercontent.com/drduh/config/master/gpg.conf
+$ wget https://raw.githubusercontent.com/drduh/config/master/gpg.conf
 
 $ grep -ve "^#" $GNUPGHOME/gpg.conf
 personal-cipher-preferences AES256 AES192 AES
@@ -297,14 +299,16 @@ The first key to generate is the master key. It will be used for certification o
 
 **Important** The master key should be kept offline at all times and only accessed to revoke or issue new sub-keys. Keys can also be generated on the YubiKey itself to ensure no other copies exist.
 
-You'll be prompted to enter and verify a passphrase - keep it handy as you'll need it throughout. To generate a strong passphrase which could be written down in a hidden or secure place; or memorized:
+You'll be prompted to enter and verify a passphrase - keep it handy as you'll need it multiple times later.
+
+To generate a strong passphrase which could be written down in a hidden or secure place; or memorized:
 
 ```console
 $ gpg --gen-random -a 0 24
 ydOmByxmDe63u7gqx2XI9eDgpvJwibNH
 ```
 
-On Linux, select the password with your mouse to copy it to the clipboard and paste using the middle mouse button or `Shift`-`Insert`.
+On Linux or OpenBSD, select the password with the mouse to copy it to the clipboard and paste using the middle mouse button or `Shift`-`Insert`.
 
 Generate a new key with GPG, selecting `(8) RSA (set your own capabilities)`, `Certify` capability only and `4096` bit key size.
 
@@ -680,7 +684,7 @@ sd 7:0:0:0: [sdb] Attached SCSI removable disk
 Write it with random data to prepare for encryption:
 
 ```console
-$ sudo dd if=/dev/urandom of=/dev/sdb bs=4M
+$ sudo dd if=/dev/urandom of=/dev/sdb bs=4M status=progress
 ```
 
 Erase and create a new partition table:
@@ -1346,7 +1350,7 @@ $ echo "test message string" | gpg --encrypt --armor --recipient $KEYID_0 --reci
 Decrypt the message:
 
 ```console
-$ gpg --decrypt --armor cipher.txt
+$ gpg --decrypt --armor encrypted.txt
 gpg: anonymous recipient; trying secret key 0x0000000000000000 ...
 gpg: okay, we are the anonymous recipient.
 gpg: encrypted with RSA key, ID 0x0000000000000000
@@ -1527,11 +1531,11 @@ When using the key `pinentry` will be invoked to request the key's passphrase. T
 
 ## Remote Machines (agent forwarding)
 
-If you want to use YubiKey to sign a git commit on a remote machine, or ssh through another layer, then this is possible using "Agent Forwarding".  This section should help you setup GPG and SSH agent forwarding.
+If you want to use YubiKey to sign a git commit on a remote machine, or ssh through another layer, then this is possible using Agent Forwarding.
 
-To do this, you need to already have shell access to the remote machine, and the YubiKey setup on the host machine.
+To do this, you need access to the remote machine and the YubiKey has to be set up on the host machine.
 
-* First, on the local machine, run:
+On the local machine, run:
 
 ```console
 $ gpgconf --list-dirs agent-extra-socket
@@ -1539,7 +1543,7 @@ $ gpgconf --list-dirs agent-extra-socket
 
 This should return a path to agent-extra-socket - `/run/user/1000/gnupg/S.gpg-agent.extra` - though on older Linux distros (and macOS) it may be `/home/<user>/.gnupg/S/gpg-agent.extra`.
 
-* Next, find the agent socket on the **remote** machine:
+Find the agent socket on the **remote** machine:
 
 ```console
 $ gpgconf --list-dirs agent-socket
@@ -1547,17 +1551,17 @@ $ gpgconf --list-dirs agent-socket
 
 This should return a path such as `/run/user/1000/gnupg/S.gpg-agent`.
 
-* On the remote machine, edit the file `/etc/ssh/sshd_config`, so that option `StreamLocalBindUnlink` is set to `StreamLocalBindUnlink yes`
+On the remote machine, edit `/etc/ssh/sshd_config` to set `StreamLocalBindUnlink yes`
 
-* **Optional** If you do not have root access to the remote machine to edit `/etc/ssh/sshd_config`, you will need to remove the socket on the remote machine before forwarding works.  For example, `rm /run/user/1000/gnupg/S.gpg-agent`.  Further information can be found on the [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding).
+**Optional** If you do not have root access to the remote machine to edit `/etc/ssh/sshd_config`, you will need to remove the socket on the remote machine before forwarding works. For example, `rm /run/user/1000/gnupg/S.gpg-agent`. Further information can be found on the [AgentForwarding GNUPG wiki page](https://wiki.gnupg.org/AgentForwarding).
 
-* Import public keys to the remote machine. This can be done by fetching from a keyserver. On the local machine, copy the public keyring to the remote machine:
+Import public keys to the remote machine. This can be done by fetching from a keyserver. On the local machine, copy the public keyring to the remote machine:
 
 ```console
 $ scp ~/.gnupg/pubring.kbx remote:~/.gnupg/
 ```
 
-* Finally, enable agent forwarding for a given machine by adding the following to the local machine's ssh config file `~/.ssh/config` (your agent sockets may be different):
+Finally, enable agent forwarding for a given machine by adding the following to the local machine's ssh config file `~/.ssh/config` (your agent sockets may be different):
 
 ```
 Host
@@ -1577,6 +1581,8 @@ pinentry-program /usr/bin/pinentry-curses
 extra-socket /run/user/1000/gnupg/S.gpg-agent.extra
 ```
 
+See [Issue #85](https://github.com/drduh/YubiKey-Guide/issues/85) for more information and troubleshooting.
+
 ## GitHub
 
 You can use YubiKey to sign GitHub commits and tags. It can also be used for GitHub SSH authentication, allowing you to push, pull, and commit without a password.
@@ -1702,9 +1708,20 @@ And reload the SSH daemon (e.g., `sudo service sshd reload`).
 
 **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host.
 
+# Email
+
+GPG keys on YubiKey can be used with ease to encrypt or sign email messages 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.
+
+# Notes
+
+1. YubiKey has two configurations: one invoked with a short press, and the other with a long press. By default, the short-press mode is configured for HID OTP - a brief touch will emit an OTP string starting with `cccccccc`. If you rarely use the OTP mode, you can swap it to the second configuration via the YubiKey Personalization tool. If you *never* use OTP, you can disable it entirely using the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named YubiKey NEO Manager).
+1. Programming YubiKey for GPG keys still lets you use its other configurations - [U2F](https://en.wikipedia.org/wiki/Universal_2nd_Factor), [OTP](https://www.yubico.com/faq/what-is-a-one-time-password-otp/) and [static password](https://www.yubico.com/products/services-software/personalization-tools/static-password/) modes, for example.
+1. Setting an expiry essentially forces you to manage your subkeys and announces to the rest of the world that you are doing so. Setting an expiry on a primary key is ineffective for protecting the key from loss - whoever has the primary key can simply extend its expiry period. Revocation certificates are [better suited](https://security.stackexchange.com/questions/14718/does-openpgp-key-expiration-add-to-security/79386#79386) for this purpose. It may be appropriate for your use case to set expiry dates on subkeys.
+1. To switch between two or more identities on different keys - unplug the first key and restart gpg-agent, ssh-agent and pinentry with `pkill gpg-agent ; pkill ssh-agent ; pkill pinentry ; eval $(gpg-agent --daemon --enable-ssh-support)`, then plug in the other key and run `gpg-connect-agent updatestartuptty /bye` - then it should be ready for use.
+
 # Troubleshooting
 
-- If you don't understand some option - read `man gpg`.
+- Use `man gpg` to understand GPG options and command-line flags.
 
 - If you encounter problems connecting to YubiKey with GPG - try unplugging and re-inserting YubiKey, and restarting the `gpg-agent` process.
 
@@ -1732,13 +1749,6 @@ And reload the SSH daemon (e.g., `sudo service sshd reload`).
 
 - If you totally screw up, you can [reset the card](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html).
 
-# Notes
-
-1. YubiKey has two configurations: one invoked with a short press, and the other with a long press. By default, the short-press mode is configured for HID OTP - a brief touch will emit an OTP string starting with `cccccccc`. If you rarely use the OTP mode, you can swap it to the second configuration via the YubiKey Personalization tool. If you *never* use OTP, you can disable it entirely using the [YubiKey Manager](https://developers.yubico.com/yubikey-manager) application (note, this not the similarly named YubiKey NEO Manager).
-1. Programming YubiKey for GPG keys still lets you use its other configurations - [U2F](https://en.wikipedia.org/wiki/Universal_2nd_Factor), [OTP](https://www.yubico.com/faq/what-is-a-one-time-password-otp/) and [static password](https://www.yubico.com/products/services-software/personalization-tools/static-password/) modes, for example.
-1. Setting an expiry essentially forces you to manage your subkeys and announces to the rest of the world that you are doing so. Setting an expiry on a primary key is ineffective for protecting the key from loss - whoever has the primary key can simply extend its expiry period. Revocation certificates are [better suited](https://security.stackexchange.com/questions/14718/does-openpgp-key-expiration-add-to-security/79386#79386) for this purpose. It may be appropriate for your use case to set expiry dates on subkeys.
-1. To switch between two or more identities on different keys - unplug the first key and restart gpg-agent, ssh-agent and pinentry with `pkill gpg-agent ; pkill ssh-agent ; pkill pinentry ; eval $(gpg-agent --daemon --enable-ssh-support)`, then plug in the other key and run `gpg-connect-agent updatestartuptty /bye` - then it should be ready for use.
-
 # Links
 
 * https://alexcabal.com/creating-the-perfect-gpg-keypair/