Merge pull request #595 from Yubico/piv-issues-ssh

Update PIV SSH documentation

content/PGP/SSH_authentication/index.adoc

@@ -4,6 +4,11 @@ this setup, the Authentication subkey of an OpenPGP key is used as an SSH key
 to authenticate against a server. To ensure that the only way to log in is by
 using your YubiKey we recommend disabling password login on your SSH server.
 
+[NOTE]
+There are multiple ways to use YubiKeys for SSH. See
+link:../../SSH/[SSH]
+for options.
+
 === Configuration guides
 
  - link:Windows.html[Windows]

content/PIV/Guides/SSH_user_certificates.adoc

@@ -1,6 +1,6 @@
 == Using SSH User Certificates with PIV keys
 This is a step-by-step on how to setup SSH user certificates using PIV
-for hardware-backed keys. This guide is primarily for an macOS or
+for hardware-backed keys. This guide is primarily for a macOS or
 Linux system.
 
 === Prerequisites
@@ -16,7 +16,7 @@ It has also been tested as *not working* with OpenSSH version 6.9p1.
 
 === Steps
 1. Generate an "ssh user CA" key and trust it for this account on this
-host
+host.
 
   $ ssh-keygen -N '' -C user-ca -f ~/.ssh/ca
   $ sed 's/^/cert-authority /' ~/.ssh/ca.pub > ~/.ssh/authorized_keys
@@ -65,6 +65,11 @@ If you have followed these steps to the letter, you will not be asked for the PI
 === More info
 For more information see the CERTIFICATES section of https://man.openbsd.org/OpenBSD-current/man1/ssh-keygen.1[ssh-keygen(1)].
 
+=== Notes
+
+- The ca key is stored in a file in this example, but could also be stored on another YubiKey in a similar fashion.
+- The target system must have the ca key configured as a cert-authority, either via a user's `authorized_keys` file, or using `sshd_config`.
+
 === Thanks
 Thanks to Christopher Harrell and Dean Sutherland formerly of the
 Paranoids, Information Security at Yahoo, Inc. for providing the

content/PIV/Guides/SSH_with_PIV_and_PKCS11.adoc

@@ -1,16 +1,21 @@
 == Using PIV for SSH through PKCS #11
 This is a step-by-step guide on setting up a YubiKey with PIV to work for public-key authentication with OpenSSH through PKCS #11. These instructions apply primarily to macOS and Linux systems.
 
+[NOTE]
+There are multiple ways to use YubiKeys for SSH. See
+link:../../SSH/[SSH]
+for options.
+
 === Prerequisites
 * a YubiKey with the PIV application loaded
-* the yubico-piv-tool software (download from link:../yubico-piv-tool/Releases/)
+* the yubico-piv-tool software (download from link:../../yubico-piv-tool/Releases/[yubico-piv-tool releases])
 * OpenSSH
 * For macOS, iOS 10.13 and later are supported
 
 OpenSC is no longer required, since we now have a functional PKCS #11 module, namely ykcs11.
 
 [NOTE]
-RSA 4096-bit keys are not currently supported due to a limitation in the PIV spec: https://github.com/Yubico/yubico-piv-tool/issues/58
+RSA 4096-bit and RSA 3072-bit keys require YubiKey firmware version 5.7 or later.
 
 [NOTE]
 We strongly recommend changing the management key; keeping the default management key is explicitly discouraged. The examples given in the following steps assume that you have not yet changed the management key. If you have changed the management key, add `--key` to the `yubico-piv-tool -a import-certificate` command below.
@@ -34,6 +39,9 @@ or *generate* the key:
 
   $ yubico-piv-tool -a verify-pin -a selfsign-certificate -s 9a -S "/CN=SSH key/" -i public.pem -o cert.pem
 
+[NOTE]
+This command will prompt for the PIV PIN. The default PIV PIN is 123456. You should change the default PIN before generating keys with `yubico-piv-tool -a change-pin`.
+
 *Step 3*: Load the certificate:
 
    $ yubico-piv-tool -a import-certificate -s 9a -i cert.pem