Merge pull request #1 from drduh/master

Merge upstream

README.md

@@ -4,7 +4,7 @@ An authentication key can also be created for SSH and used with [gpg-agent](http
 
 Keys stored on a smartcard like YubiKey seem more difficult to steal than ones stored on disk, and are convenient for everyday use.
 
-Instructions written for Debian GNU/Linux 8 (jessie) using YubiKey 4 in OTP+CCID mode, updated to GPG version 2.2.1. Some notes are included for macOS as well. Note, older YubiKeys are limited to 2048 bit RSA keys.
+Instructions written for Debian GNU/Linux 8 (jessie) using YubiKey 4 - with support for **4096 bit** RSA keys - in OTP+CCID mode, updated to GPG version 2.2.1. Some notes are included for macOS as well. Note, older YubiKeys like the Neo are limited to **2048 bit** RSA keys. Please see a comparison of the different YubiKeys [here](https://www.yubico.com/products/yubikey-hardware/compare-yubikeys/).
 
 Debian live install images are available from [here](https://www.debian.org/CD/live/) and are suitable for writing to USB drives.
 
@@ -27,7 +27,7 @@ If you have a comment or suggestion, please open an [issue](https://github.com/d
     - [Authentication key](#authentication-key)
   - [Check your work](#check-your-work)
   - [Export keys](#export-keys)
-  - [Back up everything](#back-up-everything)
+  - [Backup everything](#backup-everything)
   - [Configure YubiKey](#configure-yubikey)
   - [Configure smartcard](#configure-smartcard)
     - [Change PINs](#change-pins)
@@ -252,6 +252,8 @@ Export the key ID as a [variable](https://stackoverflow.com/questions/1158091/de
 
 ## Create subkeys
 
+Note: If using a Yubikey 4, please use **4096 bit** as the size for the subkeys; if using a YubiKey Neo, please use **2048 bit** as the size for the subkeys.
+
 Edit the key to add subkeys:
 
     $ gpg --expert --edit-key $KEYID
@@ -483,10 +485,12 @@ In addition to the backup below, you might want to keep a separate copy of the
 revocation certificate in a safe place:
 `$GNUPGHOME/openpgp-revocs.d/<key fingerprint>.rev`
 
-## Back up everything
+## Backup everything
 
 Once keys are moved to hardware, they cannot be extracted again (otherwise, what would be the point?), so make sure you have made an *encrypted* backup before proceeding.
 
+Also consider using a [paper copy](http://www.jabberwocky.com/software/paperkey/) of the keys as an additional backup measure.
+
 To create an encrypted USB drive, first attach it and check its label:
 
     $ dmesg | tail
@@ -956,6 +960,8 @@ Unplug and replug the Yubikey. Check the card's status:
 
 `sec#` indicates master key is not available (as it should be stored encrypted offline).
 
+**Note** If you see `General key info..: [none]` in the output instead, first import your public key using the previous step.
+
 ## GnuPG
 
 ### Trust master key
@@ -1158,6 +1164,13 @@ Depending on how your environment is set up, you might need to add these to your
     export GPG_TTY="$(tty)"
     export SSH_AUTH_SOCK="${HOME}/.gnupg/S.gpg-agent.ssh"
     gpgconf --launch gpg-agent
+    
+**Note** On some systems, for example Arch Linux-based distributions, you may need to replace the second and the third line with:
+
+```
+export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"
+gpg-connect-agent updatestartuptty /bye
+```
 
 
 ### Copy public key to server
@@ -1188,6 +1201,8 @@ There is a `-L` option of `ssh-add` that lists public key parameters of all iden
     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).
+
 ## Requiring touch to authenticate
 
 By default the Yubikey will perform key operations without requiring a touch from the user. To require a touch for every SSH connection, use the [Yubikey Manager](https://developers.yubico.com/yubikey-manager/) (you'll need the Admin PIN):
@@ -1219,6 +1234,10 @@ The Yubikey will blink when it's waiting for the touch.
 
 - If you receive the error, `sign_and_send_pubkey: signing failed: agent refused operation` - you probably have ssh-agent running.  Make sure you replaced ssh-agent with gpg-agent as noted above.
 
+- If you still receive the error, `sign_and_send_pubkey: signing failed: agent refused operation` - On Debian, [try](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=835394) `gpg-connect-agent updatestartuptty /bye`
+
+- If you receive the error, `Error connecting to agent: No such file or directory` from `ssh-add -L`, the UNIX file socket that the agent uses for communication with other processes may not be set up correctly. On Debian, try `export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"`
+
 - If you totally screw up, you can [reset the card](https://developers.yubico.com/ykneo-openpgp/ResetApplet.html).
 
 ## Yubikey OTP Mode and cccccccc....