Skip to main content
Oct 19-21 HashiConf Global is live. Join Now
Type '/' to Search

Build Your Own Certificate Authority (CA)

This tutorial also appears in: Vault.

Vault's PKI secrets engine can dynamically generate X.509 certificates on demand. This allows services to acquire certificates without going through the usual manual process of generating a private key and Certificate Signing Request (CSR), submitting to a Certificate Authority (CA), and then waiting for the verification and signing process to complete.

»Personas

The steps described in this tutorial are typically performed by a security engineer.

»Challenge

Organizations should protect their website; however, the Traditional PKI process workflow takes a long time, which motivates organizations to create certificates which do not expire for a year or more.

»Solution

Use Vault to create X.509 certificates for usage in Mutual Transport Layer Security (MTLS) or other arbitrary PKI encryption. This solution can be used to create web server certificates, but if users do not import the CA chains, browsers will complain about the self-signed certificates.

Creating PKI certificates is generally a cumbersome process using traditional tools like openssl or even more advanced frameworks like CFSSL. These tools also require a human component to verify certificate distribution meets organizational security policies.

Vault's PKI secrets engine makes this a lot simpler. The PKI secrets engine can be an intermediate-only certificate authority, which potentially allows for higher levels of security.

  1. Store CA outside of Vault (air gapped).
  2. Create CSRs for the intermediate CA.
  3. Sign CSR outside Vault and import intermediate CA.
  4. Issue leaf certificates from the Intermediate CA.

»Prerequisites

To perform the tasks described in this tutorial, you need:

  • A Vault environment. Refer to the Getting Started tutorial to install Vault.

  • The API and CLI versions of the example scenario use the jq tool to parse JSON output. Install jq in your Vault environment to follow the examples which use this tool.

»Policy requirements

NOTE: For the purpose of this tutorial, you can use a root token to work with Vault. However, it is recommended that root tokens are only used for just enough initial setup or in emergencies. As a best practice, use tokens with appropriate set of policies based on your role in the organization.

To perform all tasks demonstrated in this tutorial, your policy must include the following capabilities:

# Enable secrets engine
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# List enabled secrets engine
path "sys/mounts" {
  capabilities = [ "read", "list" ]
}

# Work with pki secrets engine
path "pki*" {
  capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

# Enable secrets enginepath "sys/mounts/*" {  capabilities = [ "create", "read", "update", "delete", "list" ]}
# List enabled secrets enginepath "sys/mounts" {  capabilities = [ "read", "list" ]}
# Work with pki secrets enginepath "pki*" {  capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]}

If you are not familiar with policies, complete the policies tutorial.

»Scenario introduction

In this tutorial, you are going to first generate a self-signed root certificate.

Then you are going to generate an intermediate certificate that is signed by the root. Finally, you are going to generate a certificate for the test.example.com domain.

Overview

In this tutorial, you will perform the following:

  1. Generate Root CA
  2. Generate Intermediate CA
  3. Create a Role
  4. Request Certificates
  5. Revoke Certificates
  6. Remove Expired Certificates

»Start Vault

In another terminal, start a Vault dev server with root as the root token.

$ vault server -dev -dev-root-token-id root

$ vault server -dev -dev-root-token-id root

The Vault dev server defaults to running at 127.0.0.1:8200. The server is also initialized and unsealed.

Insecure operation: Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.

Export an environment variable for the vault CLI to address the Vault server.

$ export VAULT_ADDR=http://127.0.0.1:8200

$ export VAULT_ADDR=http://127.0.0.1:8200

Export an environment variable for the vault CLI to authenticate with the Vault server.

$ export VAULT_TOKEN=root

$ export VAULT_TOKEN=root

The Vault server is ready.

»Step 1: Generate root CA

In this step, you are going to generate a self-signed root certificate using PKI secrets engine.

  1. Enable the pki secrets engine at the pki path.

    $ vault secrets enable pki

    $ vault secrets enable pki

  2. Tune the pki secrets engine to issue certificates with a maximum time-to-live (TTL) of 87600 hours.

    $ vault secrets tune -max-lease-ttl=87600h pki

    $ vault secrets tune -max-lease-ttl=87600h pki

  3. Generate the root certificate and save the certificate in CA_cert.crt.

    $ vault write -field=certificate pki/root/generate/internal \
     common_name="example.com" \
     ttl=87600h > CA_cert.crt

    $ vault write -field=certificate pki/root/generate/internal \     common_name="example.com" \     ttl=87600h > CA_cert.crt

    This generates a new self-signed CA certificate and private key. Vault will automatically revoke the generated root at the end of its lease period (TTL); the CA certificate will sign its own Certificate Revocation List (CRL).

  4. Configure the CA and CRL URLs.

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

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

»Step 2: Generate intermediate CA

Now, you are going to create an intermediate CA using the root CA you regenerated in the previous step.

  1. First, enable the pki secrets engine at the pki_int path.

    $ vault secrets enable -path=pki_int pki

    $ vault secrets enable -path=pki_int pki

  2. Tune the pki_int secrets engine to issue certificates with a maximum time-to-live (TTL) of 43800 hours.

    $ vault secrets tune -max-lease-ttl=43800h pki_int

    $ vault secrets tune -max-lease-ttl=43800h pki_int

  3. Execute the following command to generate an intermediate and save the CSR as pki_intermediate.csr.

    $ vault write -format=json pki_int/intermediate/generate/internal \
     common_name="example.com Intermediate Authority" \
     | jq -r '.data.csr' > pki_intermediate.csr

    $ vault write -format=json pki_int/intermediate/generate/internal \     common_name="example.com Intermediate Authority" \     | jq -r '.data.csr' > pki_intermediate.csr

  4. Sign the intermediate certificate with the root CA private key, and save the generated certificate as intermediate.cert.pem.

    $ vault write -format=json pki/root/sign-intermediate csr=@pki_intermediate.csr \
     format=pem_bundle ttl="43800h" \
     | jq -r '.data.certificate' > intermediate.cert.pem

    $ vault write -format=json pki/root/sign-intermediate csr=@pki_intermediate.csr \     format=pem_bundle ttl="43800h" \     | jq -r '.data.certificate' > intermediate.cert.pem

  5. Once the CSR is signed and the root CA returns a certificate, it can be imported back into Vault.

    $ vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem

    $ vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem

»Step 3: Create a role

A role is a logical name that maps to a policy used to generate those credentials. It allows configuration parameters to control certificate common names, alternate names, the key uses that they are valid for, and more.

Here are a few noteworthy parameters:

ParamDescription
allowed_domainsSpecifies the domains of the role (used with allow_bare_domains and allow-subdomains options)
allow_bare_domainsSpecifies if clients can request certificates matching the value of the actual domains themselves
allow_subdomainsSpecifies if clients can request certificates with CNs that are subdomains of the CNs allowed by the other role options (NOTE: This includes wildcard subdomains.)
allow_glob_domainsAllows names specified in allowed_domains to contain glob patterns (e.g. ftp*.example.com)

In this step, you are going to create a role named example-dot-com.

Create a role named example-dot-com which allows subdomains.

$ vault write pki_int/roles/example-dot-com \
     allowed_domains="example.com" \
     allow_subdomains=true \
     max_ttl="720h"

$ vault write pki_int/roles/example-dot-com \     allowed_domains="example.com" \     allow_subdomains=true \     max_ttl="720h"

»Step 4: Request certificates

Keep certificate lifetimes short to align with Vault's philosophy of short-lived secrets.

Execute the following command to request a new certificate for the test.example.com domain based on the example-dot-com role.

$ vault write pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"

Key                 Value
---                 -----
certificate         -----BEGIN CERTIFICATE-----
MIIDwzCCAqugAwIBAgIUTQABMCAsXjG6ExFTX8201xKVH4IwDQYJKoZIhvcNAQEL
BQAwGjEYMBYGA1UEAxMPd3d3LmV4YW1wbGUuY29tMB4XDTE4MDcyNDIxMTMxOVoX
             ...

-----END CERTIFICATE-----
issuing_ca          -----BEGIN CERTIFICATE-----
MIIDQTCCAimgAwIBAgIUbMYp39mdj7dKX033ZjK18rx05x8wDQYJKoZIhvcNAQEL
             ...

-----END CERTIFICATE-----
private_key         -----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAte1fqy2Ekj+EFqKV6N5QJlBgMo/U4IIxwLZI6a87yAC/rDhm
W58liadXrwjzRgWeqVOoCRr/B5JnRLbyIKBVp6MMFwZVkynEPzDmy0ynuomSfJkM
             ...

-----END RSA PRIVATE KEY-----
private_key_type    rsa
serial_number       4d:00:01:30:20:2c:5e:31:ba:13:11:53:5f:cd:b4:d7:12:95:1f:82

$ vault write pki_int/issue/example-dot-com common_name="test.example.com" ttl="24h"
Key                 Value---                 -----certificate         -----BEGIN CERTIFICATE-----MIIDwzCCAqugAwIBAgIUTQABMCAsXjG6ExFTX8201xKVH4IwDQYJKoZIhvcNAQELBQAwGjEYMBYGA1UEAxMPd3d3LmV4YW1wbGUuY29tMB4XDTE4MDcyNDIxMTMxOVoX             ...
-----END CERTIFICATE-----issuing_ca          -----BEGIN CERTIFICATE-----MIIDQTCCAimgAwIBAgIUbMYp39mdj7dKX033ZjK18rx05x8wDQYJKoZIhvcNAQEL             ...
-----END CERTIFICATE-----private_key         -----BEGIN RSA PRIVATE KEY-----MIIEowIBAAKCAQEAte1fqy2Ekj+EFqKV6N5QJlBgMo/U4IIxwLZI6a87yAC/rDhmW58liadXrwjzRgWeqVOoCRr/B5JnRLbyIKBVp6MMFwZVkynEPzDmy0ynuomSfJkM             ...
-----END RSA PRIVATE KEY-----private_key_type    rsaserial_number       4d:00:01:30:20:2c:5e:31:ba:13:11:53:5f:cd:b4:d7:12:95:1f:82

The response contains the PEM-encoded private key, key type and certificate serial number.

»Step 5: Revoke certificates

If a certificate must be revoked, you can easily perform the revocation action which will cause the CRL to be regenerated. When the CRL is regenerated, any expired certificates are removed from the CRL.

In certain circumstances, you may wish to revoke an issued certificate.

To revoke a certificate, execute the following command.

$ vault write pki_int/revoke serial_number=<serial_number>

$ vault write pki_int/revoke serial_number=<serial_number>

Example:

$ vault write pki_int/revoke \
    serial_number="3f:03:a9:10:e0:28:df:dc:d8:a8:f9:50:7b:cd:d4:8c:01:f5:47:5e"

Key                        Value
---                        -----
revocation_time            1628908066
revocation_time_rfc3339    2021-08-14T02:27:46.872534Z

$ vault write pki_int/revoke \    serial_number="3f:03:a9:10:e0:28:df:dc:d8:a8:f9:50:7b:cd:d4:8c:01:f5:47:5e"
Key                        Value---                        -----revocation_time            1628908066revocation_time_rfc3339    2021-08-14T02:27:46.872534Z

»Step 6: Remove expired certificates

Keep the storage backend and CRL by periodically removing certificates that have expired and are past a certain buffer period beyond their expiration time.

To remove revoked certificate and clean the CRL.

$ vault write pki_int/tidy tidy_cert_store=true tidy_revoked_certs=true
WARNING! The following warnings were returned from Vault:

  * Tidy operation successfully started. Any information from the operation
  will be printed to Vault's server logs.

$ vault write pki_int/tidy tidy_cert_store=true tidy_revoked_certs=trueWARNING! The following warnings were returned from Vault:
  * Tidy operation successfully started. Any information from the operation  will be printed to Vault's server logs.

NOTE: The warning message is expected in every invocation of the tidy command, and serves to alert the operator that progress from the tidy operation can be observed in the Vault operational log.

»Cleanup

You can unset the two environment variables, VAULT_ADDR and VAULT_TOKEN, that you set in the beginning of this tutorial and remove the files you created to clean up.

Unset the environment variables.

$ unset VAULT_ADDR VAULT_TOKEN

$ unset VAULT_ADDR VAULT_TOKEN

Remove the files.

$ rm -f \
    CA_cert.crt \
    intermediate.cert.pem \
    pki_intermediate.csr \
    payload.json \
    payload-url.json \
    payload-int.json \
    payload-int-cert.json \
    payload-signed.json \
    payload-role.json

$ rm -f \    CA_cert.crt \    intermediate.cert.pem \    pki_intermediate.csr \    payload.json \    payload-url.json \    payload-int.json \    payload-int-cert.json \    payload-signed.json \    payload-role.json

You can terminate the Vault process from a command.

$ pgrep -f vault | xargs kill

$ pgrep -f vault | xargs kill

»Next steps

Check out the Streamline Certificate Management with HashiCorp Vault webinar recording.

Also, refer to the Vault PKI Secrets Engine Integration tutorial for an example of Nomad using the PKI secrets engine to generate and renew the X.509 certificates it uses. To automate the process, this tutorial leverages the Consul Template tool.

»Help and reference

stdin: is not a tty