Vault includes a public key infrastructure (PKI) secrets engine which can manage the lifecycle of certificates. One element of this lifecycle is the Certificate Revocation List (CRL). A CRL is defined as a time-stamped and signed data structure that a certificate authority (CA) or CRL issuer periodically issues to communicate the revocation status of affected digital certificates. In short - if you revoke a certificate, information about that certificate is added to the CRL, which is the indicator of whether or not a certificate has been revoked.
Reviewing the information in a CRL can be a bit more difficult initially imagined however. The purpose of this KB article is to walk through how you can review the contents of Vault's PKI secrets engine's CRL.
With the PKI secrets engine, certificates can be revoked using the /pki/revoke API endpoint. This endpoint takes 2 optional parameters - either the
serial_number of the certificate or the
certificate itself in PEM format must be provided to the endpoint for revocation. Once performed, the certificate information is added to the CRL.
To read the contents of the CRL, we must first get the CRL from the PKI secrets engine. To do so, we will use the read-issuer-crl API endpoint. Note that there are numerous paths to get the CRL data from the secrets engine. The one we will be using to get the CRL is
/pki/crl. Note that the
read-issuer-crl documentation indicates that this endpoint returns data in DER format.
DER (Distinguished Encoding Rules) is a binary encoding for X.509 certificates and private keys. Unlike PEM, DER-encoded files do not contain plain text statements such as
/pki/crl endpoint returns binary data, simply curling the endpoint will not show us anything. We need to capture the data in a file and then read it using another utility. In this example, we will be using the
openssl utility to read the data. The
openssl utility contains a command appropriately called
crl. This command lets us input our DER formatted CRL and output it as text. We can then finally see which certificates have been revoked.
With the explanation out of the way - the following is an example demonstrating the entire workflow of enabling the PKI secrets engine, revoking a certificate, exporting the CRL and finally reading the CRL's data.
Enable pki secrets engine.
vault secrets enable -path=pki_test pki
Tune the TTL for the secrets engine.
vault secrets tune -max-lease-ttl=8760h pki_test
Configure CA certificate and private key.
vault write pki_test/root/generate/internal \ common_name=my-website.com \ ttl=8760h
Update 'issuing_certificates' and 'crl_distribution_points' URLs.
vault write pki_test/config/urls \ issuing_certificates="$VAULT_ADDR/v1/pki_test/ca" \ crl_distribution_points="$VAULT_ADDR/v1/pki_test/crl"
Configure a role to be used when generating credentials.
vault write pki_test/roles/example-dot-com \ allowed_domains=my-website.com \ allow_subdomains=true \ max_ttl=72h
Generate some certificates and save the serial numbers.
vault write -format=json pki_test/issue/example-dot-com \ common_name=test1.my-website.com | \ jq .data.serial_number | tr -d \" >; test1_serial.txt vault write -format=json pki_test/issue/example-dot-com \ common_name=test2.my-website.com | \ jq .data.serial_number | tr -d \" >; test2_serial.txt vault write -format=json pki_test/issue/example-dot-com \ common_name=test3.my-website.com | \ jq .data.serial_number | tr -d \" >; test3_serial.txt vault write -format=json pki_test/issue/example-dot-com \ common_name=test4.my-website.com | \ jq .data.serial_number | tr -d \" >; test4_serial.txt
Revoke 2 of the certificates using the serial numbers we saved.
vault write pki_test/revoke serial_number=$(cat test1_serial.txt) vault write pki_test/revoke serial_number=$(cat test2_serial.txt)
Retrieve the current CRL from the
crl_distribution_points in raw DER-encoded form by hitting the CRL endpoint endpoint. We can use openssl to process the CRL in DER form.
curl -s "$VAULT_ADDR/v1/pki_test/crl" -o pki_test_crl.crl
openssl crl -in pki_test_crl.crl -inform DER -text -noout | grep -A10 "Revoked Certificates:"