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.
Leave a Reply