Add card reset steps, clean up formatting.

1 files changed, 88 insertions, 51 deletions

diff --git a/README.md b/README.md
index 7c0ebf4..e4a8b8c 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,6 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
   * [Copy public key](#copy-public-key)
   * [(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-)
   * [GitHub](#github)
@@ -47,9 +46,10 @@ If you have a comment or suggestion, please open an [Issue](https://github.com/d
       - [Prerequisites](#prerequisites)
       - [WSL configuration](#wsl-configuration)
       - [Remote host configuration](#remote-host-configuration)
-      - [Final test](#final-test)
-- [Using multiple YubiKey with same GPG keys](#Using-multiple-YubiKey-with-same-GPG-keys)
+- [Multiple keys](#Multiple-keys)
+- [Require touch](#require-touch)
 - [Email](#email)
+- [Reset](#reset)
 - [Notes](#notes)
 - [Troubleshooting](#troubleshooting)
 - [Links](#links)
@@ -613,7 +613,11 @@ ssb  rsa4096/0x5912A795E90DD2CF
 ssb  rsa4096/0x3F29127E79649A3D
     created: 2017-10-09  expires: 2018-10-09       usage: A
 [ultimate] (1). Dr Duh <doc@duh.to>
+```
+
+Finish by saving the keys.
 
+```console
 gpg> save
 ```
 
@@ -635,7 +639,7 @@ ssb   rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09]
 
 Add any additional identities or email addresses you wish to associate using the `adduid` command.
 
-**Optional** Verify with OpenPGP key checks, use the automated [key best practice checker](https://riseup.net/en/security/message-security/openpgp/best-practices#openpgp-key-checks):
+**Tip** Verify with a OpenPGP [key best practice checker](https://riseup.net/en/security/message-security/openpgp/best-practices#openpgp-key-checks):
 
 ```console
 $ gpg --export $KEYID | hokey lint
@@ -669,6 +673,8 @@ $ gpg --armor --export-secret-subkeys $KEYID -o \path\to\dir\sub.gpg
 
 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.
 
+**Tip**: The ext2 filesystem (without encryption) can be mounted on both Linux and OpenBSD.
+
 **Linux**
 
 Attach another external storage device and check its label:
@@ -1266,7 +1272,7 @@ gpg: Total number processed: 1
 gpg:               imported: 1
 ```
 
-Edit the master key to assign it ultimate trust by selecting `trust` then option `5`:
+Edit the master key to assign it ultimate trust by selecting `trust` and `5`:
 
 ```console
 $ export KEYID=0xFF3E7D88647EBCDB
@@ -1470,16 +1476,18 @@ Probably the biggest thing missing from `gpg-agent`'s ssh agent support is being
 Create a hardened configuration for gpg-agent by downloading [drduh/config/gpg-agent.conf](https://github.com/drduh/config/blob/master/gpg-agent.conf):
 
 ```console
-$ curl -o ~/.gnupg/gpg-agent.conf https://raw.githubusercontent.com/drduh/config/master/gpg-agent.conf
+$ cd ~/.gnupg
 
-$ cat ~/.gnupg/gpg-agent.conf
+$ wget https://raw.githubusercontent.com/drduh/config/master/gpg-agent.conf
+
+$ grep -ve "^#" gpg-agent.conf
 enable-ssh-support
 default-cache-ttl 60
 max-cache-ttl 120
 pinentry-program /usr/bin/pinentry-curses
 ```
 
-Alternatively, you may want to use `/usr/bin/pinentry-gnome3` for a GUI-based prompt.
+**Tip** Set `pinentry-program /usr/bin/pinentry-gnome3` for a GUI-based prompt.
 
 On macOS, use `brew install pinentry-mac` and adjust the program path to suit.
 
@@ -1563,26 +1571,6 @@ debug1: Authentication succeeded (publickey).
 
 **Note** To make multiple connections or securely transfer many files, consider using the [ControlMaster](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) ssh option. Also see [drduh/config/ssh_config](https://github.com/drduh/config/blob/master/ssh_config).
 
-## Touch to authenticate
-
-**Note** This is not possible on YubiKey NEO.
-
-By default, YubiKey will perform key operations without requiring a touch from the user. To require a touch for every SSH authentication, use the [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and Admin PIN:
-
-```console
-$ ykman openpgp touch aut on
-```
-
-To require a touch for signing and encryption operations:
-
-```console
-$ ykman openpgp touch sig on
-
-$ ykman openpgp touch enc on
-```
-
-The YubiKey will blink when it's waiting for touch.
-
 ## Import SSH keys
 
 If there are existing SSH keys that you wish to make available via `gpg-agent`, you'll need to import them. You should then remove the original private keys. When importing the key, `gpg-agent` uses the key's filename as the key's label; this makes it easier to follow where the key originated from. In this example, we're starting with just the YubiKey's key in place and importing `~/.ssh/id_rsa`:
@@ -1785,25 +1773,24 @@ StreamLocalBindUnlink yes
 
 And reload the SSH daemon (e.g., `sudo service sshd reload`).
 
-#### Final test
+Unplug YubiKey, disconnect or reboot. Log back in to Windows, open a WSL console and enter `ssh-add -l` - you should see nothing.
+
+Plug in YubiKey, enter the same command to display the ssh key.
 
-- Unplug YubiKey, disconnect or reboot.
-- Log back in to Windows, open a WSL console and enter `ssh-add -l` - you should see nothing.
-- Plug in YubiKey, enter the same command to display the ssh key.
-- Log in to the remote host, you should have the pinentry dialog asking for the YubiKey pin.
-- On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwarding works!
+Log in to the remote host, you should have the pinentry dialog asking for the YubiKey pin.
+
+On the remote host, type `ssh-add -l` - if you see the ssh key, that means forwarding works!
 
 **Note** Agent forwarding may be chained through multiple hosts - just follow the same [protocol](#remote-host-configuration) to configure each host.
 
-# Using multiple YubiKey with same GPG keys
+# multiple keys
 
-If you want to store your keys on multiple YubiKey, you will see that GnuPG doesn't store the serial number of the first key it has seen.
-This is a know issue [#T2291](https://dev.gnupg.org/T2291). For now if you lost one of your keys and want to use another one the only workaround
-is to delete GnuPG's shadowed key (this is where the serial number is stored).
+GnuPG doesn't store the serial number of the first key it has seen - [#T2291](https://dev.gnupg.org/T2291).
 
-To do so, first of all you need to find the `Keygrip` number of each key :
-```
-gpg2 --with-keygrip -k $KEYID
+If a YubiKey is lost and replaced, delete GnuPG's shadowed key - where the serial number is stored. Find the `Keygrip` number of each key:
+
+```console
+$ gpg --with-keygrip -k $KEYID
 pub   rsa4096/0xFF3E7D88647EBCDB 2017-10-09 [C]
       Key fingerprint = 011C E16B D45B 27A5 5BA8  776D FF3E 7D88 647E BCDB
       Keygrip = 7A20855980A62C10569DE893157F38A696B1300E
@@ -1816,25 +1803,77 @@ sub   rsa4096/0x3F29127E79649A3D 2017-10-09 [A] [expires: 2018-10-09]
       Keygrip = 7EF25A1115294342F451BC1CDD0FA94395F2D074
 ```
 
-Then delete all the shadow keys using their `Keygrip` number :
+Then delete all the shadow keys using their `Keygrip` number:
+
+```console
+$ cd .gnupg/private-keys-v1.d
+
+$ rm 85D44BD52AD45C0852BD15BF41161EE9AE477398.key \
+    A0AA3D9F626BDEA3B833F290C7BCA79216C8A996.key \
+    7EF25A1115294342F451BC1CDD0FA94395F2D074.key
+```
+
+Insert the new YubiKey and re-generate shadow-keys by checking card status:
+
+```console
+$ gpg --card-status
 ```
-cd .gnupg/private-keys-v1.d
-rm 85D44BD52AD45C0852BD15BF41161EE9AE477398.key \
-A0AA3D9F626BDEA3B833F290C7BCA79216C8A996.key \
-7EF25A1115294342F451BC1CDD0FA94395F2D074.key
+
+# Require touch
+
+**Note** This is not possible on YubiKey NEO.
+
+By default, YubiKey will perform encryption, signing and authentication operations without requiring any action from the user, after the key is plugged in and first unlocked with the PIN.
+
+To require a touch for each key operation, install [YubiKey Manager](https://developers.yubico.com/yubikey-manager/) and recall the Admin PIN:
+
+Authentication:
+
+```console
+$ ykman openpgp touch aut on
 ```
 
-Insert the new YubiKey simply run a card-status this will re-generate the shadow-keys :
+Signing:
+
+```console
+$ ykman openpgp touch sig on
 ```
-gpg2 --card-status
+
+Encryption:
+
+```console
+$ ykman openpgp touch enc on
 ```
 
-Then try to use your key, it should work, without serial number error.
+YubiKey will blink when it is waiting for a touch.
+
 
 # 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.
 
+# Reset
+
+If PIN attempts are exceeded, the card is locked and must be [reset](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html) and set up again using the encrypted backup.
+
+Copy the following script to a file and run `gpg-connect-agent -R $file` to lock and terminate the card. Then re-insert YubiKey to reset.
+
+```console
+/hex
+scd serialno
+scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 81 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
+scd apdu 00 20 00 83 08 40 40 40 40 40 40 40 40
+scd apdu 00 e6 00 00
+scd apdu 00 44 00 00
+/echo Card has been successfully reset.
+```
+
 # 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).
@@ -1870,8 +1909,6 @@ GPG keys on YubiKey can be used with ease to encrypt or sign email messages and
 
 - If SSH authentication stil fails - add up to 3 `-v` flags to increase verbosity.
 
-- If you totally screw up, you can [reset the card](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html).
-
 # Links
 
 * https://alexcabal.com/creating-the-perfect-gpg-keypair/