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:

1. Certificate Revocation List (CRL) configuration is common to all issuers,

2. All authority access URLs are common to all issuers,

3. 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:

$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory ...

These endpoints are unauthenticated from a Vault authentication model, but internally authenticated via the ACME protocol.

Method	Path	Default Directory Policy	Issuer	Role
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 both dns and ip identifiers.

• dns-01, supporting dns identifiers including wildcards.

• tls-alpn-01, supporting only non-wildcard dns 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:

$ vault write -f /pki/acme/new-eab
$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory \
                   --eab-kid <id> --eab-hmac-key <hmac-key>

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:

$ vault secrets tune -allowed-response-headers=Location -allowed-response-headers=Replay-Nonce \
                     -allowed-response-headers=Link \
                     pki/

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.

Method	Path
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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/pki/acme/new-eab

Sample response

{
  "data": {
    "created_on": "2023-05-24T14:33:00-04:00",
    "id": "bc8088d9-3816-5177-ae8e-d8393265f7dd",
    "key_type": "hs",
    "acme_directory": "acme/directory",
    "key": "MHcCAQE... additional data elided ...",
  }
}

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.

Method	Path
LIST	/pki/eab

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/eab

Sample response

{
  "data": {
    "key_info": {
      "bc8088d9-3816-5177-ae8e-d8393265f7dd": {
        "created_on": "2023-05-24T14:33:00-04:00",
        "key_type": "hs",
        "acme_directory": "acme/directory"
      }
    },
    "keys": [
      "bc8088d9-3816-5177-ae8e-d8393265f7dd"
    ]
  }
}

Delete unused ACME EAB binding tokens

This endpoint allows the deletion of an unus