Edit this page on GitHub
»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 1.11.0+ incompatible as Consul CA provider: Do not use Vault v1.11.0+ as Consul’s Connect CA provider — the intermediate CA will become unable to issue the leaf nodes required by service mesh, and by Consul client agents if using auto-encrypt or auto-config and using TLS for agent communication. If you are already using Vault 1.11+ as a Connect CA, refer to this Knowledge Base article for more information about the underlying cause and recommended workaround.
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.
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.
- Rotation Primitives - A document which explains different types of certificates used to achieve rotation.
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.