PKI secrets engine (API)
This is the API documentation for the Vault PKI secrets engine. For general information about the usage and operation of the PKI secrets engine, please see the PKI documentation.
This documentation assumes the PKI secrets engine is enabled at the /pki
path in Vault. Since it is possible to enable secrets engines at any location, please update your API calls accordingly.
Notice about new Multi-Issuer functionality
Vault since 1.11.0 allows a single PKI mount to have multiple Certificate Authority (CA) certificates ("issuers") in a single mount, for the purpose of facilitating rotation. All issuers within a single mount are treated as a single Authority, meaning that:
Certificate Revocation List (CRL) configuration is common to all issuers,
All authority access URLs are common to all issuers,
Issued certificates' serial numbers will be unique across all issuers.
However, since each issuer may have a distinct subject and keys, different issuers may have different CRLs.
It is strongly encouraged to limit the scope of CAs within a mount and not to mix different types of CAs (roots and intermediates).
Note: Some functionality will not work if a default issuer is not configured. Vault automatically selects the default issuer from the current issuing certificate on migration from an older Vault version (Vault < 1.11.0).
ACME certificate issuance
Starting with Vault 1.14, Vault supports the ACME certificate lifecycle management protocol for issuing and renewing leaf server certificates.
In order to use ACME, a cluster path must be set and ACME must be enabled in its configuration with the required headers enabled on the mount tuning.
Using ACME with a role requires no_store=false
to be set on the role; this allows the certificate to be stored and later fetched through the ACME protocol.
ACME directories
Vault PKI supports the following ACME directories, providing different restrictions around usage (defaults, a specific issuer and/or a specific role). To interact with these directories, specify the directory URL in an ACME client. For example, with the EFF's CertBot:
These endpoints are unauthenticated from a Vault authentication model, but internally authenticated via the ACME protocol.
ACME
/pki/acme/directory
sign-verbatim
default
Sign-Verbatim
ACME
/pki/acme/directory
role:role_ref
Specified by the role
:role_ref
ACME
/pki/acme/directory
external-policy(:policy)
Specified by CIEPS
CIEPS
ACME
/pki/issuer/:issuer_ref/acme/directory
sign-verbatim
:issuer_ref
Sign-Verbatim
ACME
/pki/issuer/:issuer_ref/acme/directory
role:role_ref
:issuer_ref
:role_ref
ACME
/pki/roles/:role/acme/directory
(any)
Specified by the role
:role
ACME
/pki/issuer/:issuer_ref/roles/:role/acme/directory
(any)
:issuer_ref
:role
ACME
/pki/external-policy(/:policy)/acme/directory
(any)
Specified by CIEPS
CIEPS
ACME
/pki/issuer/:issuer_ref/external-policy(/:policy)/acme/directory
(any)
Specified by CIEPS
CIEPS
When a role is not explicitly specified, behavior is specified by the default_directory_policy
in the ACME configuration. These directories can also be forbidden by setting that policy as forbid
. If the policy is sign-verbatim
then any identifier for which the client can prove ownership of will be issued for. This is similar to using the Sign Verbatim endpoint, but with additional verification that the client has proven ownership (within the ACME protocol) of the requested certificate identifiers. When external-policy
is specified as the default value, the Certificate Issuance External Policy Service (CIEPS)EnterpriseEnterprise is used for validating and templating the certificate instead of a role; ACME's challenge validation is still enforced. An optional policy name can be specified by using external-policy:policy
. Roles are not used when CIEPS is used.
ACME challenge types
Vault supports the following ACME challenge types presently:
http-01
, supporting bothdns
andip
identifiers.dns-01
, supportingdns
identifiers including wildcards.tls-alpn-01
, supporting only non-wildcarddns
identifiers.
A custom DNS resolver used by the server for looking up DNS names for use with both mechanisms can be added via the ACME configuration.
ACME external account bindings
ACME External Account Binding (EAB) Policy can enforce that clients need to have a valid external account binding to Vault. Before registering a new account, an authenticated Vault client will need to fetch a new EAB token. This returns two values: a key identifier and an HMAC key used by the ACME client to authenticate with EAB. For example:
With or without EAB, requests from the ACME client are not authenticated using traditional Vault authentication, but are instead authenticated through the ACME protocol. With EAB however, a Vault authenticated client will have to fetch an EAB token and pass it to the ACME client for use on the initial registration: this binds the ACME client's registration to an authenticated Vault endpoint, but not further to the client's entity or other information.
Note: Enabling EAB is strongly recommended for public-facing Vault deployments. Use of the VAULT_DISABLE_PUBLIC_ACME
environment variable can be used to enforce all ACME instances have EAB enabled.
ACME accounts
ACME Accounts are created specific to a particular directory and are not portable across Performance Secondary clusters.
ACME required headers
ACME requires the following response headers (allowed_response_headers
) to be specified by mount tuning:
Replay-Nonce
Link
Location
On an existing mount, these can be specified by running the following command:
Get ACME EAB binding token
This endpoint returns a new ACME binding token. The id
response field can be used as the key identifier and the key
response field be used as the EAB HMAC key in the ACME Client.
Each call to this endpoint will generate and return a new EAB binding token that is linked to the specific ACME directory it resides under. EAB tokens are not usable across different ACME directories.
POST
/pki/acme/new-eab
POST
/pki/issuer/:issuer_ref/acme/new-eab
POST
/pki/roles/:role/acme/new-eab
POST
/pki/issuer/:issuer_ref/roles/:role/acme/new-eab
Parameters
No parameters.
Sample request
Sample response
List unused ACME EAB binding tokens
This endpoint returns a list of all unused ACME binding tokens; once used, they will be removed from this list.
LIST
/pki/eab
Sample request
Sample response
Delete unused ACME EAB binding tokens
This endpoint allows the deletion of an unus