PKI secrets engine - setup and usage
This document provides a brief overview of the setup and usage of the PKI Secrets Engine.
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.
Enable the PKI secrets engine:
$ vault secrets enable pki Success! Enabled the pki secrets engine at: pki/
By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the
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/
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.
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
The returned certificate is purely informative. The private key is safely stored internally in Vault.
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
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
After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials.
Generate a new credential by writing to the
/issueendpoint 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
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.
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.
The PKI secrets engine has a full HTTP API. Please see the PKI secrets engine API for more details.