Introduction

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.

Explanation

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 -----BEGIN CERTIFICATE-----.

Because the /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.

Example

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

Use openssl to view list of revoked certificates.

openssl crl -in pki_test_crl.crl -inform DER -text -noout | grep -A10 "Revoked Certificates:"