PKI secrets engine - setup and usage

This document provides a brief overview of the setup and usage of the PKI Secrets Engine.

Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

1. Enable the PKI secrets engine:

   $ vault secrets enable pki
   Success! Enabled the pki secrets engine at: pki/
   

   Copy

   By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

2. Increase the TTL by tuning the secrets engine. The default value of 30 days may be too short, so increase it to 1 year:

   $ vault secrets tune -max-lease-ttl=8760h pki
   Success! Tuned the secrets engine at: pki/
   

   Copy

   Note that individual roles can restrict this value to be shorter on a per-certificate basis. This just configures the global maximum for this secrets engine.

3. Configure a CA certificate and private key. Vault can accept an existing key pair, or it can generate its own self-signed root. In general, we recommend maintaining your root CA outside of Vault and providing Vault a signed intermediate CA.

   $ vault write pki/root/generate/internal \
       common_name=my-website.com \
       ttl=8760h
   
   Key              Value
   ---              -----
   certificate      -----BEGIN CERTIFICATE-----...
   expiration       1536807433
   issuing_ca       -----BEGIN CERTIFICATE-----...
   serial_number    7c:f1:fb:2c:6e:4d:99:0e:82:1b:08:0a:81:ed:61:3e:1d:fa:f5:29
   

   Copy

   The returned certificate is purely informative. The private key is safely stored internally in Vault.

4. Update the CRL location and issuing certificates. These values can be updated in the future.

   $ vault write pki/config/urls \
       issuing_certificates="http://127.0.0.1:8200/v1/pki/ca" \
       crl_distribution_points="http://127.0.0.1:8200/v1/pki/crl"
   Success! Data written to: pki/config/urls
   

   Copy

5. Configure a role that maps a name in Vault to a procedure for generating a certificate. When users or machines generate credentials, they are generated against this role:

   $ vault write pki/roles/example-dot-com \
       allowed_domains=my-website.com \
       allow_subdomains=true \
       max_ttl=72h
   Success! Data written to: pki/roles/example-dot-com
   

   Copy

Usage

After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials.

1. Generate a new credential by writing to the /issue endpoint with the name of the role:

   $ vault write pki/issue/example-dot-com \
       common_name=www.my-website.com
   
   Key                 Value
   ---                 -----
   certificate         -----BEGIN CERTIFICATE-----...
   issuing_ca          -----BEGIN CERTIFICATE-----...
   private_key         -----BEGIN RSA PRIVATE KEY-----...
   private_key_type    rsa
   serial_number       1d:2e:c6:06:45:18:60:0e:23:d6:c5:17:43:c0:fe:46:ed:d1:50:be
   

   Copy

   The output will include a dynamically generated private key and certificate which corresponds to the given role and expires in 72h (as dictated by our role definition). The issuing CA and trust chain is also returned for automation simplicity.

Tutorial

Refer to the Build Your Own Certificate Authority (CA) guide for a step-by-step tutorial.

Have a look at the PKI Secrets Engine with Managed Keys for more about how to use externally managed keys with PKI.

API

The PKI secrets engine has a full HTTP API. Please see the PKI secrets engine API for more details.