PKI secrets engine
Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround starting in Vault 1.12. See the deprecation FAQ for more information.
Vault as Consul CA provider: If you are using Vault 1.11.0+ as a Connect CA, run a Consul version which includes the fix for GH-15525. Refer to this Knowledge Base article for more details.
The PKI secrets engine generates dynamic X.509 certificates. With this secrets engine, services can get certificates without going through the usual manual process of generating a private key and CSR, submitting to a CA, and waiting for a verification and signing process to complete. Vault's built-in authentication and authorization mechanisms provide the verification functionality.
By keeping TTLs relatively short, revocations are less likely to be needed, keeping CRLs short and helping the secrets engine scale to large workloads. This in turn allows each instance of a running application to have a unique certificate, eliminating sharing and the accompanying pain of revocation and rollover.
In addition, by allowing revocation to mostly be forgone, this secrets engine allows for ephemeral certificates. Certificates can be fetched and stored in memory upon application startup and discarded upon shutdown, without ever being written to disk.
Table of contents
The PKI Secrets Engine documentation is split into the following pieces:
- Overview - this document.
- Setup and Usage - a brief description of setting up and using the PKI Secrets Engine to issue certificates.
- Quick Start - Root CA Setup - A quick start guide for setting up a root CA.
- Quick Start - Intermediate CA Setup - A quick start guide for setting up an intermediate CA.
- Considerations - A list of helpful considerations to keep in mind when using and operating the PKI Secrets Engine.
- Troubleshooting ACME - A list of advice for troubleshooting failures with ACME issuance and Vault PKI.
- Rotation Primitives - A document which explains different types of certificates used to achieve rotation.
- CIEPS Protocol Enterprise - A
document which explains the Certificate Issuance External Policy Service (CIEPS)
protocol (request and response structure), along with an overview of the difference
between it and
/pki/sign-verbatim.
Tutorial
Refer to the following tutorials for PKI secrets engine usage examples:
- Build Your Own Certificate Authority (CA)
- Build Certificate Authority (CA) in Vault with an offline Root
- Enable ACME with PKI secrets engine
- PKI Secrets Engine with Managed Keys
- PKI Unified CRL and OCSP With Cross Cluster Revocation
- Configure Vault as a Certificate Manager in Kubernetes with Helm
- Generate mTLS Certificates for Nomad using Vault
API
The PKI secrets engine has a full HTTP API. Please see the PKI secrets engine API for more details.