From c310969973e46c38cc281def633fd476b21e7bed Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Wed, 1 Oct 2014 14:21:25 +0200 Subject: [PATCH] Add. --- doc/CertificateAuthorityWithNEO.txt | 206 ++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 doc/CertificateAuthorityWithNEO.txt diff --git a/doc/CertificateAuthorityWithNEO.txt b/doc/CertificateAuthorityWithNEO.txt new file mode 100644 index 0000000..99896e7 --- /dev/null +++ b/doc/CertificateAuthorityWithNEO.txt @@ -0,0 +1,206 @@ +Certificate Authority with NEO +------------------------------ + +This document explains how to set up a Certificate Authority (CA) with +Sub-CA private keys stored on YubiKey NEOs. 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 YubiKey NEOs, 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 NEO Sub-CAs and EE certificates. The NEO 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'll also set a short lifelength on the root CA to signal that expiry +dates on root CAs are not relevant. + +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 NEO with the PIV applet 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< 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 NEO +---------------------- + +We need to change the management key, PIN and PUK code following the +YubiKey-NEO-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 NEO. + +This step is parametrized with the name of the YubiKey NEO 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 NEO 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 NEO 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: + + cat>yubico-internal-https-subca-$user-csr.conf<yubico-internal-https-subca-$user-crt.conf< 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 NEO: + + yubico-piv-tool -k $key -a import-key -s 9c < yubico-internal-https-subca-$user-key.pem + +Import Sub-CA cert to NEO: + + 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 + +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<yubico-internal-https-ee-$host-crt.conf<