add instructions for SSH with PIV

2014-12-09 14:56:29 +01:00
parent d835ba1cff
commit bddfa55403
2 changed files with 48 additions and 1 deletions
@@ -30,7 +30,8 @@ ACLOCAL_AMFLAGS = -I m4

 EXTRA_DIST = windows.mk mac.mk tool/tests/basic.sh

-EXTRA_DIST += doc/Certificate_Authority_with_NEO.adoc doc/OS_X_code_signing.adoc doc/Windows_certificate.adoc doc/YubiKey_NEO_PIV_introduction.adoc
+EXTRA_DIST += doc/Certificate_Authority_with_NEO.adoc doc/OS_X_code_signing.adoc doc/SSH_with_PIV_and_PKCS11.adoc doc/Windows_certificate.adoc doc/YubiKey_NEO_PIV_introduction.adoc
+

 # Maintainer rules.

@@ -0,0 +1,46 @@
+Using PIV for SSH through PKCS11
+--------------------------------
+
+This is a step-by-step for how to get a Neo with PIV to work for
+public-key authentication with OpenSSH through PKCS11.
+Primarily on a OS X or Linux system.
+
+Prerequisites
+-------------
+
+* a YubiKey Neo with the PIV applet loaded
+* the yubico-piv-tool software
+* the OpenSC software
+
+Steps
+-----
+
+1. Generate a key in slot 9a (any slot should suffice):
+
+  $ yubico-piv-tool -s 9a -a generate -o public.pem
+
+2. Create a selfsigned certificate for that key:
+
+  $ yubico-piv-tool -a verify-pin -P 123456 -a selfsign-certificate -s 9a \
+        -S "/CN=SSH key/" -i public.pem -o cert.pem
+
+3. Load the certificate:
+
+   $ yubico-piv-tool -a import-certificate -s 9a -i cert.pem
+
+4. Find out where OpenSC has installed the pkcs11 module.
+
+  * For OS X with binary installation this is typically in `/Library/OpenSC/lib/`
+
+  * For a Debian based system this is typically in `/usr/lib/x86_64-linux-gnu/`
+
+After this we'll call this location `$OPENSC_LIBS`
+
+5. Get the public key in correct format for ssh and add to authorized_keys on
+the target system.
+
+   $ ssh-keygen -D $OPENSC_LIBS/opensc-pkcs11.so
+
+6. Authenticate to the target system using the new key:
+
+   $ ssh -I $OPENSC_LIBS/opensc-pkcs11.so user@remote.example.com