Vault PKI - How to run a CA with Hashicorp Vault

This article will demonstrate how to run a CA (Certification Authority) with Hashicorp Vault using the vault pki secrets engine. The examples provided will be in the form of a development environment using Docker. Before continuing it may be helpful to read our previous article on running vault in Docker.

Installing the vault client in Linux

First, you should go ahead and install the vault client. This article is assuming Linux is your host OS.

These instructions are valid as of this writing. Note that the HashiCorp GPG key and repository could change at any time. The official Hashicorp instructions are located here along with instructions for other OS installations: https://learn.hashicorp.com/tutorials/vault/getting-started-install

Add the HashiCorp GPG key to your host:

curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -

Add the HashiCorp Linux repository

sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"

Update your OS packages and install vault

sudo apt-get update && sudo apt-get install vault

Verify that vault was installed. You should see example usages in the output

vault

Set vault client environment variables

The two most basic environment variables for using vault on the command line are the location of the vault server and the authentication token.

export VAULT_ADDR='http://0.0.0.0:8200'
export VAULT_TOKEN=vault-plaintext-root-token

Run a local instance of Docker

As mentioned in the introduction, follow the instructions in our previous article on how to run vault in docker.

Configure the Vault PKI Secrets Engine

Create a PKI secrets engine for your root CA

vault secrets enable -path=root_ca pki

After creating the pki secrets engine with the previous command you should receive the following message: Success! Enabled the pki secrets engine at: root_ca/

Root CA certificates generally have a long validity period. For this example we will set it to 10 years. To set the TTL for the Root PKI secrets engine run the following command:

vault secrets tune -max-lease-ttl=87600h root_ca

Where 87600h is equivalent to 10 years and root_ca is the name of the engine.

After the engine is configured, generate the CA certificate:

vault write -field=certificate root_ca/root/generate/internal common_name="My Root CA" ttl=87600h > CA_cert.crt

Configure the CA to issue certificates and have a CRL (Certificate Revocation List) endpoint.

vault write root_ca/config/urls \
     issuing_certificates="$VAULT_ADDR/v1/pki/ca" \
     crl_distribution_points="$VAULT_ADDR/v1/pki/crl"

Create a PKI secrets engine for your intermediate CA

vault secrets enable -path=int_ca pki

Set the TTL for the intermediate secrets engine to be 10 years also:

vault secrets tune -max-lease-ttl=87600h int_ca

Next, generate a CSR that will be submitted to the Root CA to be issued a certificate.

vault write -format=json int_ca/intermediate/generate/internal \
     common_name="My Intermediate CA" \
     | jq -r '.data.csr' > intermediate.csr

Submit the CSR to the root certificate secrets engine to be issued a signed certificate:

vault write int_ca/intermediate/set-signed certificate=@intermediate.csr

Request a certificate from the Vault PKI secrets engine

A primary use case of using the Vault PKI Secrets Engine is to issue short lived certificates. For example, a user has a task to perform so they get a certificate with a validity period of 10 minutes. If they need to do that same task the next day, they request a new certificate.

To request an SSL Certificate using the vault command line tools, run the following command:

vault write int_ca/issue/my-cert common_name="my-cert" ttl="10m"

Note that this can also be done with the Vault REST API.

curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"common_name": "my-cert", "ttl": "10m"}' \
    $VAULT_ADDR/v1/int_ca/issue/my-cert | jq

Revoke a certificate from the Vault PKI secrets engine

If the certificate has been compromised or is no longer needed it should be revoked. To revoke a certificate in a Vault PKI Secrets engine run the following command:

vault write int_ca/revoke serial_number=<serial_number>

Conclusion

This article has demonstrated how to operate a CA with Hashicorp Vault. Vault PKI Secrets Engines provide much flexibility and a way to generate X.509 SSL certificates for both client authentication and server identification. Let us know in the comments if you have any questions or would like to see additional examples of operating a CA with the PKI Secrets Engine.