Updated docs.

2016-10-19 15:40:54 +02:00
parent 127227fe4c
commit 20aa39ec21
10 changed files with 72 additions and 641 deletions
@@ -1,9 +1,6 @@
-Yubico PIV Tool
+== Yubico PIV Tool
 ===============
 Introduction
 ------------
 === Introduction
 The Yubico PIV tool is used for interacting with the Privilege and
 Identification Card (PIV) application on a https://www.yubico.com[YubiKey].
@@ -11,9 +8,11 @@ With it you may generate keys on the device, importing keys and
 certificates, and create certificate requests, and other operations.
 A shared library and a command-line tool is included.
-License
+==== Usage guides
-------
+For information and examples on what you can do with a PIV enabled YubiKey,
 see https://developers.yubico.com/PIV/
 === License
 In general the project is covered by the following BSD license.  The
 file ykcs11/pkcs11.h has additional copyright and licensing
 information, please see it for more information.  Some other files
@@ -49,15 +48,13 @@ infrastructure.
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ----
-Building
+=== Building
 --------
 After downloading and unpacking the package tarball, you build it as
 follows.
-  ./configure
+  $ ./configure
-  make
+  $ make
-  sudo make install
+  $ sudo make install
 The backend to use is decided at compile time, see the summary at the
 end of the ./configure output.  Use --with-backend=foo to chose
@@ -69,80 +66,74 @@ under Mac OS X, and "winscard" is used under Windows.  In most
 situations, running ./configure should automatically find the proper
 backend to use.
-Building from Git
+=== Building from Git
 -----------------
 Recent versions of autoconf, automake, pkg-config and libtool must
 be installed.  Help2man is used to generate the manpages.  Gengetopt
 version 2.22.6 or later is needed for command line parameter handling.
 Generate the build system using:
-  autoreconf --install
+  $ autoreconf --install
 Then you follow the normal build instructions, see above.
 To turn on all warnings add --enable-gcc-warnings to ./configure
-Portability
+=== Portability
 -----------
 The main development platform is Debian GNU/Linux.  The project is
 cross-compiled to Windows using MinGW (see windows.mk) using the PCSC
 backend.  It may also be built for Mac OS X (see mac.mk), also using
 the PCSC backend.
-Example Usage
+=== Example Usage
 -------------
 For a list of all available options --help can be given. For more information
 on exactly what happens --verbose or --verbose=2 may be added.
 Generate a new ECC-P256 key on device in slot 9a, will print the public
 key on stdout:
-  yubico-piv-tool -s 9a -A ECCP256 -a generate
+  $ yubico-piv-tool -s 9a -A ECCP256 -a generate
 Generate a certificate request with public key from stdin, will print
 the resulting request on stdout:
-  yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
+  $ yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
    -a verify -a request
 Generate a self-signed certificate with public key from stdin, will print
 the certificate, for later import, on stdout:
-  yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
+  $ yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
    -a verify -a selfsign
 Import a certificate from stdin:
-  yubico-piv-tool -s 9a -a import-certificate
+  $ yubico-piv-tool -s 9a -a import-certificate
 Set a random chuid, import a key and import a certificate from a PKCS12
 file with password test, into slot 9c:
-  yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
+  $ yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
    -a import-key -a import-cert
 Change the management key used for administrative authentication:
-  yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
+  $ yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
    -a set-mgm-key
 Delete a certificate in slot 9a:
-  yubico-piv-tool -a delete-certificate -s 9a
+  $ yubico-piv-tool -a delete-certificate -s 9a
 Show some information on certificates and other data:
-  yubico-piv-tool -a status
+  $ yubico-piv-tool -a status
 Read out the certificate from a slot and then run a signature test:
-  yubico-piv-tool -a read-cert -s 9a
+  $ yubico-piv-tool -a read-cert -s 9a
-  yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a
+  $ yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a
 Import a key into slot 85 (only available on YubiKey 4) and set the
 touch policy (also only available on YubiKey 4):
-  yubico-piv-tool -a import-key -s 85 --touch-policy=always -i key.pem
+  $ yubico-piv-tool -a import-key -s 85 --touch-policy=always -i key.pem
@@ -1,73 +0,0 @@
 Load and use Android code signing certificate
 ---------------------------------------------
 This is a step-by-step guide on how to load and use an android code signing
 key and certificate.
 Prerequisites
 -------------
 * a YubiKey with the PIV application
 * the yubico-piv-tool software
 * the OpenSC software
 * jarsigner and keytool from the JDK (OpenJDK 8 used here)
 Steps
 -----
 1. Import the key and cert, do one of the below:
 a. Import the key and cert (PEM format) in slot 9a:
 +
 ----
  $ yubico-piv-tool -s 9a -a import-key -i key.pem
  $ yubico-piv-tool -s 9a -a import-certificate -i cert.pem
 ----
 b. Import the key and cert (PKCS12 format) in slot 9a:
 +
 ----
  $ yubico-piv-tool -s 9a -a import-key -a import-cert -i key.p12 -K PKCS12
 ----
 2. Create a java pkcs11 configuration file:
 +
 ----
  cat > /tmp/pkcs11_java.cfg
  name = OpenSC-PKCS11
  description = SunPKCS11 via OpenSC
  library = /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
  slotListIndex = 1
 ----
 3. Check that keytool can see the key:
 +
 ----
  $ keytool -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /tmp/pkcs11_java.cfg \
    -keystore NONE -storetype PKCS11 -list
  Enter keystore password:
  Keystore type: PKCS11
  Keystore provider: SunPKCS11-OpenSC-PKCS11
  Your keystore contains 1 entry
  Certificate for PIV Authentication, PrivateKeyEntry,
  Certificate fingerprint (SHA1): 26:D7:CB:71:6D:42:3C:AB:58:69:E0:9D:F0:16:DF:84:7E:1C:5A:9A
 ----
 +
 Password here is the PIN of the key (default 123456).
 4. Sign the apk with jarsigner:
 +
 ----
  $ jarsigner -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /tmp/pkcs11_java.cfg \
    -keystore NONE -storetype PKCS11 app.apk "Certificate for PIV Authentication"
  Enter Passphrase for keystore: 
  jar signed.
 ----
 5. Verify the signature with jarsigner:
 +
 ----
  $ jarsigner -verify app.apk
 ----
@@ -1,13 +1,12 @@
-Using Attestation
+== Using Attestation
 -----------------
-== Introduction
+=== Introduction
 This feature is only available in YubiKey 4.3 and newer.
 A high level description of the thinking and how this can be used can be found
 at https://developers.yubico.com/PIV/Introduction/PIV_attestation.html
-== Usage
+=== Usage
 Attestation works through a special key slot called “f9” this comes
 pre-loaded from factory with a key and cert signed by Yubico, but can be
 overwritten.
@@ -20,7 +19,7 @@ special key, this can be realised by using the yubico-piv-tool action attest:
 The output of this is a PEM encoded certificate, signed by the key in slot f9.
-== Verifying
+=== Verifying
 To verify an attestation step 1 is to build the certificate chain. Put the
 attestation root certificate in a file (or if you trust several put all
 of them in said file). The Yubico root certificate can be found at
@@ -1,208 +0,0 @@
 Certificate Authority with a YubiKey
 ------------------------------------
 This document explains how to set up a Certificate Authority (CA) with
 Sub-CA private keys stored on YubiKeys.  Typical use for this is
 to generate HTTPS certificates for internal servers.
 Considerations
 --------------
 For our example, we have chosen to use one root CA with a private key
 stored in an offline machine, that signs sub-CAs with private keys
 stored on YubiKeys, which signs end-entity (EE) certs.  We'll
 generate the Sub-CA private keys on an offline host and save a copy of
 those keys.
 We have chosen to use a RSA 3744 bit root CA key, and RSA 2048 bit
 keys for the Sub-CAs and EE certificates.  The YubiKey is limited to
 RSA 1k and 2k keys (it supports ECDSA too but we chose to not use that
 here).
 By setting some name constraints, we are trying to limit to powers of
 this CA.  This is not fully supported by all environments, but it
 should do no harm, and may be useful in some environments.
 The root also has a path length constraint of 1 to prevent the Sub-CAs
 from issuing further Sub-Sub-CAs.
 We also set a expiry date far away in the future on the root CA
 (expiring in 1000000 days) and use datefudge to set an arbitrary start
 date for the CA, to avoid leaking the time of CA creation which would
 leak some bits if information going into the randomness generation.
 Preparations
 ------------
 We use OpenSSL to generate keys and certificates.  This is done on an
 offline machine, booted from a LiveCD.  Some additional packages may
 be required (pcscd, etc, see below) and will have to be transferred on
 a USB stick.
 You need a YubiKey with the PIV application on, which you can purchase
 from Yubico.
 You need to install the PKCS#11 Engine:
  sudo dpkg -i libengine-pkcs11-openssl*
 or if you are on a connected machine, more simpler:
  sudo apt-get install libengine-pkcs11-openssl
 Creating a Root CA
 -------------------
 Generate the private key as follows:
  openssl genrsa -out yubico-internal-https-ca-key.pem 3744
 Generate the Root CA certificate and initialize the CA serial number
 counter as follows:
  cat>yubico-internal-https-ca.conf<<EOF
  [ req ]
  x509_extensions = v3_ca
  distinguished_name = req_distinguished_name
  prompt = no
  [ req_distinguished_name ]
  CN=Yubico Internal HTTPS CA
  [ v3_ca ]
  subjectKeyIdentifier=hash
  basicConstraints=critical,CA:true,pathlen:1
  keyUsage=critical,keyCertSign,cRLSign
  nameConstraints=critical,@nc
  [ nc ]
  permitted;otherName=1.3.6.1.5.5.7.8.7;IA5:yubico.com
  permitted;email.0=yubico.com
  permitted;email.1=.yubico.com
  permitted;DNS=yubico.com
  permitted;URI.0=yubico.com
  permitted;URI.1=.yubico.com
  permitted;IP.0=0.0.0.0/255.255.255.255
  permitted;IP.1=::/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
  EOF
  datefudge "2014-01-01 UTC" openssl req -new -sha256 -x509 -set_serial 1 -days 1000000 -config yubico-internal-https-ca.conf -key yubico-internal-https-ca-key.pem -out yubico-internal-https-ca-crt.pem
  echo 01 > yubico-internal-https-ca-crt.srl
 You may inspect the newly generated root CA with:
  openssl x509 -text < yubico-internal-https-ca-crt.pem
 Preparing a Sub-CA
 ----------------------
 We need to change the management key, PIN and PUK code following the
 YubiKey-PIV-Introduction.txt document.  We also want to save a
 copy of these values.  Here are the steps that are needed to be done
 for each new Sub-CA.
 This step is parametrized with the name of the YubiKey user.
 Generate new management code, PIN and PUK as follows:
  user=Simon
  key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
  echo $key > yubico-internal-https-$user-key.txt
  pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
  echo $pin > yubico-internal-https-$user-pin.txt
  puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
  echo $puk > yubico-internal-https-$user-puk.txt
 Configure a fresh YubiKey with these parameters as follows:
  yubico-piv-tool -a set-mgm-key -n $key
  yubico-piv-tool -k $key -a change-pin -P 123456 -N $pin
  yubico-piv-tool -k $key -a change-puk -P 12345678 -N $puk
 Creating a Sub-CA
 -----------------
 This step is parametrized with the name of the YubiKey user.  This
 means we will have one Sub-CA for every person authorized to sign
 certificates in our CA.
  user=Simon
 We first need to load the management key and PIN code from the
 previous section.
  key=`cat yubico-internal-https-$user-key.txt`
  pin=`cat yubico-internal-https-$user-pin.txt`
 Generate the private key:
  openssl genrsa -out yubico-internal-https-subca-$user-key.pem 2048
 Generate the Sub-CA certificate request:
  cat>yubico-internal-https-subca-$user-csr.conf<<EOF
  [ req ]
  distinguished_name = req_distinguished_name
  prompt = no
  [ req_distinguished_name ]
  CN=Yubico Internal HTTPS $user Sub-CA
  EOF
  openssl req -sha256 -new -config yubico-internal-https-subca-$user-csr.conf -key yubico-internal-https-subca-$user-key.pem -nodes -out yubico-internal-https-subca-$user-csr.pem
 Generate the Sub-CA certificate:
  cat>yubico-internal-https-subca-$user-crt.conf<<EOF
  basicConstraints = critical, CA:true, pathlen:0
  keyUsage=critical, keyCertSign
  EOF
  openssl x509 -sha256 -CA yubico-internal-https-ca-crt.pem -CAkey yubico-internal-https-ca-key.pem -req -in yubico-internal-https-subca-$user-csr.pem -extfile yubico-internal-https-subca-$user-crt.conf -out yubico-internal-https-subca-$user-crt.pem
  echo 00 > yubico-internal-https-subca-$user-crt.srl
 You may inspect the newly generated EE cert with this command:
  openssl x509 -text < yubico-internal-https-subca-$user-crt.pem
 Import Sub-CA key to the YubiKey:
  yubico-piv-tool -k $key -a import-key -s 9c < yubico-internal-https-subca-$user-key.pem 
 Import Sub-CA cert to the YubiKey:
  yubico-piv-tool -k $key -a import-certificate -s 9c < yubico-internal-https-subca-$user-crt.pem 
 Creating End-Entity Certificates
 --------------------------------
 This step is parametrized with the hostname, and the name of the
 Sub-CA used to sign the EE, so set it first:
  host=munin
  user=Simon
 We first need to load the PIN code from the previous section.
  pin=`cat yubico-internal-https-$user-pin.txt`
 Then generate a new private key and certificate request:
  openssl genrsa -out yubico-internal-https-ee-$host-key.pem 2048
  cat>yubico-internal-https-ee-$host-csr.conf<<EOF
  [ req ]
  distinguished_name = req_distinguished_name
  prompt = no
  [ req_distinguished_name ]
  CN=$host.yubico.com
  EOF
  openssl req -sha256 -new -config yubico-internal-https-ee-$host-csr.conf -key yubico-internal-https-ee-$host-key.pem -nodes -out yubico-internal-https-ee-$host-csr.pem
 Then sign the certificate using the:
  cat>yubico-internal-https-ee-$host-crt.conf<<EOF
  basicConstraints = critical,CA:false
  keyUsage=critical,digitalSignature,keyEncipherment
  extendedKeyUsage=critical,serverAuth
  subjectAltName=critical,DNS:$host.yubico.com
  EOF
  openssl << EOF
  engine dynamic -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so -pre ID:pkcs11 -pre NO_VCHECK:1 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so -pre VERBOSE
  x509 -engine pkcs11 -CAkeyform engine -CAkey slot_1-id_2 -sha256 -CA yubico-internal-https-subca-$user-crt.pem -req -passin pass:$pin -in yubico-internal-https-ee-$host-csr.pem -extfile yubico-internal-https-ee-$host-crt.conf -out yubico-internal-https-ee-$host-crt.pem
  EOF
 You may inspect the newly generated EE cert with this command:
  openssl x509 -text < yubico-internal-https-ee-$host-crt.pem
@@ -1,55 +0,0 @@
 Request, load and use OS X code signing certificates
 ---------------------------------------------------
 This is a short step-by-step on how to generate a key on a YubiKey,
 create a certificate request, submit that request to apple, load the
 certificate in the YubiKey and use it for code signing.
 Prerequisites
 -------------
 * a YubiKey with the PIV application loaded
 * the yubico-piv-tool software
 * the OpenSC software
 * membership in the mac developer program
 Steps
 -----
 1. Generate a key in slot 9a:
  $ yubico-piv-tool -s 9a -a generate -o public.pem
 2. Create a certificate request for app distribution:
  $ yubico-piv-tool -a verify-pin -P 123456 -s 9a -a request-certificate \
 	-S "/CN=Application/" -i public.pem -o application.csr
 3. Generate a key in slot 9c:
   $ yubico-piv-tool -s 9c -a generate -o public.pem
 4. Create a certificate request for installer distribution:
  $ yubico-piv-tool -a verify-pin -P 123456 -s 9c -a request-certificate \
 	-S "/CN=Installer/" -i public.pem -o installer.csr
 5. Go to the Apple developer program page and submit the requests.
 6. When the certificates are ready and approved, download them.
 7. Load the certificates:
   $ yubico-piv-tool -a import-certificate -s 9a -K DER -i mac_app.cer
   $ yubico-piv-tool -a import-certificate -s 9c -K DER -i mac_installer.cer
 +
 NOTE: -K DER is available from version 0.1.3, with earlier convert to PEM and import.
 8. Set a new chuid in the application to make sure nothing is cached for the key:
   $ yubico-piv-tool -a set-chuid
 9. Re-plug the YubiKey and make sure the certificates show up under the keychain
 "PIV_II" in Keychain Access.
 10. Use the certificates as usual with codesign/pkgbuild/productbuild/productsign
@@ -1,76 +0,0 @@
 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 OS X or
 Linux system.
 Prerequisites
 -------------
 * a YubiKey with the PIV application loaded
 * the yubico-piv-tool software
 * the ykcs11 PKCS#11 module
 * OpenSSH
 [NOTE]
 This has been tested as working with OpenSSH version 7.2p2.
 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
  $ ssh-keygen -N '' -C user-ca -f ~/.ssh/ca
  $ sed 's/^/cert-authority /' ~/.ssh/ca.pub > ~/.ssh/authorized_keys
 2. Generate a key in PIV slot 9c that requires touch. (Note the second
 operation will require touch)
  $ yubico-piv-tool -a generate -s 9c -A RSA2048 --pin-policy=never --touch-policy=always -o public.pem
  $ yubico-piv-tool -a selfsign-certificate -s 9c -S "/CN=SSH key/" -i public.pem -o cert.pem
  $ yubico-piv-tool -a import-certificate -s 9c -i cert.pem
 3. Double check that the key appears in slot 9c (optional)
  $ yubico-piv-tool -a status
 4. Clear the SSH agent
  $ ssh-add -D
  $ ssh-add -e /PATH/TO/libykcs11.so
  * Make sure to use the correct path (e.g. `/usr/local/lib`) and extension (`.so` for Linux, `.dylib` for Mac OS X) for libykcs11.
  * Beware that `ssh-add -D` doesn't seem to clear PKCS#11 libraries, only keys
 (http://lists.mindrot.org/pipermail/openssh-unix-dev/2016-July/035154.html[link]).
 5. Add PIV to the SSH agent (will prompt for PIV PIN)
  $ ssh-add -s /PATH/TO/libykcs11.so
 6. Get the public key from PIV and sign it using the CA key. This produces `~/.ssh/id_rsa-cert.pub`
  $ ssh-add -L > ~/.ssh/id_rsa.pub
  $ ssh-keygen -s ~/.ssh/ca -I identity -n "${LOGNAME}" ~/.ssh/id_rsa.pub
 7. Authenticate to the target system using the new key:
   $ ssh user@remote.example.com
 If you have followed these steps to the letter, you will not be asked for the PIV PIN, but your YubiKey will start blinking, waiting for touch.
 More info
 ---------
 For more information see the CERTIFICATES section of http://man.openbsd.org/OpenBSD-current/man1/ssh-keygen.1[ssh-keygen(1)].
 Thanks
 ------
 Thanks to Christopher Harrell and Dean Sutherland from the
 https://yahoo-security.tumblr.com/[Yahoo Paranoids] for providing the
 instruction and the testing.
@@ -1,72 +0,0 @@
 Using PIV for SSH through PKCS11
 --------------------------------
 This is a step-by-step for how to get a YubiKey with PIV to work for
 public-key authentication with OpenSSH through PKCS11.
 Primarily on a OS X or Linux system.
 Prerequisites
 -------------
 * a YubiKey with the PIV application loaded
 * the yubico-piv-tool software
 * the OpenSC software
 * OpenSSH
 ** If you are using OSX El Capitan (10.11) or earlier, for ssh-agent to work a newer OpenSSH than is delivered with the system; macOS Sierra (10.12) contains a compatible version
 [NOTE]
 The following example 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.
 Steps
 -----
 1. Generate a key in slot 9a (any slot should suffice):
  $ yubico-piv-tool -s 9a -a generate -o public.pem
 +
 [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
 2. Create a self-signed certificate for that key.
 The only use for the X.509 certificate is to make PIV/PKCS#11 lib happy.
 They would want to be able to extract the public-key from the smartcard,
 and do that through the X.509 certificate.
  $ yubico-piv-tool -a verify-pin -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/`. Homebrew users can use `export OPENSC_LIBS=$(brew --prefix 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. Export the public key in correct format for ssh and once you got it,
 add it to authorized_keys on the target system.
   $ ssh-keygen -D $OPENSC_LIBS/opensc-pkcs11.so -e
 +
 [NOTE]
 The command will export all keys stored on the YubiKey Neo.
 Hopefully it will keep the slot order so it should be not hard to guess which
 is the public key associated with your targeted private key.
 6. Authenticate to the target system using the new key:
   $ ssh -I $OPENSC_LIBS/opensc-pkcs11.so user@remote.example.com
 7. This can also be setup to work with ssh-agent: (Optional)
   $ ssh-add -s $OPENSC_LIBS/opensc-pkcs11.so
 +
 NOTE: On OS X prior to macOS 10.12 “Sierra” this typically requires installation of a third-party OpenSSH from Homebrew or the like and using that ssh-agent.
 +
 To confirm that the ssh-agent correctly finds that key and getting the public key in correct format:
   $ ssh-add -L
@@ -1,43 +0,0 @@
 Request and load a certificate from Windows CA
 ----------------------------------------------
 This is a short step-by-step on how to generate a key on a YubiKey,
 create a certificate request, submit that request to a Windows CA
 and then load the certificate on the YubiKey.
 Prerequisites
 -------------
 * a YubiKey with the PIV application loaded
 * the yubico-piv-tool software
 * credentials to request certs from a Windows CA
 Steps
 -----
 1. Generate the key:
   (--key[=STRING] is needed if the management key value is no longer the default value)
  yubico-piv-tool -s 9a -a generate -o public.pem --key[=STRING]
 2. Request a certificate:
  yubico-piv-tool -a verify-pin -P 123456 -s 9a -a request-certificate \
 	-S "/CN=example/O=test/" -i public.pem -o request.csr
 3. Submit the request to the Windows CA:
   (this step must be run on a windows machine that know about the CA)
  certreq -submit -attrib "CertificateTemplate:User" request.csr cert.crt
 4. Load the certificate on the YubiKe:
   (--key[=STRING] is needed if the management key value is not the default value)
  yubico-piv-tool -s 9a -a import-certificate -i cert.crt --key[=STRING]
 5. For it to be useful in windows a chuid must be set as well:
   (only if that wasn't done earlier)
   (--key[=STRING] is needed if the management key value is no longer the default value)
   yubico-piv-tool -a set-chuid --key[=STRING]
@@ -1,6 +1,4 @@
-YKCS11
+== YKCS11
 ------
 This is a PKCS#11 module that allows to communicate with the PIV
 application running on a YubiKey.
@@ -10,18 +8,14 @@ specifications.
 The complete specifications are available at
 http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html.
-BUILDING
+=== BUILDING
 ~~~~~~~~
 YKCS11 is automatically built as part of `yubico-piv-tool` and the
-following command will suffice
+following command will suffice:
----
+  $ autoreconf --install
-yubico-piv-tool$ autoreconf --install
+  $ ./configure
-yubico-piv-tool$ ./configure
+  $ make
-yubico-piv-tool$ make
+  $ sudo make install
 yubico-piv-tool$ sudo make install
 ----
 More info about building yubico-piv-tool can be found in the related
 `README` file or over at
@@ -31,9 +25,7 @@ Once installed, the module will be found by default in
 /usr/local/lib/libykcs11.so otherwise it will be built locally in
 yubico-piv-tool/ykcs11/.libs/libykcs11.so
-PORTABILITY
+=== PORTABILITY
 ~~~~~~~~~~~
 The module has been developed and tested using Debian GNU/Linux and
 Ubuntu Linux. It is however possible to cross-compile it for Windows
 and Mac OS X using the relative makefiles (windows.mk and mac.mk).
@@ -47,9 +39,7 @@ Further testing at this stage has *not* been carried out, so
 additional tweaks might be needed to use operating systems different
 from Linux.
-SUPPORTED FUNCTIONALITY AND KNOWN ISSUES
+=== SUPPORTED FUNCTIONALITY AND KNOWN ISSUES
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 YKCS11 is not a full implementation of PKCS#11. Some functionality are
 not present and others are not yet implemented.
@@ -84,9 +74,7 @@ officer (SO). These have been mapped to perform regular usage of the
 private key material (PIN-associated operations) and device management
 (management-key associated operations).
-Key Mapping
+==== Key Mapping
 ^^^^^^^^^^^
 The module provides four main keys that can be used. These correspond
 to the four main keys in PIV and accessible through yubico-piv-tool.
 The mapping is as follows:
@@ -100,9 +88,7 @@ The mapping is as follows:
 |3|9d
 |===
-PINs and Management Key
+==== PINs and Management Key
 ^^^^^^^^^^^^^^^^^^^^^^
 The default user PIN for the YubiKey is `123456`. +
 The default management key is
 `010203040506070801020304050607080102030405060708`. +
@@ -119,9 +105,7 @@ According to PKCS#11 however, a special user called `CONTEXT_SPECIFIC`
 should be used for such operations. This is also supported and *might
 become the only available mechanism in the future*.
-Key Generation
+==== Key Generation
 ^^^^^^^^^^^^^^
 Key pair generation is a particular operation, in the sense that
 within PIV this is the only moment where the newly created public key
 is given back to the user. To prevent the key from being lost it is
@@ -129,16 +113,12 @@ automatically stored within the YubiKey by wrapping it in an X.509
 certificate. This certificate is however empty. It does not have other
 valid information except for the public key.
-DEBUGGING
+==== DEBUGGING
 ^^^^^^^^^
 By default the module has debugging disabled. This is _highly_ verbose
 and might be confusing. In order to enabled it rebuild the project as
 follows:
----
+  $ autoreconf --install
-yubico-piv-tool$ autoreconf --install
+  $ ./configure --enable-ykcs11-debug
-yubico-piv-tool$ ./configure --enable-ykcs11-debug
+  $ make
-yubico-piv-tool$ make
+  $ sudo make install
 yubico-piv-tool$ sudo make install
 ----
@@ -1,6 +1,4 @@
-Yubico PIV Tool
+== Yubico PIV Tool
 ===============
 The YubiKey supports the Personal Identity Verification (PIV) card
 interface specified in NIST SP 800-73 document "Cryptographic
 Algorithms and Key Sizes for PIV".  PIV enables you to perform RSA or
@@ -11,9 +9,7 @@ hardware functionality.
 * PIV Standards http://csrc.nist.gov/groups/SNS/piv/standards.html
-General information
+=== General information
 -------------------
 The default PIN code is 123456.  The default PUK code is 12345678.
 The default 3DES management key (9B) is
@@ -31,57 +27,51 @@ The maximum size of stored objects is 2005 bytes.
 Currently all functionality are available over both contact and
 contactless interfaces (contrary to what the specifications mandate).
-Preparing a YubiKey for real use
+=== Preparing a YubiKey for real use
 --------------------------------
 You would typically change the management key to make sure nobody but
 you can modify the state of the PIV application on the YubiKey.  Make sure to
 keep a copy of the key around for later use.
-  key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
+  $ key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
-  echo $key
+  $ echo $key
-  yubico-piv-tool -a set-mgm-key -n $key
+  $ yubico-piv-tool -a set-mgm-key -n $key
 The PIN and PUK should be changed as well.
-  pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
+  $ pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
-  echo $pin
+  $ echo $pin
-  puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
+  $ puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
-  echo $puk
+  $ echo $puk
-  yubico-piv-tool -a change-pin -P 123456 -N $pin
+  $ yubico-piv-tool -a change-pin -P 123456 -N $pin
-  yubico-piv-tool -a change-puk -P 12345678 -N $puk
+  $ yubico-piv-tool -a change-puk -P 12345678 -N $puk
 Other useful commands
 ---------------------
 === Other useful commands
 To generate a new private key:
-  yubico-piv-tool -k $key -a generate -s 9c
+  $ yubico-piv-tool -k $key -a generate -s 9c
 To reset PIN/PUK retry counter AND codes (default pin 123456 puk
 12345678):
-  yubico-piv-tool -k $key -a verify -P $pin -a pin-retries --pin-retries 3 --puk-retries 3
+  $ yubico-piv-tool -k $key -a verify -P $pin -a pin-retries --pin-retries 3 --puk-retries 3
 To reset the application (PIN/PUK need to be blocked hence trying a couple
 of times -- you need to modify this if you have changed the default
 number of PIN/PUK retries).
-  yubico-piv-tool -a verify-pin -P 471112
+  $ yubico-piv-tool -a verify-pin -P 471112
-  yubico-piv-tool -a verify-pin -P 471112
+  $ yubico-piv-tool -a verify-pin -P 471112
-  yubico-piv-tool -a verify-pin -P 471112
+  $ yubico-piv-tool -a verify-pin -P 471112
-  yubico-piv-tool -a verify-pin -P 471112
+  $ yubico-piv-tool -a verify-pin -P 471112
-  yubico-piv-tool -a change-puk -P 471112 -N 6756789
+  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  yubico-piv-tool -a change-puk -P 471112 -N 6756789
+  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  yubico-piv-tool -a change-puk -P 471112 -N 6756789
+  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  yubico-piv-tool -a change-puk -P 471112 -N 6756789
+  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  yubico-piv-tool -a reset
+  $ yubico-piv-tool -a reset
 Software
 --------
 === Software
 Card management has been tested with the tools from the OpenSC
 project, specifically piv-tool, and Yubico's PIV software (see
 below).  Basic features should work with any PIV compliant 
@@ -93,9 +83,7 @@ middleware.
 * https://github.com/OpenSC/OpenSC/wiki/US-PIV
 * https://github.com/OpenSC/OpenSC/wiki/PivTool
-Card Holder Unique Identifier
+=== Card Holder Unique Identifier
 -----------------------------
 For the application to be usable in windows the object CHUID (Card Holder
 Unique Identifier) has to be set and unique. The card contents are
 also aggressively cached so the CHUID has to be changed if the card