Standard Issuance Protocols (API)
- ACME Certificate Issuance
- EST - Certificate Issuance Enterprise
- CMPv2 - Certificate Management Protocol (v2) Enterprise
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.
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)Enterprise 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:
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.
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
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.
Method | Path |
---|---|
LIST | /pki/eab |
Sample request
Sample response
Delete unused ACME EAB binding tokens
This endpoint allows the deletion of an unused ACME binding token.
Method | Path |
---|---|
DELETE | /pki/eab/:key_id |
Parameters
key_id
(string: <required>)
- The id of the EAB binding token to delete. This is part of the request URL.
Sample request
Get ACME configuration
This endpoint allows reading of the current ACME server configuration used by this mount.
Method | Path |
---|---|
GET | /pki/config/acme |
Sample request
Sample response
Set ACME configuration
This endpoint allows setting the ACME server configuration used by this mount.
Method | Path |
---|---|
POST | /pki/config/acme |
Parameters
allowed_issuers
(list: ["*"])
- Specifies a list issuers allowed to issue certificates via explicit ACME paths. If an allowed role specifies an issuer outside this list, it will be allowed. The default value*
allows every issuer within the mount.allow_role_ext_key_usage
(bool: false)
- whether the ExtKeyUsage field from a role is used, defaults to false meaning that certificate will be signed with ServerAuth.allowed_roles
(list: ["*"])
- Specifies a list of roles allowed to issue certificates via explicit ACME paths. The default value*
allows every role within the mount to be used. If thedefault_directory_policy
specifies a role, it must be allowed under this configuration.default_directory_policy
(string: "sign-verbatim")
- Specifies the behavior of the default ACME directory. Can beforbid
,sign-verbatim
or a role given byrole:<role_name>
. If a role is used, it must be present inallowed_roles
.dns_resolver
(string: "")
- An optional overriding DNS resolver to use for challenge verification lookups. When not specified, the default system resolver will be used. This allows domains on peered networks with an accessible DNS resolver to be validated.eab_policy
(string: "not-required")
- Specified policy to enforce around External Account Bindings (EABs). The allowed values are:not-required
, where EABs are not enforced but are validated if specified.new-account-required
, where new accounts are required to have EAB but existing accounts can still be used.always-required
, where all accounts regardless of age are required to have EABs set.
enabled
(bool: false)
- Whether ACME is enabled on this mount. When ACME is disabled, all requests to ACME directory URLs will return 404.max_ttl
(string: "")
- Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If not set, defaults to the previous hard-coded behavior of 90 days (2160 hours).
Sample payload
Sample request
Sample response
EST Certificate issuance Enterprise
Within Vault Enterprise, support can be enabled for the EST (Enrollment over Secure Transport) protocol for issuing and renewing leaf certificates.
EST Protocol Paths Enterprise
These are the EST protocol API paths currently supported from Vault's authentication
point of view. Note that the cacerts
endpoint is unauthenticated.
Path | Default Policy Path | Issuer | Role |
---|---|---|---|
/pki/est/{cacerts, simpleenroll, simplereenroll} | sign-verbatim | default | Sign-Verbatim |
/pki/est/{cacerts, simpleenroll, simplereenroll} | role:role_ref | Specified by the role | :role_ref |
/pki/roles/:role/est/{cacerts, simpleenroll, simplereenroll} | (any) | Specified by the role | :role |
Read EST Configuration Enterprise
This endpoint fetches the current EST configuration.
Method | Path |
---|---|
GET | /pki/config/est |
Sample request
Sample response
Set EST Configuration Enterprise
This endpoint will update EST related configuration, returning the
updated values as a response along with an updated last_updated
field.
Method | Path |
---|---|
POST | /pki/config/est |
Parameters
enabled
(bool: false)
- Specifies whether EST is enabled or not.default_mount
(bool: false)
- Should this mount register the default .well-known/est URL path. Only a single mount can enable this across a Vault clusterdefault_path_policy
(string: "")
- Required to be set ifdefault_mount
is enabled. Specifies the behavior for requests using the default EST label. Can besign-verbatim
or a role given byrole:<role_name>
.label_to_path_policy
(map[string]string: "")
- Configures a pairing of an EST label with the redirected behavior for requests hitting that role. The path policy can besign-verbatim
or a role given byrole:<role_name>
. Labels must be unique across Vault cluster, and will register.well-known/est/<label>
URL paths.authenticators
(map[string]map[string]string: "")
- Specifies the mount accessors EST should delegate authentication requests. Map keys can be eithercert
oruserpass
, with associated maps containing the keyaccessor
with a value containing the auth mount's accessor. For thecert
type, an optional keycert_role
parameter is supported which will be passed as the name parameter during certificate authentication attempts.enable_sentinel_parsing
(bool: false)
- Parse out fields from the provided CSR making them available for Sentinel policies.audit_fields
(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])
- Fields parsed from the CSR that appear in the audit and can be used by sentinel policies. Allowed values arecsr
,common_name
,alt_names
,ip_sans
,uri_sans
,other_sans
,signature_bits
,exclude_cn_from_sans
,ou
,organization
,country
,locality
,province
,street_address
,postal_code
,serial_number
,use_pss
,key_type
,key_bits
,add_basic_constraints
Sample Payload
Sample request
Sample response
CMPv2 Certificate issuance Enterprise
Within Vault Enterprise, support can be enabled for the CMPv2 (Certificate Management Protocol) protocol for issuing and renewing leaf certificates.
CMPv2 Protocol Paths Enterprise
These are the CMP protocol API paths currently supported from Vault's authentication point of view.
Read CMPv2 Configuration Enterprise
This endpoint fetches the current CMPv2 configuration.
Method | Path |
---|---|
GET | /pki/config/cmp |
Sample request
Sample response
Set CMPv2 Configuration Enterprise
This endpoint will update CMPv2 related configuration, returning the
updated values as a response along with an updated last_updated
field.
Method | Path |
---|---|
POST | /pki/config/cmp |
Parameters
enabled
(bool: false)
- Specifies whether CMPv2 is enabled or not.authenticators
(map[string]map[string]string: "")
- Specifies the mount accessors CMPv2 should delegate authentication requests. Map key can only becert
, with associated value containing the keyaccessor
with a value containing the auth mount's accessor. An optional keycert_role
parameter is supported which will be passed as the name parameter during certificate authentication attempts.default_path_policy
(string: required)
: Specify the default issuance policy when the non role based cmp path is called. Must be set to eithersign-verbatim
(to issue via the sign-verbatim function) orrole:
followed by the name of a configured role.enable_sentinel_parsing
(bool: false)
- Parse out fields from the provided CSR making them available for Sentinel policies.audit_fields
(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])
- Fields parsed from the CSR that appear in the audit and can be used by sentinel policies. Allowed values arecsr
,common_name
,alt_names
,ip_sans
,uri_sans
,other_sans
,signature_bits
,exclude_cn_from_sans
,ou
,organization
,country
,locality
,province
,street_address
,postal_code
,serial_number
,use_pss
,key_type
,key_bits
,add_basic_constraints
Sample Payload
Sample request
Sample response