Helper scripts to build and manage internal Certificate Authorities (CAs) with yubikey devices, because everybody needs a little bit of PKI, and we can definitely make it cheaper and easier to achieve.
This project is intended to be used as a template for the creation and management of certificate infrastructure, with CA information stored in git, and consists of a set of helper utilities to support the creation of root certificates, intermediate and end (client and certificate) Certificate Signing Requests (CSRs), as well as to load certificates and keys on to yubikeys and to use yubikeys to sign CSRs to create certificates.
This requires as many yubikeys as you would like to store certificates on, as well as an offline machine to generate the root keys and intermediate certificates. In future it may be possible to generate all keys on devices to aleviate this need for a trusted / airgapped machine.
PKI is Public Key Infrastructure, a method using cryptographic certificates to validate or authenticate services or devices. This works using a trust chain, whereby devices can trust a root Certificate Authority (CA), then any certificates issued by that authority can be validated against that root.
This is commonly used for HTTPS/TLS on the web, where certificate authorities are distributed as part of your operating system or browser, allowing transparent validation and secure connections through the web. Sometimes it is useful to have an internal certificate authority (or a few), for use between micro-services, or in manufacturing to ensure security with physical devices.
Working on OSX, Linux, Some features supported on Windows (and PRs are welcome).
OSX: install with
brew install openssl engine_pkcs11 opensc yubico-piv-tool.
Linux: install with
sudo apt install openssl opensc-pkcs11 libengine-pkcs11-openssl
Windows: install with
choco install openssl opensc, compile libp11 or grab a pre-compiled (win10, x64) libp11.dll from here, copy config from scripts/engine-win.conf to
C:\Program Files\OpenSSL-Win64\openssl.cfg and update
pkcs11.dll locations to match installed.
First, create your own PKI git repository using this as a template, then use the following steps to create a Root / CA, Intermediate certificates, and Client or Server certificates.
Note that when deploying yubikeys you may wish to configure management and PIV pins to ensure that certificates are not mistakenly overwritten, and are only used by authorized parties. We recommend you read this getting started guide for PIV on yubikeys before getting underway.
mkdir CA_NAMEto create a new directory for your CA
cp example-ca/config CA_NAME/configto copy the example config to your new CA directory
CA_NAME/configto configure your CA
./scripts/new-ca.sh CA_NAME "Human Description"to create the root certificate
./scripts/yk-load CA_NAME CA_NAMEto load the root certificate onto a connected yubikey
rm CA_NAME/CA_NAME.keyto remove CA key from the system
git add CA_NAME/to add your new CA to version control
./scripts/new-int.sh CA_NAME INT_NAME "Human Description"to create a new intermediate CSR under the provided CA
./scripts/yk-sign-int.sh CA_NAME INT_NAMEto sign the intermediate CSR using the root yubikey
./scripts/yk-load CA_NAME INT_NAMEto load the CA onto a connected yubikey
rm CA_NAME/INT_NAME.keyto remove intermediate key from the system
git add CA_NAME/INT_NAME.*to add your new intermediate to version control
Note that steps 4-6 can be elided if you need to do something else with your intermediate certificate
./scripts/new-client.sh CA_NAME CLIENT_NAMEor
./scripts/new-server.sh CA_NAME SERVER_NAMEto create a new client or server cerficiate respectively
./scripts/yk-sign-end.sh CA_NAME END_NAMEto sign the client or server CSR using an intermediate yubikey
git add CA_NAME/END_NAME.crtto add your new certificate to version control
./scripts/new-client.cmd CA_NAME INT_NAME CLIENT_NAMEto generate and sign the new client certificate with the provided intermediate (on the yubikey)
If you have any questions, comments, or suggestions, feel free to open an issue or a pull request.