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 bothdnsandipidentifiers.dns-01, supportingdnsidentifiers including wildcards.tls-alpn-01, supporting only non-wildcarddnsidentifiers.
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-NonceLinkLocation
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 unused ACME binding token.
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.
GET
/pki/config/acme
Sample request
Sample response
Set ACME configuration
This endpoint allows setting the ACME server configuration used by this mount.
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_policyspecifies 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-verbatimor 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.
Sample payload
Sample request
Sample response
Issuing certificates
The following API endpoints allow users or operators to request certificates and are all authenticated.
In general, for self-serve use, the /pki/sign/:name and /pki/issue/:name are sufficient to allow most users to access for ACL purposes. The per-issuer variants (/pki/issuer/:issuer_ref/sign/:name and /pki/issuer/:issuer_ref/issue/:name) allow the requester to override the role's chosen issuer, potentially allowing users to request certificates issued by the wrong parent authority.
Some API endpoints included here are privileged and should only be accessed by trusted users or operators; these include the various sign-verbatim, sign-self-signed and sign-intermediate endpoints.
If an issued certificate has been compromised, it should be revoked. The Vault PKI secrets engine presently only allows revocation by serial number; because this could allow users to deny access to other users, it should be restricted to operators.
List roles
This endpoint returns a list of available roles. Only the role names are returned, not any values. It is useful to both operators and users.
LIST
/pki/roles
Sample request
Sample response
Read role
This endpoint queries the role definition. It is useful to both operators and users.
GET
/pki/roles/:name
Parameters
name(string: <required>)- Specifies the name of the role to read. This is part of the request URL.
Sample request
Sample response
Generate certificate and key
This endpoint generates a new set of credentials (private key and certificate) based on the role named in the endpoint. The issuing CA certificate and full CA chain is returned as well, so that only the root CA need be in a client's trust store. Choice of issuing CA is determined first by the role (when using the /pki/issue/:name path) and then by the path (when using the /pki/issuer/:issuer_ref/issue/name path).
It is suggested to limit access to the path-overridden issue endpoint (on /pki/issuer/:issuer_ref/issue/:name).
Note: The private key is not stored. If you do not save the private key from the response, you will need to request a new certificate.
POST
/pki/issue/:name
Role selected
POST
/pki/issuer/:issuer_ref/issue/:name
Path selected
Parameters
name(string: <required>)- Specifies the name of the role to create the certificate against. This is part of the request URL.issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/issue/:name path and takes its value from the role's issuer_ref field.
common_name(string: "")- Specifies the requested CN for the certificate. If the CN is allowed by role policy, it will be issued. If more than onecommon_nameis desired, specify the alternative names in thealt_nameslist.
Note: A value for common_name is required when require_cn is set to true
alt_names(string: "")- Specifies requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will be parsed into their respective fields. If any requested names do not match role policy, the entire request will be denied.ip_sans(string: "")- Specifies requested IP Subject Alternative Names, in a comma-delimited list. Only valid if the role allows IP SANs (which is the default).uri_sans(string: "")- Specifies the requested URI Subject Alternative Names, in a comma-delimited list. If any requested URIs do not match role policy, the entire request will be denied.other_sans(string: "")- Specifies custom OID/UTF8-string SANs. These must match values specified on the role inallowed_other_sans(see role creation for allowed_other_sans globbing rules). The format is the same as OpenSSL:<oid>;<type>:<value>where the only current valid type isUTF8. This can be a comma-delimited list or a JSON string slice.ttl(string: "")- Specifies requested Time To Live. Cannot be greater than the role'smax_ttlvalue. If not provided, the role'sttlvalue will be used. Note that the role values default to system values if not explicitly set. Seenot_afteras an alternative for setting an absolute end date (rather than a relative one).format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle; defaults topem. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the private key and certificate, concatenated; if the issuing CA is not a Vault-derived self-signed root, this will be included as well.private_key_format(string: "der")- Specifies the format for marshaling the private key within the private_key response field. Defaults toderwhich will return either base64-encoded DER or PEM-encoded DER, depending on the value offormat. The other option ispkcs8which will return the key marshalled as PEM-encoded PKCS8.
Note that this does not apply to the private key within the certificate field if format=pem_bundle parameter is specified.
exclude_cn_from_sans(bool: false)- If true, the givencommon_namewill not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some human-readable identifier.not_after(string)- Set the Not After field of the certificate with specified date value. The value format should be given in UTC formatYYYY-MM-ddTHH:MM:SSZ. Supports the Y10K end date for IEEE 802.1AR-2018 standard devices,9999-12-31T23:59:59Z.remove_roots_from_chain(bool: false)- If true, the returnedca_chainfield will not include any self-signed CA certificates. Useful if end-users already have the root CA in their trust store.user_ids(string: "")- Specifies the comma-separated list of requested User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the signed certificate. This field is validated againstallowed_user_idson the role.
Sample payload
Sample request
Sample response
Generate certificate and key with external policy EnterpriseEnterprise
Similar to the generate certificate and key endpoint, this endpoint generate key material and certificate via an external policy engine. The private key material stays local to Vault, with the external service getting only an empty CSR. Any parameters passed to this endpoint are passed verbatim to the Certificate Issuance External Policy Service (CIEPS)EnterpriseEnterprise. The response format is the same between both endpoints.
It is suggested to limit access to the path-overridden issue endpoint (on /pki/issuer/:issuer_ref/external-policy/issue/:policy) and let the CIEPS engine override the issuer as necessary.
POST
/pki/external-policy/issue(/:policy)
default or CIEPS-selected
POST
/pki/issuer/:issuer_ref/external-policy/issue(/:policy)
Path or CIEPS selected
Parameters
policy(string: <optional>)- Specifies the name of the policy to create the certificate against. This is part of the request URL and is passed to the external CIEPS engine.issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/external-policy/sign/:policy path and takes its value from the CIEPS engine response's issuer_ref field, which can override the user-requested issuer.
format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle; defaults topem. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the private key and certificate, concatenated; if the issuing CA is not a Vault-derived self-signed root, this will be included as well.key_type(string: "rsa")- Specifies the desired key type; must bersa,ed25519orec.
Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.
key_bits(int: 0)- Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); withkey_type=rsa, allowed values are: 2048 (default), 3072, or 4096; withkey_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored withkey_type=ed25519.private_key_format(string: "der")- Specifies the format for marshaling the private key within the private_key response field. Defaults toderwhich will return either base64-encoded DER or PEM-encoded DER, depending on the value offormat. The other option ispkcs8which will return the key marshalled as PEM-encoded PKCS8.
Note that this does not apply to the private key within the certificate field if format=pem_bundle parameter is specified.
remove_roots_from_chain(bool: false)- If true, the returnedca_chainfield will not include any self-signed CA certificates. Useful if end-users already have the root CA in their trust store.
Other parameters may be specified and will not be parsed by Vault but may be recognized based on external CIEPS engine definition.
Sample payload
Sample response
Sign certificate
This endpoint signs a new certificate based upon the provided CSR and the supplied parameters, subject to the restrictions contained in the role named in the endpoint. The issuing CA certificate and the full CA chain is returned as well, so that only the root CA need be in a client's trust store.
It is suggested to limit access to the path-overridden sign endpoint (on /pki/issuer/:issuer_ref/sign/:name).
POST
/pki/sign/:name
Role selected
POST
/pki/issuer/:issuer_ref/sign/:name
Path selected
Parameters
name(string: <required>)- Specifies the name of the role to create the certificate against. This is part of the request URL.issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/sign/:name path and takes its value from the role's issuer_ref field.
csr(string: <required>)- Specifies the PEM-encoded CSR.common_name(string: <required>)- Specifies the requested CN for the certificate. If the CN is allowed by role policy, it will be issued. If more than onecommon_nameis desired, specify the alternative names in thealt_nameslist.alt_names(string: "")- Specifies the requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will be parsed into their respective fields. If any requested names do not match role policy, the entire request will be denied.other_sans(string: "")- Specifies custom OID/UTF8-string SANs. These must match values specified on the role inallowed_other_sans(see role creation for allowed_other_sans globbing rules). The format is the same as OpenSSL:<oid>;<type>:<value>where the only current valid type isUTF8. This can be a comma-delimited list or a JSON string slice.ip_sans(string: "")- Specifies the requested IP Subject Alternative Names, in a comma-delimited list. Only valid if the role allows IP SANs (which is the default).uri_sans(string: "")- Specifies the requested URI Subject Alternative Names, in a comma-delimited list. If any requested URIs do not match role policy, the entire request will be denied.ttl(string: "")- Specifies the requested Time To Live. Cannot be greater than the role'smax_ttlvalue. If not provided, the role'sttlvalue will be used. Note that the role values default to system values if not explicitly set. Seenot_afteras an alternative for setting an absolute end date (rather than a relative one).format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the certificate and, if the issuing CA is not a Vault-derived self-signed root, it will be concatenated with the certificate.exclude_cn_from_sans(bool: false)- If true, the givencommon_namewill not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some human-readable identifier.not_after(string)- Set the Not After field of the certificate with specified date value. The value format should be given in UTC formatYYYY-MM-ddTHH:MM:SSZ. Supports the Y10K end date for IEEE 802.1AR-2018 standard devices,9999-12-31T23:59:59Z.remove_roots_from_chain(bool: false)- If true, the returnedca_chainfield will not include any self-signed CA certificates. Useful if end-users already have the root CA in their trust store.user_ids(string: "")- Specifies the comma-separated list of requested User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the signed certificate. This field is validated againstallowed_user_idson the role.
Sample payload
Sample response
Sign certificate with external policy EnterpriseEnterprise
Similar to the sign certificate endpoint, this endpoint signs the specified leaf CSR via an external policy engine. Any parameters passed to this endpoint are passed verbatim to the Certificate Issuance External Policy Service (CIEPS)EnterpriseEnterprise. The response format is the same between both endpoints.
It is suggested to limit access to the path-overridden sign endpoint (on /pki/issuer/:issuer_ref/external-policy/sign/:policy) and let the CIEPS engine override the issuer as necessary.
POST
/pki/external-policy/sign(/:policy)
default or CIEPS-selected
POST
/pki/issuer/:issuer_ref/external-policy/sign(/:policy)
Path or CIEPS selected
Parameters
policy(string: <optional>)- Specifies the name of the policy to create the certificate against. This is part of the request URL and is passed to the external CIEPS engine.issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/external-policy/sign/:policy path and takes its value from the CIEPS engine response's issuer_ref field, which can override the user-requested issuer.
csr(string: <required>)- Specifies the PEM-encoded CSR.format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle; defaults topem. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the private key and certificate, concatenated; if the issuing CA is not a Vault-derived self-signed root, this will be included as well.private_key_format(string: "der")- Specifies the format for marshaling the private key within the private_key response field. Defaults toderwhich will return either base64-encoded DER or PEM-encoded DER, depending on the value offormat. The other option ispkcs8which will return the key marshalled as PEM-encoded PKCS8.
Note that this does not apply to the private key within the certificate field if format=pem_bundle parameter is specified.
remove_roots_from_chain(bool: false)- If true, the returnedca_chainfield will not include any self-signed CA certificates. Useful if end-users already have the root CA in their trust store.
Other parameters may be specified and will not be parsed by Vault but may be recognized based on external CIEPS engine definition.
Sample payload
Sample response
Sign intermediate
This endpoint uses the configured CA certificate to issue a certificate with appropriate values for acting as an intermediate CA. Distribution points use the values set via config/urls. Values set in the CSR are ignored unless use_csr_values is set to true, in which case the values from the CSR are used verbatim.
This endpoint can be used both when signing a Vault-backed intermediate or when signing an externally-owned intermediate.
Note: This is a privileged endpoint, as callers are granted a new intermediate certificate, with which they can issue for arbitrary names. Access to this endpoint should be restricted by policy to only trusted operators.
POST
/pki/root/sign-intermediate
default
POST
/pki/issuer/:issuer_ref/sign-intermediate
Selected
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/root/sign-intermediate path and takes the value default.
csr(string: <required>)- Specifies the PEM-encoded CSR to be signed.common_name(string: <required>)- Specifies the requested CN for the certificate. If more than onecommon_nameis desired, specify the alternative names in thealt_nameslist.alt_names(string: "")- Specifies the requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will be parsed into their respective fields.ip_sans(string: "")- Specifies the requested IP Subject Alternative Names, in a comma-delimited list.uri_sans(string: "")- Specifies the requested URI Subject Alternative Names, in a comma-delimited list.other_sans(string: "")- Specifies custom OID/UTF8-string SANs. These must match values specified on the role inallowed_other_sans(see role creation for allowed_other_sans globbing rules). The format is the same as OpenSSL:<oid>;<type>:<value>where the only current valid type isUTF8. This can be a comma-delimited list or a JSON string slice.ttl(string: "")- Specifies the requested Time To Live (after which the certificate will be expired). This cannot be larger than the engine's max (or, if not set, the system max). However, this can be after the expiration of the signing CA. Seenot_afteras an alternative for setting an absolute end date (rather than a relative one).format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the certificate and, if the issuing CA is not a Vault-derived self-signed root, it will be concatenated with the certificate.max_path_length(int: -1)- Specifies the maximum path length to encode in the generated certificate.-1, means no limit, unless the signing certificate has a maximum path length set, in which case the path length is set to one less than that of the signing certificate. A limit of0means a literal path length of zero.exclude_cn_from_sans(bool: false)- If true, the givencommon_namewill not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some human-readable identifier.use_csr_values(bool: false)- If set totrue, then: 1) Subject information, including names and alternate names, will be preserved from the CSR rather than using the values provided in the other parameters to this path; 2) Any key usages (for instance, non-repudiation) requested in the CSR will be added to the basic set of key usages used for CA certs signed by this path; 3) Extensions requested in the CSR will be copied into the issued certificate.permitted_dns_domains(string: "")- A comma separated string (or, string array) containing DNS domains for which certificates are allowed to be issued or signed by this CA certificate. Supports subdomains via a.in front of the domain, as per RFC 5280 Section 4.2.1.10 - Name Constraintsou(string: "")- Specifies the OU (OrganizationalUnit) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.organization(string: "")- Specifies the O (Organization) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.country(string: "")- Specifies the C (Country) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.locality(string: "")- Specifies the L (Locality) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.province(string: "")- Specifies the ST (Province) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.street_address(string: "")- Specifies the Street Address values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.postal_code(string: "")- Specifies the Postal Code values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.serial_number(string: "")- - Specifies the requested Subject's named Serial Number value, if any. If you want more than one, specify alternative names in thealt_namesmap using OID 2.5.4.5. Note that this has no impact on the Certificate's serial number field, which Vault randomly generates.not_before_duration(duration: "30s")- Specifies the duration by which to backdate the NotBefore property. This value has no impact in the validity period of the requested certificate, specified in thettlfield. Uses duration format strings.not_after(string)- Set the Not After field of the certificate with specified date value. The value format should be given in UTC formatYYYY-MM-ddTHH:MM:SSZ. Supports the Y10K end date for IEEE 802.1AR-2018 standard devices,9999-12-31T23:59:59Z.signature_bits(int: 0)- Specifies the number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
Note: ECDSA and Ed25519 issuers do not follow configuration of the signature_bits value; only RSA issuers will change signature types based on this parameter.
skid(string: "")- Value for the Subject Key Identifier field (RFC 5280 Section 4.2.1.2). Specified as a string in hex format. Default is empty, allowing Vault to automatically calculate the SKID according to method one in the above RFC section.
Note: This value should ONLY be used when cross-signing to mimic the existing certificate's SKID value; this is necessary to allow certain TLS implementations (such as OpenSSL) which use SKID/AKID matches in chain building to restrict possible valid chains.
use_pss(bool: false)- Specifies whether or not to use PSS signatures over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for ECDSA/Ed25519 issuers.
Sample payload
Sample request
Sample response
Sign Intermediate with External Policy EnterpriseEnterprise
Similar to sign intermediate, this endpoint accepts a CSR and returns a certificate with appropriate values for acting as an intermediate CA via an external policy engine. Any parameters passed to this endpoint are passed verbatim to the Certificate Issuance External Policy Service (CIEPS)EnterpriseEnterprise. The response format is the same between both endpoints.
It is suggested to limit access to the path-overridden issue endpoint (on /pki/issuer/:issuer_ref/external-policy/issue/:policy) and let the CIEPS engine override the issuer as necessary.
POST
/pki/external-policy/sign-intermediate(/:policy)
default or CIEPS-selected
POST
/pki/issuer/:issuer_ref/external-policy/sign-intermediate(/:policy)
Path or CIEPS selected
Parameters
policy(string: <optional>)- Specifies the name of the policy to create the certificate against. This is part of the request URL and is passed to the external CIEPS engine.issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/external-policy/sign-intermediate path and takes its value from the CIEPS engine response's issuer_ref field, which can override the user-requested issuer.
csr(string: <required>)- Specifies the PEM-encoded CSR.format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle; defaults topem. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the private key and certificate, concatenated; if the issuing CA is not a Vault-derived self-signed root, this will be included as well.private_key_format(string: "pem")- Specifies the format for marshaling the private key within the private_key response field. Defaults toderwhich will return either base64-encoded DER or PEM-encoded DER, depending on the value offormat. The other option ispkcs8which will return the key marshalled as PEM-encoded PKCS8.
Note that this does not apply to the private key within the certificate field if format=pem_bundle parameter is specified.
Other parameters may be specified and will not be parsed by Vault but may be recognized based on external CIEPS engine definition.
Sample payload
Sample response
Sign Self-Issued
This endpoint uses the configured CA certificate to sign a self-issued certificate (which will usually be a self-signed certificate as well).
This is an extremely privileged endpoint. The given certificate will be signed as-is with only minimal validation performed (is it a CA cert, and is it actually self-issued). The only values that will be changed will be the authority key ID, the issuer DN, and, if set, any distribution points. It is recommended to limit this endpoint to only trusted operators.
This is generally only needed for root certificate rolling in cases where you don't want/can't get access to a CSR (such as if it's a root stored in Vault where the key is not exposed). If you don't know whether you need this endpoint, you most likely should be using a different endpoint (such as sign-intermediate).
Method
Path
Issuer
Requires sudo capability
POST
/pki/root/sign-self-issued
default
yes
POST
/pki/issuer/:issuer_ref/sign-self-issued
Selected
no
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/root/sign-self-issued path and takes the value default.
certificate(string: <required>)- Specifies the PEM-encoded self-issued certificate.require_matching_certificate_algorithms(bool: false)- If true, requires that the public key algorithm of the CA match that of the submitted certificate.
Sample payload
Sample request
Sample response
Sign verbatim
This endpoint signs a new certificate based upon the provided CSR. Values are taken verbatim from the CSR; the only restriction is that this endpoint will refuse to issue an intermediate CA certificate (see the /pki/root/sign-intermediate endpoint for that functionality.)
This is a potentially dangerous endpoint and only highly trusted users should have access.
POST
/pki/sign-verbatim(/:name)
default
POST
/pki/issuer/:issuer_ref/sign-verbatim(/:name)
Selected
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/root/sign-self-issued path and takes the value default.
name(string: "")- Specifies a role. If set, the following parameters from the role will have effect:ttl,max_ttl,generate_lease,no_storeandnot_before_duration.csr(string: <required>)- Specifies the PEM-encoded CSR.key_usage(list: ["DigitalSignature", "KeyAgreement", "KeyEncipherment"])- Specifies the default key usage constraint on the issued certificate. Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage - simply drop theKeyUsagepart of the value. Values are not case-sensitive. To specify no default key usage constraints, set this to an empty list.
Note: previous versions of this document incorrectly called this a constraint; this value is only used as a default when the KeyUsage extension is missing from the CSR.
ext_key_usage(list: [])- Specifies the default extended key usage constraint on the issued certificate. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage - simply drop theExtKeyUsagepart of the value. Values are not case-sensitive. To specify no key default usage constraints, set this to an empty list.
Note: previous versions of this document incorrectly called this a constraint; this value is only used as a default when the ExtendedKeyUsage extension is missing from the CSR.
ext_key_usage_oids(string: "")- A comma-separated string or list of extended key usage oids.
Note: This value is only used as a default when the ExtendedKeyUsage extension is missing from the CSR.
ttl(string: "")- Specifies the requested Time To Live. Cannot be greater than the engine'smax_ttlvalue. If not provided, the engine'sttlvalue will be used, which defaults to system values if not explicitly set. Seenot_afteras an alternative for setting an absolute end date (rather than a relative one).format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the certificate and, if the issuing CA is not a Vault-derived self-signed root, it will be concatenated with the certificate.not_after(string)- Set the Not After field of the certificate with specified date value. The value format should be given in UTC formatYYYY-MM-ddTHH:MM:SSZ. Supports the Y10K end date for IEEE 802.1AR-2018 standard devices,9999-12-31T23:59:59Z.signature_bits(int: 0)- Specifies the number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
Note: ECDSA and Ed25519 issuers do not follow configuration of the signature_bits value; only RSA issuers will change signature types based on this parameter.
use_pss(bool: false)- Specifies whether or not to use PSS signatures over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for ECDSA/Ed25519 issuers.remove_roots_from_chain(bool: false)- If true, the returnedca_chainfield will not include any self-signed CA certificates. Useful if end-users already have the root CA in their trust store.user_ids(string: "")- Specifies the comma-separated list of requested User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the signed certificate. No validation on names is performed using this endpoint.
Sample payload
Sample request
Sample response
Revoke certificate
This endpoint revokes a certificate using its serial number. This is an alternative option to the standard method of revoking using Vault lease IDs. A successful revocation will rotate the CRL.
Note: This operation is privileged as it allows revocation of arbitrary certificates based purely on their serial number. It does not validate that the requesting user issued the certificate or has possession of the private key. It is not possible to revoke issuers using this path.
POST
/pki/revoke
Parameters
Note: either serial_number or certificate (but not both) must be specified on requests to this endpoint.
serial_number(string: <optional>)- Specifies the serial number of the certificate to revoke, in hyphen-separated or colon-separated hexadecimal.certificate(string: <optional>)- Specifies the certificate to revoke, in PEM format. This certificate must have been signed by one of the issuers in this mount in order to be accepted for revocation.
Sample payload
Sample request
Sample response
Revoke certificate with private key
This endpoint revokes a certificate using its private key as proof that the request is authorized by an appropriate individual (Proof of Possession).
This is an alternative option to the standard method of revoking using Vault lease IDs or revocation via serial number. A successful revocation will rotate the CRL.
It is not possible to revoke issuers using this path.
Note: This operation is NOT privileged, as it validates revocation has a private key corresponding to a certificate signed by Vault. However, to avoid third parties performing a denial-of-service (DOS) against Vault, we've made this endpoint authenticated. Thus it is strongly encouraged to generally allow all access to this path via ACLs.
POST
/pki/revoke-with-key
Parameters
Note: either serial_number or certificate (but not both) must be specified on requests to this endpoint.
serial_number(string: <optional>)- Specifies the serial number of the certificate to revoke, in hyphen-separated or colon-separated hexadecimal.certificate(string: <optional>)- Specifies the certificate to revoke, in PEM format. This certificate must have been signed by one of the issuers in this mount in order to be accepted for revocation.private_key(string: <required>)- Specifies the private key (in PEM format) corresponding to the certificate issued by Vault that is attempted to be revoked. This endpoint must be called several times (with each unique certificate/serial number) if this private key is used in multiple certificates as Vault does not maintain such a mapping.
Sample payload
Sample request
Sample response
List revoked certificates
This endpoint returns a list of serial numbers that have been revoked on the local cluster.
LIST
/certs/revoked
Sample request
Sample response
List revocation requests
This endpoint returns a list of serial numbers that have been requested to be revoked on any cluster, along with information about the request's state and which cluster it originated on.
LIST
/certs/revocation-queue
Sample request
Sample response
List Cross-Cluster revocations
This endpoint returns a list of serial numbers that have been revoked on any cluster, along with the clusters that have a copy of that revoked certificate.
LIST
/certs/unified-revoked
Sample request
Sample response
Accessing authority information
All consumers of the PKI Secrets Engine mount point will have access to the following unauthenticated APIs, useful for reading information about the certificate authority in this mount point.
This includes information about CA certificates, their chains, and their signed CRLs, containing an encoded list of revoked certificates previously issued by this authority. Individual issued certificates can also be read, assuming their serial number is known. Finally, the list of issuing certificates is public information in this mount.
List issuers
This endpoint returns a list of issuers currently provisioned in this mount. The response includes both the issuer's identifier as well as the name chosen by the operators; either can be used to refer to the issuer later.
This endpoint is unauthenticated.
LIST
/pki/issuers
Sample request
Sample response
Read issuer certificate
This endpoint retrieves the specified issuer's certificate.
Note that the response differs between the older /pki/cert/ca path and the newer /pki/issuer/:issuer_ref/json path; the latter includes the full ca_chain of the issuer, removing the need for a separate endpoint.
These are unauthenticated endpoints.
Note: this endpoint accepts the If-Modified-Since header, to respond with 304 Not Modified when the requested resource has not changed. This header needs to be allowed on the PKI mount by tuning the passthrough_request_headers option. In order for clients to know the last modified time, the response header Last-Modified needs to be added to the mount tunable allowed_response_headers.
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/cert/ca and /pki/ca(/pem)? paths and takes the implicit value default.
Sample request
Sample response
Read default issuer certificate chain
This endpoint retrieves the default issuer's CA certificate chain, including the default issuer.
To read other issuers' chains, use the /pki/issuer/:issuer_ref/json endpoint instead.
These are unauthenticated endpoints.
GET
/pki/cert/ca_chain
default
JSON
Note: As of Vault 1.11.0, these endpoints now return the full chain (including the default issuer's certificate and all parent issuers known to Vault) in these responses.
Sample request
Sample response
Read issuer CRL
This endpoint retrieves the specified issuer's CRL.
Note that the response differs between the older /pki/cert/crl path and the newer /pki/issuer/:issuer_ref/crl path; the latter correctly places the PEM-encoded CRL in the crl field whereas the former incorrectly places it in the certificate field.
Endpoints with type complete are full CRLs containing all revoked certificates (as of the time of generation. Endpoints with type delta contain incremental CRLs on top of the last complete CRL, with any new certificates that have been revoked. See the revocation configuration section for more information about these options. The delta CRL clears when the next complete CRL is rebuilt. Consumers of delta CRLs will need to update their client to support fetching the corresponding full CRL when it has been regenerated; otherwise, some serial numbers may not appear in the local copy of the full CRL if the remote complete and delta CRLs has been regenerated.
Endpoints with source local only include cluster-local revocations. When the unified_crl parameters is enabled in the CRL configuration, endpoints with source unified will have revocations from all clusters. Generally use of the unified source is more consistent with expectations of external apps, but see the PKI Considerations page for a discussion on cluster size and unified CRLs/OCSP.
EnterpriseEnterprise
Unified CRLs require a Vault Enterprise license or HCP Plus cluster.
These are unauthenticated endpoints.
Note: As of Vault 1.11.0, these endpoints now serve a version 2 CRL response.
Note: this endpoint accepts the If-Modified-Since header, to respond with 304 Not Modified when the requested resource has not changed. This header needs to be allowed on the PKI mount by tuning the passthrough_request_headers option. In order for clients to know the last modified time, the response header Last-Modified needs to be added to the mount tunable allowed_response_headers.
GET
/pki/cert/crl
default
JSON
Complete
Local
GET
/pki/cert/delta-crl
default
JSON
Delta
Local
GET
/pki/issuer/:issuer_ref/crl
Selected
JSON
Complete
Local
GET
/pki/issuer/:issuer_ref/crl/delta
Selected
JSON
Delta
Local
GET
/pki/cert/unified-crl
default
JSON
Complete
Unified
GET
/pki/cert/unified-delta-crl
default
JSON
Delta
Unified
GET
/pki/issuer/:issuer_ref/unified-crl
Selected
JSON
Complete
Unified
GET
/pki/issuer/:issuer_ref/unified-crl/delta
Selected
JSON
Delta
Unified
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Note: This parameter is not present on the /pki/cert/crl and /pki/crl(/pem)? paths and takes the implicit value default.
Sample request
Sample response
OCSP request
This endpoint retrieves an OCSP response (revocation status) for a given serial number. The request/response formats are based on RFC 6960
Endpoints with source local only include cluster-local revocations. When the unified_crl parameters is enabled in the CRL configuration, endpoints with source unified will have revocations from all clusters. Generally use of the unified source is more consistent with expectations of external apps, but see the PKI Considerations page for a discussion on cluster size and unified CRLs/OCSP.
EnterpriseEnterprise
Unified OCSP requires a Vault Enterprise license or HCP Plus cluster.
At this time there are certain limitations of the OCSP implementation at this path:
Only a single serial number within the request will appear in the response,
None of the extensions defined in the RFC are supported for requests or responses,
Ed25519 backed CA's are not supported for OCSP requests,
Note that this API will not work with the Vault client as both request and responses are DER encoded, and
Note that KMS based issuers which require PSS support are not supported either (such as PKCS#11 HSMs or GCP in certain scenarios).
These are unauthenticated endpoints.
Parameters
None
Sample request
List certificates
This endpoint returns a list of the current certificates by serial number only. The response does not include the special serial numbers (ca, ca_chain, and crl) that can be used with /pki/cert/:serial.
This includes only certificates issued by this mount with no_store=false. While root generation does create entries here, importing certificates (including both roots and intermediates) will not cause the imported certificate's serial number to appear in this list.
Note: The endpoint to list all certificates is authenticated. This is to prevent automated enumeration of issued certificates for internal services; however, this information should generally be considered non-sensitive and the certificates themselves are exposed without authentication (provided their serial number is known). Many Public CAs participate in the Certificate Transparency initiative, where all issued certificates are publicly disclosed in the interest of third-party verification of CA integrity.
LIST
/pki/certs
Sample request
Sample response
Read certificate
This endpoint retrieves the certificate specified by its serial number, including issued certificates.
Note: With the exception of the special values (ca, crl, and ca_chain), /pki/cert/:serial will return different results on different clusters. This is because stored certificates are not replicated across different Performance Replication clusters.
These are unauthenticated endpoints.
Parameters
serial(string: <required>)- Specifies the serial of the key to read. This is part of the request URL. Valid values forserialare:<serial>for the certificate with the given serial number, in hyphen-separated or colon-separated hexadecimal.cafor the default issuer's CA certificatecrlfor the default issuer's CRLca_chainfor the default issuer's CA trust chain.
Note: As of Vault 1.11.0, these endpoints return the full chain (including this certificate and all parent issuers known to Vault) in the ca_chain response, for both the certificate and newer ca_chain fields. The root certificate is no longer elided.
Sample request
Sample response
Managing keys and issuers
The following endpoints are highly privileged and allow operators to generate or import new issuer certificates and keys, remove existing keys and issuers, or read internal information about keys and issuers.
List issuers
Refer to the earlier section for more information about listing issuers.
List keys
This endpoint returns a list of keys currently provisioned in this mount. The response includes both the key's identifier as well as the name chosen by the operators; either can be used to refer to the key later.
This endpoint is authenticated.
LIST
/pki/keys
Sample request
Sample response
Generate key
This endpoint generates a new private key for use in the PKI mount. This key can be used with either the root or intermediate endpoints, using the type=existing variant.
If the path ends with exported, the private key will be returned in the response; if it is internal the private key will not be returned and cannot be retrieved later; if it is kms, a managed keys will be used.
POST
/pki/keys/generate/:type
Parameters
type(string: <required>)- Specifies the type of the key to create. Ifexported, the private key will be returned in the response; ifinternalthe private key will not be returned and cannot be retrieved later;kmsis also supported: see below for more details about managed keys. This parameter is part of the request URL.key_name(string: "")- When a new key is created with this request, optionally specifies the name for this. The global refdefaultmay not be used as a name.key_type(string: "rsa")- Specifies the desired key type; must bersa,ed25519orec.
Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.
key_bits(int: 0)- Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); withkey_type=rsa, allowed values are: 2048 (default), 3072, or 4096; withkey_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored withkey_type=ed25519.
Managed keys parameters
See Managed Keys for additional details on this feature, if type was set to kms. One of the following parameters must be set
managed_key_name(string: "")- The managed key's configured name.managed_key_id(string: "")- The managed key's UUID.
Sample payload
Sample request
Sample response
Generate root
This endpoint generates a new self-signed CA certificate and private key. If the path ends with exported, the private key will be returned in the response; if it is internal the private key will not be returned and cannot be retrieved later; if it is existing, the key specified by key_ref will be reused for this root; if it is kms, a managed keys will be used.
This generated root will sign its own CRL. Authority Access distribution points use the values set via config/urls.
Note: As of Vault 1.11.0, the PKI Secrets Engine now supports multiple issuers under a single mount. Use the management operations in this section to list and modify issuers within this mount. No issuers will be overridden by calling this operation. Deleting individual keys and issuers should be preferred to calling DELETE /pki/root, which deletes everything.
POST
/pki/root/generate/:type
POST
/pki/issuers/generate/root/:type
POST
/pki/root/rotate/:type
Parameters
type(string: <required>)- Specifies the type of the root to create. Ifexported, the private key will be returned in the response; ifinternalthe private key will not be returned and cannot be retrieved later; ifexisting, we use the value of thekey_refparameter to find existing key material to create the CSR;kmsis also supported: see below for more details about managed keys. This parameter is part of the request URL.issuer_name(string: "")- Provides a name to the specified issuer. The name must be unique across all issuers and not be the reserved valuedefault. When no value is supplied and the path is/pki/root/rotate/:type, the default value of"next"will be used.key_name(string: "")- When a new key is created with this request, optionally specifies the name for this. The global refdefaultmay not be used as a name.key_ref(string: "default")- Specifies the key (eitherdefault, by name, or by identifier) to use for generating this request. Only suitable fortype=existingrequests.common_name(string: <required>)- Specifies the requested CN for the certificate. If more than onecommon_nameis desired, specify the alternative names in thealt_nameslist.alt_names(string: "")- Specifies the requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will be parsed into their respective fields.ip_sans(string: "")- Specifies the requested IP Subject Alternative Names, in a comma-delimited list.uri_sans(string: "")- Specifies the requested URI Subject Alternative Names, in a comma-delimited list.other_sans(string: "")- Specifies custom OID/UTF8-string SANs. These must match values specified on the role inallowed_other_sans(see role creation for allowed_other_sans globbing rules). The format is the same as OpenSSL:<oid>;<type>:<value>where the only current valid type isUTF8. This can be a comma-delimited list or a JSON string slice.ttl(string: "")- Specifies the requested Time To Live (after which the certificate will be expired). This cannot be larger than the engine's max (or, if not set, the system max). Seenot_afteras an alternative for setting an absolute end date (rather than a relative one).format(string: "pem")- Specifies the format for returned data. Can bepem,der, orpem_bundle. Ifder, the output is base64 encoded. Ifpem_bundle, thecertificatefield will contain the private key (if exported) and certificate, concatenated; if the issuing CA is not a Vault-derived self-signed root, this will be included as well.private_key_format(string: "der")- Specifies the format for marshaling the private key within the private_key response field. Defaults toderwhich will return either base64-encoded DER or PEM-encoded DER, depending on the value offormat. The other option ispkcs8which will return the key marshalled as PEM-encoded PKCS8.
Note that this does not apply to the private key within the certificate field if format=pem_bundle parameter is specified.
key_type(string: "rsa")- Specifies the desired key type; must bersa,ed25519orec.
Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.
key_bits(int: 0)- Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); withkey_type=rsa, allowed values are: 2048 (default), 3072, or 4096; withkey_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored withkey_type=ed25519.max_path_length(int: -1)- Specifies the maximum path length to encode in the generated certificate.-1means no limit. Unless the signing certificate has a maximum path length set, in which case the path length is set to one less than that of the signing certificate. A limit of0means a literal path length of zero.exclude_cn_from_sans(bool: false)- If true, the givencommon_namewill not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some human-readable identifier.permitted_dns_domains(string: "")- A comma separated string (or, string array) containing DNS domains for which certificates are allowed to be issued or signed by this CA certificate. Note that subdomains are allowed, as per RFC 5280 Section 4.2.1.10 - Name Constraints.ou(string: "")- Specifies the OU (OrganizationalUnit) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.organization(string: "")- Specifies the O (Organization) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.country(string: "")- Specifies the C (Country) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.locality(string: "")- Specifies the L (Locality) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.province(string: "")- Specifies the ST (Province) values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.street_address(string: "")- Specifies the Street Address values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.postal_code(string: "")- Specifies the Postal Code values in the subject field of the resulting certificate. This is a comma-separated string or JSON array.serial_number(string: "")- - Specifies the default Subject's named Serial Number value, if any. If you want more than one, specify alternative names in thealt_namesmap using OID 2.5.4.5. Note that this has no impact on the Certificate's serial number field, which Vault randomly generates.not_before_duration(duration: "30s")- Specifies the duration by which to backdate the NotBefore property. This value has no impact in the validity period of the requested certificate, specified in thettlfield. Uses duration format strings.not_after(string)- Set the Not After field of the certificate with specified date value. The value format should be given in UTC formatYYYY-MM-ddTHH:MM:SSZ. Supports the Y10K end date for IEEE 802.1AR-2018 standard devices,9999-12-31T23:59:59Z.Note: Keys of type
rsacurrently only support PKCS#1 v1.5 signatures.
Managed keys parameters
See Managed Keys for additional details on this feature, if type was set to kms. One of the following parameters must be set
managed_key_name(string: "")- The managed key's configured name.managed_key_id(string: "")- The managed key's UUID.
Sample payload
Sample request
Sample response
Generate intermediate CSR
This endpoint returns a new CSR for signing, optionally generating a new private key. If using Vault as a root (and, like many other CAs), the various parameters on the final signed certificate are set at signing time and may or may not honor the parameters set here (and transmitted in the returned CSR).
Note that this API supports Managed Keys; additional details are available below in a dedicated section.
The parameters below are mostly meant as a helper function; not all possible parameters that can be set in a CSR are supported in this request.
No new issuer is yet created by this call; note that a new key may be generated depending on the type request parameter.
Note: In order to complete the intermediate generation, the CSR must be signed and the resulting certificate imported. This may involve working with external systems (such as an external or offline root CA) to transmit the CSR and complete the signing before the signed intermediate certificate is imported into this mount.
Method
Path
Private key source (type)
POST
/pki/intermediate/generate/:type
specified per request
POST
/pki/issuers/generate/intermediate/:type
specified per request
POST
/pki/intermediate/cross-sign
existing
Parameters
type(string: <required>)- Specifies the type of the intermediate to create. Ifexported, the private key will be returned in the response; ifinternalthe private key will not be returned and cannot be retrieved later; ifexisting, we expect thekey_refparameter to use existing key material to create the CSR;kmsis also supported: see below for more details. This parameter is part of the request URL.common_name(string: <required>)- Specifies the requested CN for the certificate. If more than onecommon_nameis desired, specify the alternative names in thealt_nameslist.alt_names(string: "")- Specifies the requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will be parsed into their respective fields.ip_sans(string: "")- Specifies the requested IP Subject Alternative Names, in a comma-delimited list.uri_sans(string: "")- Specifies the requested URI Subject Alternative Names, in a comma-delimited list.other_sans(string: "")- Specifies custom OID/UTF8-string SANs. These must match values specified on the role inallowed_other_sans(see role creation for allowed_other_sans globbing rules). The format is the same as OpenSSL:<oid>;<type>:<value>where the only current valid type isUTF8. This can be a comma-delimited list or a JSON string slice.format(string: "pem")- Specifies the format for returned data. This can bepem,der, orpem_bundle; defaults topem. Ifder, the output is base64 encoded. Ifpem_bundle, thecsrfield will contain the private key (if exported) and CSR, concatenated.private_key_format(string: "der")- Specifies the format for marshaling the private key within the private_key response field. Defaults toderwhich will return either base64-encoded DER or PEM-encoded DER, depending on the value offormat. The other option ispkcs8which will return the key marshalled as PEM-encoded PKCS8.
Note that this does not apply to the private key within the certificate field if format=pem_bundle parameter is specified.
key_type(string: "rsa")- Specifies the desired key type; must bersa,ed25519orec. Not suitable fortype=existingrequests.
Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.
Note: Keys of type rsa currently only support PKCS#1 v1.5 signatures. This includes any managed keys.
key_bits(int: 0)- Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); withkey_type=rsa, allowed values are: 2048 (default), 3072, or 4096; withkey_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored withkey_type=ed25519. Not suitable fortype=existingrequests.key_name(string: "")- When a new key is created with this request, optionally specifies the name for this. The global refdefaultmay not be used as a name.key_ref(string: "default")- Specifies the key (eitherdefault, by name, or by identifier) to use for generating this request. Only suitable fortype=existingrequests.signature_bits(int: 0)- Specifies the number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
Note: ECDSA and Ed25519 issuers do not follow configuration of the signature_bits value; only RSA issuers will change signature types based on this parameter.
exclude_cn_from_sans(bool: false)- If true, the givencommon_namewill not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some human-readable identifier.ou(string: "")- Specifies the OU (OrganizationalUnit) values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.organization(string: "")- Specifies the O (Organization) values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.country(string: "")- Specifies the C (Country) values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.locality(string: "")- Specifies the L (Locality) values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.province(string: "")- Specifies the ST (Province) values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.street_address(string: "")- Specifies the Street Address values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.postal_code(string: "")- Specifies the Postal Code values in the subject field of the resulting CSR. This is a comma-separated string or JSON array.serial_number(string: "")- Specifies the requested Subject's named Serial Number value, if any. If you want more than one, specify alternative names in thealt_namesmap using OID 2.5.4.5. Note that this has no impact on the Certificate's serial number field, which Vault randomly generates.add_basic_constraints(bool: false)- Whether to add a Basic Constraints extension with CA: true. Only needed as a workaround in some compatibility scenarios with Active Directory Certificate Services.
Managed keys parameters
See Managed Keys for additional details on this feature, if type was set to kms. One of the following parameters must be set
managed_key_name(string: "")- The managed key's configured name.managed_key_id(string: "")- The managed key's UUID.
Sample payload
Sample request
Import CA certificates and keys
This endpoint allows submitting (importing) the CA information for the backend via a PEM file containing the CA certificate and any private keys, concatenated together, in any order.
Each certificate will be validated to ensure it is a valid CA (has an asserted isCA basic constraint); non-CA certs will err. Any provided CRLs will be ignored. Each unique certificate and private key will be imported as its own issuer or key entry; duplicates (including with existing keys) will be ignored.
The response will indicate what issuers and keys were created as part of this request (in the imported_issuers and imported_keys), along with a mapping field, indicating which keys belong to which issuers (including from already imported entries present in the same bundle). In Vault 1.14.0, the response also contains an existing_issuers and existing_keys fields, which specifies the issuer and key IDs of any entries in the bundle that already existed within this mount.
POST
/pki/config/ca
yes
pem_bundle
POST
/pki/issuers/import/bundle
yes
pem_bundle
POST
/pki/issuers/import/cert
no
pem_bundle
POST
/pki/intermediate/set-signed
no
certificate
Note: endpoints which allow importing private keys should be considered highly privileged and restricted appropriately. Endpoints which allow importing issuers should also be restricted, but note that issuers without keys are unable to issue certificates or CRLs.
Note: Vault will deduplicate differently-encoded but same-valued keys and issuers. This means the returned certificate may differ in encoding from the one provided on subsequent re-imports of the same issuer or key.
Note: This import may fail due to CRL rebuilding issues or other potential issues; this may impact long-term use of these issuers, but some issuers or keys may still be imported as a result of this process.
Warning: See the note regarding Subject naming on externally created CA certificates and shortcomings with CRL building.
Parameters
pem_bundle(string: <required>)- Specifies the unencrypted private key and certificate, concatenated in PEM format.
Note: this parameter is on the /pki/config/ca and /pki/issuers/import/* paths; it is not on the /pki/intermediate/set-signed path.
certificate(string: <required>)- Specifies the certificates to import, concatenated in PEM format.
Note: this parameter is only on the /pki/intermediate/set-signed path.
Sample request
Note that if you provide the data through the HTTP API, it must be JSON-formatted, with newlines replaced with , like so:
Sample response
Read issuer
This endpoint allows an operator to fetch a single issuer certificate and its chain, including internal information not exposed on the unauthenticated /pki/issuer/:issuer_ref/json endpoint. This includes information about the name, the key material, if an explicitly constructed chain has been set, what the behavior is for signing longer TTL'd certificates, and what usage modes are set on this issuer.
GET
/pki/issuer/:issuer_ref
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.
Sample request
Sample response
Update issuer
This endpoint allows an operator to manage a single issuer, updating various properties about it, including its name, an explicitly constructed chain, what the behavior is for signing longer TTL'd certificates, and what usage modes are set on this issuer.
Note that it is not possible to change the certificate of this issuer; to do so, import a new issuer and a new issuer_id will be assigned.
POST
/pki/issuer/:issuer_ref
PATCH
/pki/issuer/:issuer_ref
Note POSTing to this endpoint causes Vault to overwrite the previous contents of the issuer, using the provided request data (and any defaults for elided parameters). It does not update only the provided fields.
Since Vault 1.11.0, Vault supports the PATCH operation to this endpoint, using the JSON patch format supported by KVv2, allowing update of specific fields. Note that vault write uses POST.
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.issuer_name(string: "")- Provides a name to the specified issuer. The name must be unique across all issuers and not be the reserved valuedefault.leaf_not_after_behavior(string: "err")- Behavior of a leaf'sNotAfterfield during issuance. Valid options are:err, to error if the computedNotAfterexceeds that of this issuer;truncateto silently truncate the requestedNotAftervalue to that of this issuer; orpermitto allow this issuance to succeed with aNotAftervalue exceeding that of this issuer.
Note: Not all values result in leaf certificates that can be validated through the entire validity period. It is suggested to use truncate for intermediate CAs and permit only for root CAs. This is because (root) certificates in browsers' trust stores typically aren't checked for validity, whereas intermediate CA certificates sent in TLS connections are checked for validity at the time of use. This means that a leaf certificate permitted to be issued for longer than the intermediate likely won't continue to validate after the intermediate has expired.
manual_chain([]string: nil)- Chain of issuer references to build this issuer's computed CAChain field from, when non-empty.
Note: the manual_chain field is an advanced field useful when automatic chain building isn't desired. The first element must be the present issuer's reference. Subsequent references should validate previous entries, terminating with a root certificate. Ideally a single linear chain would come first (from this issuer to a single root certificate) before any parallel, alternate chains appear.
This field is especially useful for cross-signed intermediates within Vault. Because each cross-signed intermediate will only know of the one root, but issuance should serve both, update the issuers' entries with the desired manual_chain value.
The CA Chain returned by a GET to the issuer configuration is the same chain presented during signing and (if this issuer is the default) on the /ca_chain path. Setting manual_chain thus allows controlling the presented chain as desired.
usage([]string: read-only,issuing-certificates,crl-signing,ocsp-signing)- Allowed usages for this issuer. Valid options are:read-only, to allow this issuer to be read; implict; always allowed;issuing-certificates, to allow this issuer to be used for issuing other certificates; orcrl-signing, to allow this issuer to be used for signing CRLs. This is separate from the CRLSign KeyUsage on the x509 certificate, but this usage cannot be set unless that KeyUsage is allowed on the x509 certificate.ocsp-signing, to allow this issuer to be used for signing OCSP responses
Note: The usage field allows for a soft-delete capability on the issuer, or to prevent use of the issuer prior to it being enabled. For example, as issuance is rotated to a new issuer, the old issuer could be marked usage=read-only,crl-signing,ocsp-signing, allowing existing certificates to be revoked (and the CRL updated), but preventing new certificate issuance. After all certificates issued under this certificate have expired, this certificate could be marked usage=read-only, freezing the CRL. Finally, after a grace period, the issuer could be deleted.
revocation_signature_algorithm(string: "")- Which signature algorithm to use when building CRLs. See Go'sx509.SignatureAlgorithmconstant for possible values. This flag allows control over hash function and signature scheme (PKCS#1v1.5 vs PSS). The default (empty string) value is for Go to select the signature algorithm automatically, which may not always work.
Note: This can fail if the underlying key does not support the requested signature algorithm; this may not always be known at modification time. This most commonly needs to be modified when using PKCS#11 managed keys with the CKM_RSA_PKCS_PSS mechanism type.
issuing_certificates(array<string>: nil)- Specifies the URL values for the Issuing Certificate field. This can be an array or a comma-separated string list. See also RFC 5280 Section 4.2.2.1 for information about the Authority Information Access field.crl_distribution_points(array<string>: nil)- Specifies the URL values for the CRL Distribution Points field. This can be an array or a comma-separated string list. See also RFC 5280 Section 4.2.1.13 for information about the CRL Distribution Points field.
Note: When multiple Performance Replication clusters are enabled, each cluster will have its own CRL. Additionally, when multiple issuers are in use under a single mount, each issuer will also have its own CRL distribution point. These separate CRLs should either be aggregated into a single CRL (externally; as Vault does not support this functionality) or multiple crl_distribution_points should be specified here, pointing to each cluster and issuer.
ocsp_servers(array<string>: nil)- Specifies the URL values for the OCSP Servers field. This can be an array or a comma-separated string list. See also RFC 5280 Section 4.2.2.1 for information about the Authority Information Access field.enable_aia_url_templating(bool: false)- Specifies that the above AIA URL values (issuing_certificates,crl_distribution_points, andocsp_servers) should be templated. This replaces the literal value{{issuer_id}}with the ID of the issuer doing the issuance, the literal value{{cluster_path}}with the value ofpathfrom the cluster-local configuration endpoint/config/cluster, and the literal value{{cluster_aia_path}}with the value ofaia_pathfrom the cluster-local configuration endpoint/config/cluster.
Note: If no cluster-local address is present and templating is used, issuance will fail.
Sample payload
Sample request
Sample response
Revoke issuer
This endpoint allows an operator to revoke an issuer certificate, marking it unable to issue new certificates and adding it to other issuers' CRLs, if they have signed this issuer's certificate. This will cause all CRLs to be rebuilt.
This is mostly provided for book-keeping and as a soft-delete feature, to ensure this issuer is not accidentally reused in the future.
Warning: This operation cannot be undone!
Note: This operation does not have any impact on other clusters or mounts and may not have any impact on whether clients consider these issuers revoked. Revoked issuers will not appear on their own CRLs. Revoked issuers may not appear on other CRLs if a suitable parent is not present in the same mount point. Revoked issuers will still need to be revoked in any other mounts they appear in, both as issuers, in the event of issuer reuse, and as issued certificates, in the event of an external parent mount.
POST
/pki/issuer/:issuer_ref/revoke
Parameters
No parameters.
Sample request
Sample response
Delete issuer
This endpoint deletes the specified issuer. A warning is emitted and the default is cleared if this issuer is the default issuer.
Note: If an issuer is incorrectly deleted, but its key material remains, it is possible to re-import just the issuer certificate. The issuer_id will change, but the name can be re-assigned to the new issuer.
DELETE
/pki/issuer/:issuer_ref
Sample request
Import key
This endpoint allows an operator to import a single pem encoded rsa, ec, or ed25519 key.
Note: This API does not protect against importing keys using insecure combinations of algorithm and key length.
POST
/pki/keys/import
Parameters
pem_bundle(string: <required>)- Specifies the unencrypted private key in PEM format.key_name(string: "")- Provides a name to the specified key. The name must be unique across all keys and not be the reserved valuedefault.
Sample payload
Sample request
Sample response
Read key
This endpoint allows an operator to fetch information about an existing key.
Note: Vault does not allow reading the value of the private key after it has been created.
GET
/pki/key/:key_ref
Parameters
key_ref(string: <required>)- Reference to an existing key, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default key, or the name assigned to a key. This parameter is part of the request URL.
Sample request
Sample response
Update key
This endpoint allows an operator to manage a single key. Currently, the only parameter that is configurable is the key's name.
Note that it is not possible to change the private key of this key; to do so, import a new key and a new key_id will be assigned.
POST
/pki/key/:key_ref
Note POSTing to this endpoint causes Vault to overwrite the previous contents of the key, using the provided request data (and any defaults for elided parameters). It does not update only the provided fields.
Parameters
key_ref(string: <required>)- Reference to an existing key, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default key, or the name assigned to a key. This parameter is part of the request URL.key_name(string: "")- Provides a name to the specified key. The name must be unique across all keys and not be the reserved valuedefault.
Sample payload
Sample request
Sample response
Delete key
This endpoint deletes the specified key. A warning is emitted and the default is cleared if this key is the default key.
Note: Because Vault does not allow exporting the private key after it is initially generated, deletion of keys is a sensitive operation. Additionally, one key may be used by more than one issuer. As a result, Vault prohibits deletion of keys until all issuers using this key have also been deleted. If these issuers are still necessary for chain building, re-import them without the corresponding keys after the key has been deleted or use the soft-delete feature of issuers.
DELETE
/pki/key/:key_ref
Sample request
Delete all issuers and keys
This endpoint deletes all issuers and keys within the mount. It is highly recommended to use the individual delete operations instead. This mount will be unusable until new issuers and keys are provisioned.
This endpoint requires sudo/root privileges.
DELETE
/pki/root
Sample request
Managing authority information
The following privileged endpoints allow the operator to control information about the core contents of certificates and to perform privileged operations like rotating the CRLs or performing tidy operations.
List roles
Refer to the earlier section for more information about listing roles.
Create/Update role
This endpoint creates or updates the role definition. Note that the allowed_domains, allow_subdomains, allow_glob_domains, and allow_any_name attributes are additive; between them nearly and across multiple roles nearly any issuing policy can be accommodated. server_flag, client_flag, and code_signing_flag are additive as well. If a client requests a certificate that is not allowed by the CN policy in the role, the request is denied.
POST
/pki/roles/:name
PATCH
/pki/roles/:name
Note POSTing to this endpoint when the role already exists causes Vault to overwrite the contents of the role, using the provided request data (and any defaults for elided parameters). It does not update only the provided fields.
Since Vault 1.11.0, Vault supports the PATCH operation to this endpoint, using the JSON patch format supported by KVv2, allowing update of specific fields. Note that vault write uses POST.
Parameters
name(string: <required>)- Specifies the name of the role to create. This is part of the request URL.issuer_ref:(string: "default")- Specifies the default issuer of this request. May be the valuedefault, a name, or an issuer ID. Use ACLs to prevent access to the/pki/issuer/:issuer_ref/{issue,sign}/:namepaths to prevent users overriding the role'sissuer_refvalue.
Note: This parameter is stored as-is; if the reference is to a name, it is not resolve to an identifier. Deletion of issuers (or updating their names) may result in issuance failing or using an unexpected issuer.
Note: existing roles from previous Vault versions are migrated to use the issuer_ref=default.
ttl(string: "")- Specifies the Time To Live value to be used for the validity period of the requested certificate, provided as a string duration with time suffix. Hour is the largest suffix. The value specified is strictly used for future validity. If not set, uses the system default value or the value ofmax_ttl, whichever is shorter. Seenot_afteras an alternative for setting an absolute end date (rather than a relative one).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 system maximum lease TTL.allow_localhost(bool: true)- Specifies if clients can request certificates forlocalhostas one of the requested common names. This is useful for testing and to allow clients on a single host to talk securely.
Note: This strictly applies to localhost and localdomain when this option is enabled. Additionally, even if this option is disabled, if either name is included in allowed_domains, the match rules for that option could permit issuance of a certificate for localhost.
allowed_domains(list: [])- Specifies the domains this role is allowed to issue certificates for. This is used with theallow_bare_domains,allow_subdomains, andallow_glob_domainsoptions to determine the type of matching between these domains and the values of common name, DNS-typed SAN entries, and Email-typed SAN entries. Whenallow_any_nameis used, this attribute has no effect.
Note: The three options allow_bare_domains, allow_subdomains, and allow_glob_domains are each independent of each other. That is, at least one type of allowed matching must describe the relationship between the allowed_domains list and the names on the issued certificate. For example, given allowed_domain=foo.*.example.com and allow_subdomains=true and allow_glob_domains=true, a request for bar.foo.baz.example.com won't be permitted, even though it foo.baz.example.com matches the glob foo.*.example.com and bar is a subdomain of that.
allowed_domains_template(bool: false)- When set,allowed_domainsmay contain templates, as with ACL Path Templating. Non-templated domains are also still permitted.allow_bare_domains(bool: false)- Specifies if clients can request certificates matching the value of the actual domains themselves; e.g. if a configured domain set withallowed_domainsisexample.com, this allows clients to actually request a certificate containing the nameexample.comas one of the DNS values on the final certificate. In some scenarios, this can be considered a security risk. Note that when anallowed_domainfield contains a potential wildcard character (for example,allowed_domains=*.example.com) andallow_bare_domainsandallow_wildcard_certificatesare both enabled, issuance of a wildcard certificate for*.example.comwill be permitted.allow_subdomains(bool: false)- Specifies if clients can request certificates with CNs that are subdomains of the CNs allowed by the other role options. This includes wildcard subdomains. For example, anallowed_domainsvalue ofexample.comwith this option set to true will allowfoo.example.comandbar.example.comas well as*.example.com. To restrict issuance of wildcards by this option, seeallow_wildcard_certificatesbelow. This option is redundant when using theallow_any_nameoption.allow_glob_domains(bool: false)- Allows names specified inallowed_domainsto contain glob patterns (e.g.ftp*.example.com). Clients will be allowed to request certificates with names matching the glob patterns.
Note: These globs behave like shell-style globs and can match across multiple domain parts. For example, allowed_domains=*.example.com with allow_glob_domains enabled will match not only foo.example.com but also baz.bar.foo.example.com.
Warning: Glob patterns will match wildcard domains and permit their issuance unless otherwise restricted by allow_wildcard_certificates. For instance, with allowed_domains=*.*.example.com and both allow_glob_domains and allow_wildcard_certificates enabled, we will permit the issuance of a wildcard certificate for *.foo.example.com.
allow_wildcard_certificates(bool: true)- Allows the issuance of certificates with RFC 6125 wildcards in the CN field. When set tofalse, this prevents wildcards from being issued even if they would've been allowed by an option above. We support the following four wildcard types:*.example.com, a single wildcard as the entire left-most label,foo*.example.com, a single suffixed wildcard in the left-most label,*foo.example.com, a single prefixed wildcard in the left-most label, andf*o.example.com, a single interior wildcard in the left-most label.
allow_any_name(bool: false)- Specifies if clients can request any CN. Useful in some circumstances, but make sure you understand whether it is appropriate for your installation before enabling it. Note that bothenforce_hostnamesandallow_wildcard_certificatesare still checked, which may introduce limitations on issuance with this option.enforce_hostnames(bool: true)- Specifies if only valid host names are allowed for CNs, DNS SANs, and the host part of email addresses.allow_ip_sans(bool: true)- Specifies if clients can request IP Subject Alternative Names. No authorization checking is performed except to verify that the given values are valid IP addresses.allowed_uri_sans(string: "")- Defines allowed URI Subject Alternative Names. No authorization checking is performed except to verify that the given values are valid URIs. This can be a comma-delimited list or a JSON string slice. Values can contain glob patterns (e.g.spiffe://hostname/*).allowed_uri_sans_template(bool: false)- When set,allowed_uri_sansmay contain templates, as with ACL Path Templating. Non-templated domains are also still permitted.allowed_other_sans(string: "")- Defines allowed custom OID/UTF8-string SANs. This can be a comma-delimited list or a JSON string slice, where each element has the same format as OpenSSL:<oid>;<type>:<value>, but the only valid type isUTF8orUTF-8. Thevaluepart of an element may be a*to allow any value with that OID. Alternatively, specifying a single*will allow anyother_sansinput.allowed_serial_numbers(string: "")- If set, an array of allowed serial numbers to be requested during certificate issuance. These values support shell-style globbing. When empty, custom-specified serial numbers will be forbidden. It is strongly recommended to allow Vault to generate random serial numbers instead.server_flag(bool: true)- Specifies if certificates are flagged for server authentication use. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field.client_flag(bool: true)- Specifies if certificates are flagged for client authentication use. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field.code_signing_flag(bool: false)- Specifies if certificates are flagged for code signing use. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field.email_protection_flag(bool: false)- Specifies if certificates are flagged for email protection use. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field.key_type(string: "rsa")- Specifies the type of key to generate for generated private keys and the type of key expected for submitted CSRs. Currently,rsa,ec, anded25519are supported, or when signing existing CSRs,anycan be specified to allow keys of either type and with any bit size (subject to >=2048 bits for RSA keys or >= 224 for EC keys). Whenanyis used, this role cannot generate certificates and can only be used to sign CSRs.
Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: ed25519.
key_bits(int: 0)- Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); withkey_type=rsa, allowed values are: 2048 (default), 3072, or 4096; withkey_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored withkey_type=ed25519or in signing operations whenkey_type=any.signature_bits(int: 0)- Specifies the number of bits to use in the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, and 512 for SHA-2-512. Defaults to 0 to automatically detect based on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves).
Note: ECDSA and Ed25519 issuers do not follow configuration of the signature_bits value; only RSA issuers will change signature types based on this parameter.
use_pss(bool: false)- Specifies whether or not to use PSS signatures over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for ECDSA/Ed25519 issuers.key_usage(list: ["DigitalSignature", "KeyAgreement", "KeyEncipherment"])- Specifies the allowed key usage constraint on issued certificates. Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage - simply drop theKeyUsagepart of the value. Values are not case-sensitive. To specify no key usage constraints, set this to an empty list. See RFC 5280 Section 4.2.1.3 for more information about the Key Usage field.ext_key_usage(list: [])- Specifies the allowed extended key usage constraint on issued certificates. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage - simply drop theExtKeyUsagepart of the value. Values are not case-sensitive. To specify no key usage constraints, set this to an empty list. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field.ext_key_usage_oids(string: "")- A comma-separated string or list of extended key usage oids. Useful for adding EKUs not supported by the Go standard library.use_csr_common_name(bool: true)- When used with the CSR signing endpoint, the common name in the CSR will be used instead of taken from the JSON data. This does not include any requested SANs in the CSR; useuse_csr_sansfor that.use_csr_sans(bool: true)- When used with the CSR signing endpoint, the subject alternate names in the CSR will be used instead of taken from the JSON data. This does not include the common name in the CSR; useuse_csr_common_namefor that.ou(string: "")- Specifies the OU (OrganizationalUnit) values in the subject field of issued certificates. This is a comma-separated string or JSON array.organization(string: "")- Specifies the O (Organization) values in the subject field of issued certificates. This is a comma-separated string or JSON array.country(string: "")- Specifies the C (Country) values in the subject field of issued certificates. This is a comma-separated string or JSON array.locality(string: "")- Specifies the L (Locality) values in the subject field of issued certificates. This is a comma-separated string or JSON array.province(string: "")- Specifies the ST (Province) values in the subject field of issued certificates. This is a comma-separated string or JSON array.street_address(string: "")- Specifies the Street Address values in the subject field of issued certificates. This is a comma-separated string or JSON array.postal_code(string: "")- Specifies the Postal Code values in the subject field of issued certificates. This is a comma-separated string or JSON array.generate_lease(bool: false)- Specifies if certificates issued/signed against this role will have Vault leases attached to them. Certificates can be added to the CRL byvault revoke <lease_id>when certificates are associated with leases. It can also be done using thepki/revokeendpoint. However, when lease generation is disabled, invokingpki/revokewould be the only way to add the certificates to the CRL. When large number of certificates are generated with long lifetimes, it is recommended that lease generation be disabled, as large amount of leases adversely affect the startup time of Vault.no_store(bool: false)- If set, certificates issued/signed against this role will not be stored in the storage backend. This can improve performance when issuing large numbers of certificates. However, certificates issued in this way cannot be enumerated or revoked via serial number. Certificates may still be revoked via BYOC revocation. This option is recommend only for certificates that are non-sensitive, extremely short-lived, or have high volume/turn-over that would prohibit storage. This option implies a value offalseforgenerate_lease.require_cn(bool: true)- If set to false, makes thecommon_namefield optional while generating a certificate.policy_identifiers(list: [])- A comma-separated string or list of policy OIDs.basic_constraints_valid_for_non_ca(bool: false)- Mark Basic Constraints valid when issuing non-CA certificates.not_before_duration(duration: "30s")- Specifies the duration by which to backdate the NotBefore property. This value has no impact in the validity period of the requested certificate, specified in thettlfield.not_after(string)- Set the Not After field of the certificate with specified date value. The value format should be given in UTC formatYYYY-MM-ddTHH:MM:SSZ. Supports the Y10K end date for IEEE 802.1AR-2018 standard devices,9999-12-31T23:59:59Z.cn_validations(list: ["email", "hostname"])- Validations to run on the Common Name field of the certificate. Valid values include:email, to ensure the Common Name is an email address (contains an@sign),hostname, to ensure the Common Name is a hostname (otherwise).
Multiple values can be separated with a comma or specified as a list and use OR semantics (either email or hostname in the CN are allowed). When the special value "disabled" is used (must be specified alone), none of the usual validation is run (including but not limited to
allowed_domainsand basic correctness validation around email addresses and domain names). This allows non-standard CNs to be used verbatim from the request.allowed_user_ids(string: "")- Comma separated, globbing list of User ID Subject components to allow on requests. By default, no user IDs are allowed. Use the bare wildcard*value to allow any value. See also theuser_idsrequest parameter.
Sample payload
Sample request
Read role
Refer to the earlier section for more information about reading roles.
Delete role
This endpoint deletes the role definition. Deleting a role does not revoke certificates previously issued under this role.
DELETE
/pki/roles/:name
Parameters
name(string: <required>)- Specifies the name of the role to delete. This is part of the request URL.
Sample request
Read Certificate Issuance External Policy Service (CIEPS) configuration EnterpriseEnterprise
This endpoint reads the Certificate Issuance External Policy Service (CIEPS) engine EnterpriseEnterprise connection properties.
On top of the configuration parameters documented below, this endpoint returns the following parameters:
external_service_last_updated- An RFC 3339 timestamp indicating when the configuration was last modified.external_service_validated- Indicates whether a successful connection to the external policy engine has been made under this configuration.last_successful_request- Timestamp of the last successful request to the external policy engine.
Note that the last two parameters are node-specific and will be reset whenever the mount reloads (e.g., leadership election or seal/unseal).
GET
/pki/config/external-policy
Sample request
Sample Response
Set Certificate Issuance External Policy Service (CIEPS) configuration EnterpriseEnterprise
This endpoint allows enabling the Certificate Issuance External Policy Service (CIEPS) EnterpriseEnterprise engine and configuring connection properties.
POST
/pki/config/external-policy
Parameters
enabled(bool: false)- Enables or disables the external policy service. When disabled, issuance mechanisms underexternal-policypaths (e.g.,/pki/external-policy/sign/:policy) will not work.external_service_url(string: <required>)- URI to the external policy engine. Must use thehttps://scheme.timeout(string: "")- This is how long any particular API request should wait for a timeout at various layers of the stack. Defaults to15s.trusted_ca(string: "")- A PEM bundle of trusted CAs to verify the certificates presented by the external policy engine against. Optional; one oftrusted_caortrusted_leaf_certificate_bundlemust be specified.trusted_leaf_certificate_bundle(string: "")- A PEM bundle of pinned non-CA leaf certificates that must be presented by the external policy engine. Optional; one oftrusted_caortrusted_leaf_certificate_bundlemust be specified.vault_client_cert_bundle(string: "")- A PEM bundle of a private key and one or more certificates to present during authentication to the external policy service.entity_jmespath(string: "")- A JMESPath expression that will select and filter entity metadata to the service. By default no entity metadata beyond the entity id is sent, use "@" to send all informationgroup_jmespath(string: "")- A JMESPath expression that will select and filter entity group metadata to the service. By default no group entity metadata is sent, use "@" to send all information
Sample payload
Sample request
Read URLs
This endpoint fetches the URLs to be encoded in generated certificates. No URL configuration will be returned until the configuration is set.
GET
/pki/config/urls
Sample request
Sample response
Set URLs
This endpoint allows setting the issuing certificate endpoints, CRL distribution points, and OCSP server endpoints that will be encoded into issued certificates. You can update any of the values at any time without affecting the other existing values. To remove the values, simply use a blank string as the parameter.
POST
/pki/config/urls
Note: When using multiple issuers within the same mount, it is strongly suggested to use the per-issuer AIA information instead of the global AIA information. If any of the per-issuer AIA fields are set, the entire issuer's preferences will be used instead. Otherwise, these fields are used as a fallback. This can be achieved by using templated global AIA values, but setting the cluster-local address in configuration. When used, this value must be set on all performance replication clusters, otherwise issuance will fail!
Parameters
issuing_certificates(array<string>: nil)- Specifies the URL values for the Issuing Certificate field. This can be an array or a comma-separated string list. See also RFC 5280 Section 4.2.2.1 for information about the Authority Information Access field.crl_distribution_points(array<string>: nil)- Specifies the URL values for the CRL Distribution Points field. This can be an array or a comma-separated string list. See also RFC 5280 Section 4.2.1.13 for information about the CRL Distribution Points field.
Note: When multiple Performance Replication clusters are enabled, each cluster will have its own CRL. Additionally, when multiple issuers are in use under a single mount, each issuer will also have its own CRL distribution point. These separate CRLs should either be aggregated into a single CRL (externally; as Vault does not support this functionality) or multiple crl_distribution_points should be specified here, pointing to each cluster and issuer.
ocsp_servers(array<string>: nil)- Specifies the URL values for the OCSP Servers field. This can be an array or a comma-separated string list. See also RFC 5280 Section 4.2.2.1 for information about the Authority Information Access field.enable_templating(bool: false)- Specifies that the above AIA URL values (issuing_certificates,crl_distribution_points, andocsp_servers) should be templated. This replaces the literal value{{issuer_id}}with the ID of the issuer doing the issuance, the literal value{{cluster_path}}with the value ofpathfrom the cluster-local configuration endpoint/config/cluster, and the literal value{{cluster_aia_path}}with the value ofaia_pathfrom the cluster-local configuration endpoint/config/cluster.For example, the following values can be used globally to ensure all AIA URIs use the cluster-local, per-issuer canonical reference, but with the issuing CA certificate and CRL distribution points to potentially use an external, non-Vault CDN.
issuing_certificates={{cluster_aia_path}}/issuer/{{issuer_id}}/dercrl_distribution_points={{cluster_aia_path}}/issuer/{{issuer_id}}/crl/derocsp_servers={{cluster_aia_path}}/ocsp
Note: If no cluster-local address is present and templating is used, issuance will fail.
Sample payload
Sample request
Read issuers configuration
This endpoint allows getting the value of the default issuer.
GET
/pki/config/issuers
Sample request
Sample response
Set issuers configuration
This endpoint allows setting the value of the default issuer.
POST
/pki/config/issuers
POST
/pki/root/replace
Parameters
default(string: "")- Specifies the default issuer (by reference; either a name or an ID). When no value is specified and the path is/pki/root/replace, the default value of"next"will be used.default_follows_latest_issuer(bool: false)- Specifies whether a root creation or an issuer import operation updates the default issuer to the newly added issuer.While the new multi-issuer functionality of 1.11 was backwards compatible on a per-API basis, some applications relied explicitly on unsafe behavior across multiple APIs that we addressed. For instance, calling
/intermediate/generate/:typewould silently remove any (potentially in-use!) key material and generate new private keys. While our response to this endpoint is backwards compatible (returning a new key and safely preserving old keys), some applications implicitly relied on this behavior. This new option is meant to provide compatibility across API calls to these callers: the newly created issuer (once imported -- not on intermediate generation) will become the default and it will look (to anyone strictly using old APIs) that it is the only issuer in the mount. However, it is encouraged for applications to update to the newer, safer semantics associated with multi-issuer rotation.
Note: When an import creates more than one new issuer with key material known to this mount, no default update will occur.
Sample payload
Sample request
Sample response
Read keys configuration
This endpoint allows getting the value of the default key.
GET
/pki/config/keys
Sample request
Sample response
Set keys configuration
This endpoint allows setting the value of the default key.
POST
/pki/config/keys
Parameters
default(string: "")- Specifies the default key (by reference; either a name or an ID).
Sample payload
Sample request
Sample response
Read cluster configuration
This endpoint fetches the cluster-local configuration.
The cluster-local config has path, which sets the URL to this mount on a particular performance replication cluster. This is useful for populating {{cluster_path}} during AIA URL templating, but may be used for other values in the future.
It also has aia_path, which allows using a non-Vault, external responder, setting the {{cluster_aia_path}} value for AIA URL templating. This is useful for distributing CA and CRL information over an unsecured, non-TLS channel.
GET
/pki/config/cluster
Sample request
Sample response
Set cluster configuration
This endpoint sets cluster-local configuration.
The cluster-local config has path, which sets the URL to this mount on a particular performance replication cluster. This is useful for populating {{cluster_path}} during AIA URL templating, but may be used for other values in the future.
It also has aia_path, which allows using a non-Vault, external responder, setting the {{cluster_aia_path}} value for AIA URL templating. This is useful for distributing CA and CRL information over an unsecured, non-TLS channel.
POST
/pki/config/cluster
Parameters
path(string: "")- Specifies the path to this performance replication cluster's API mount path, including any namespaces as path components. For example,https://pr-a.vault.example.com/v1/ns1/pki-root.aia_path(string: "")- Specifies the path to this performance replication cluster's AIA distribution point; may refer to an external, non-Vault responder. This is for resolving AIA URLs and providing the{{cluster_aia_path}}template parameter and will not be used for other purposes. As such, unlikepathabove, this could safely be an insecure transit mechanism (like HTTP without TLS).
Sample payload
Sample request
Read CRL configuration
This endpoint allows getting the duration for which the generated CRL should be marked valid. No CRL configuration will be returned until the configuration is set, but the CRL will still default to enabled with 72h expiration.
GET
/pki/config/crl
Sample request
Sample response
Set revocation configuration
This endpoint allows setting the duration for which the generated CRL should be marked valid. If the CRL is disabled, it will return a signed but zero-length CRL for any request. If enabled, it will re-build the CRL.
If the ocsp_disable key is set to true, the OCSP responder will always respond with an Unauthorized OCSP response to any request.
Note: This parameter is global, across all clusters and issuers. Use the per-issuer usage field to disable CRL building for a specific issuer, while leaving the global CRL building enabled.
Note: Disabling the CRL does not affect whether revoked certificates are stored internally. Certificates that have been revoked when a role's certificate storage is enabled will continue to be marked and stored as revoked until tidy has been run with the desired safety buffer. Re-enabling CRL generation will then result in all such certificates becoming a part of the CRL.
Note: Enabling automatic rebuilding of CRLs disables immediate regeneration on revocation. This is in line with the behavior of other CAs which only rebuild CRLs periodically. We suggest manually hitting the rotate if a fresh CRL is necessary after a revocation. For the most part though, CRLs should not be relied upon for the latest certificate status information, and OCSP should be used instead.
Note: The periodic function which controls automatic rebuilding of CRLs and delta CRLs only executes once a minute; this prevents high system load but limits the granularity of the temporal options below.
Note: The unified_crl, unified_crl_on_existing_paths, and cross_cluster_revocation parameters are all Vault Enterprise only functionality. While they appear in the responses on Vault Community Edition, they cannot be enabled.
POST
/pki/config/crl
Parameters
expiry(string: "72h")- The amount of time the generated CRL should be valid.disable(bool: false)- Disables or enables CRL building.ocsp_disable(bool: false)- Disables or enables the OCSP responder in Vault.ocsp_expiry(string: "12h")- The amount of time an OCSP response can be cached for, (controls the NextUpdate field), useful for OCSP stapling refresh durations. Setting to 0 should effectively disable caching in third party systems.auto_rebuild(bool: false)- Enables or disables periodic rebuilding of the CRL upon expiry.auto_rebuild_grace_period(string: "12h")- Grace period before CRL expiry to attempt rebuild of CRL. Must be shorter than the CRL expiry period.enable_delta(bool: false)- Enables or disables building of delta CRLs with up-to-date revocation information, augmenting the last complete CRL. This option requiresauto_rebuildto also be enabled.delta_rebuild_interval(string: "15m")- Interval to check for new revocations on, to regenerate the delta CRL. Must be shorter than CRL expiry.cross_cluster_revocation(bool: false)-EnterpriseEnterprise Enables cross-cluster revocation request queues. When a serial not issued on this local cluster is presented to Vault via the [`/revoke` API](#revoke-certificate), it is replicated across clusters and the cluster which issued that certificate will revoke it if it is online.
Note: API calls to revoke a certificate with Bring Your Own Certificate (BYOC) will always trigger a local revocation of that certificate. No cross-cluster revocation request will be created. API calls to revoke a certificate with Proof of Possession (PoP) cannot be satisfied if the certificate is not available locally and will not result in a cross-cluster revocation request.
unified_crl(bool: false)-EnterpriseEnterprise Enables unified CRL and OCSP building. This synchronizes all revocations between clusters; a single, unified CRL will be built on the active node of the primary performance replication (PR) cluster. Any node in any PR cluster will be able to serve this unified CRL and respond to unified OCSP inquiries.
Note: This option ensures existing, non-expired revocations are consistently reported. If a certificate was issued and stored on one cluster, but revoked via BYOC on another, this option will inform the issuing cluster of the revocation.
unified_crl_on_existing_paths(bool: false)-EnterpriseEnterprise Enables serving the unified CRL and OCSP on the existing, previously cluster-local paths (e.g., `/pki/crl` will now contain the unified CRL when enabled). This allows transitioning AIA-based consumption of CRLs to a unified view without having to re-issue certificates or update scripts pulling a single CRL.
Sample payload
Sample request
Rotate CRLs
This endpoint forces a rotation of all issuers' CRLs. This can be used by administrators to cut the size of the CRL if it contains a number of certificates that have now expired, but has not been rotated due to no further certificates being revoked. If no certificates have been revoked, but the CRL has expired or is close to expiring, administrators must hit this endpoint to manually rotate the CRL. This rotates all CRLs on the present cluster, and must be called on every cluster.
Note: Mirroring the behavior of earlier Vault versions, we add certificates revoked by an unknown issuer to the default issuer's CRL. To fully purge old revoked, unexpired certificates, it is not sufficient to delete their issuer and is instead necessary to remove the mount completely.
Note: As of Vault 1.12, it is suggested to switch to enabling the CRL's auto_rebuild functionality to avoid having to manually hit the Rotate endpoint when the CRL expires. This ensures a valid CRL is always maintained, at the expense of potentially not being up-to-date. If a revocation occurs that must be immediately propagated, this endpoint can be used to regenerate the CRL, though distribution must still occur outside of Vault (either manually or via AIA where supported).
GET
/pki/crl/rotate
Sample request
Sample response
Rotate delta CRLs
This endpoint forces a rotation of all issuers' delta CRLs, when enabled. This can be used by administrators to force a rebuild of a delta CRL if high-profile revocations have occurred and there's a long high interval between delta rebuilds (delta_rebuild_interval).
See notes about rotating regular CRLs above as they apply here as well.
GET
/pki/crl/rotate-delta
Sample request
Sample response
Combine CRLs from the same issuer
This endpoint allows combining multiple different CRLs that have been signed by the same issuer into a single signed CRL. This is useful to generate a single authoritative CRL of revocations across distinct Vault clusters such as primary and performance replica clusters.
POST
/pki/issuer/:issuer_ref/resign-crls
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.crls(list of strings: <required>)- A list of PEM encoded CRLs that have been signed by the issuercrl_number(int: <required>)- The sequence number to be written within the CRL Number extension.delta_crl_base_number(int: -1)- Using a value of 0 or greater specifies the base CRL revision number to encode within a Delta CRL indicator extension, otherwise the extension will not be added; defaults to -1.format(string: pem)- The format of the combined CRL, can be "pem" or "der". If "der", the value will be base64 encoded; Defaults to "pem".next_update(string: 72h)- The amount of time the generated CRL should be valid; defaults to 72 hours.
Sample payload
Sample request
Sample response
Sign revocation list
This endpoint allows generating a CRL based on the provided parameter data from any external source and signed by the specified issuer. Values are taken verbatim from the parameters provided.
This is a potentially dangerous endpoint and only highly trusted users should have access.
POST
/pki/issuer/:issuer_ref/sign-revocation-list
Parameters
issuer_ref(string: <required>)- Reference to an existing issuer, either by Vault-generated identifier, the literal stringdefaultto refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.crl_number(int: <required>)- The sequence number to be written within the CRL Number extension.delta_crl_base_number(int: -1)- Using a value of 0 or greater specifies the base CRL revision number to encode within a Delta CRL indicator extension, otherwise the extension will not be added; defaults to -1.format(string: pem)- The format of the combined CRL, can be "pem" or "der". If "der", the value will be base64 encoded; Defaults to "pem".next_update(string: 72h)- The amount of time the generated CRL should be valid; defaults to 72 hours.revoked_certs(type: slice of maps)- Each element contains revocation information for a single serial number along with the revocation time and the serial's extensions if any. Each element can have the following key/valuesserial_number(type: string)- the serial number of the revoked certrevocation_time(type: string)- the revocation time, unix int format or RFC3339 encoding supportedextensions(type: slice of maps)- A slice of all extensions that should be added to the revoked certificate entry. Each ele,ent contains a map with the following entriesid(type: string)- an ASN1 object identifier in dot notationcritical(type: bool)- should the extension be marked criticalvalue(type: string)- base64 encoded bytes for extension value
extensions(type: slice of maps)- A slice of all extensions that should be added to the generated CRL each element containing a map with the following entries.id(type: string)- an ASN1 object identifier in dot notationcritical(type: bool)- should the extension be marked criticalvalue(type: string)- base64 encoded bytes for extension value
Note:: The following extension ids are not allowed to be provided and can be influenced by other parameters
2.5.29.20: CRL Number2.5.29.27: Delta CRL2.5.29.35: Authority Key Identifier
Sample payload
Sample request
Sample response
Tidy
This endpoint allows tidying up the storage backend and/or CRL by removing certificates that have expired and are past a certain buffer period beyond their expiration time.
POST
/pki/tidy
Note: it is encouraged to use the automatic tidy capabilities to ensure this gets run periodically.
Parameters
tidy_cert_store(bool: false)- Specifies whether to tidy up the certificate store.tidy_revoked_certs(bool: false)- Set to true to remove all invalid and expired certificates from storage. A revoked storage entry is considered invalid if the entry is empty, or the value within the entry is empty. If a certificate is removed due to expiry, the entry will also be removed from the CRL, and the CRL will be rotated.tidy_revoked_cert_issuer_associations(bool: false)- Set to true to associate revoked certificates with their corresponding issuers; this improves the performance of OCSP and CRL building, by shifting work to a tidy operation instead.
Note: With multiple issuers, a CA which issued a particular revoked certificate may be removed and re-added, resulting in a different issuer ID value. When building CRLs, these links are automatically updated for any missing or added issuers, but during OCSP this value is computed and then discarded, potentially causing a performance penalty on each request. During regular CA operations, it is not necessary to run this operation.
It is suggested to run this tidy when removing or importing new issuers and on the first upgrade to a post-1.11 Vault version, but otherwise not to run it during automatic tidy operations.
tidy_expired_issuers(bool: false)- Set to true to automatically remove expired issuers after theissuer_safety_bufferduration has elapsed. We log the issuer certificate on removal to allow recovery; no keys are removed during this process.
Note: The default issuer will not be removed even if it has expired and is past the issuer_safety_buffer specified.
tidy_move_legacy_ca_bundle(bool: false)- Set to true to backup any legacy CA/issuers bundle (from Vault versions earlier than 1.11) toconfig/ca_bundle.bak. This can be restored withsys/rawback toconfig/ca_bundleif necessary, but won't impact mount startup (as mounts will attempt to read the latter and do a migration of CA issuers if present). Migration will only occur afterissuer_safety_bufferhas passed since the last successful migration.tidy_revocation_queue(bool: false)- Set to true to remove stale revocation request entries that haven't been confirmed by any active node of a performance replication (PR) cluster. Only runs on the active node of the primary cluster.
Note: this tidy is only applicable on Vault Enterprise.
tidy_cross_cluster_revoked_certs(bool: false)- Set to true to remove expired, cross-cluster revocation entries. This is the cross-cluster equivalent oftidy_revoked_certs. Only runs on the active node of the primary cluster.
Note: this tidy is only applicable on Vault Enterprise.
safety_buffer(string: "")- Specifies a duration using duration format strings used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep certificates from being removed from the CRL that, due to clock skew, might still be considered valid on other hosts. For a certificate to be expunged, the time must be after the expiration time of the certificate (according to the local clock) plus the duration ofsafety_buffer. Defaults to72h.issuer_safety_buffer(string: "")- Specifies a duration that issuers should be kept for, past theirNotAftervalidity period. Defaults to 365 days as hours (8760h).pause_duration(string: "0s")- Specifies the duration to pause between tidying individual certificates. This releases the revocation lock and allows other operations to continue while tidy is paused. This allows an operator to control tidy's resource utilization within a timespan: the LIST operation will remain in memory, but the space between reading, parsing, and updates on-disk cert entries will be increased, decreasing resource utilization.Does not affect
tidy_expired_issuers.
Note: Using too long of a pause_duration can result in tidy operations not concluding during this lifetime! Using too short of a pause duration (but non-zero) can lead to lock contention. Use tidy's cancellation to stop a running operation after the sleep period is over.
revocation_queue_safety_buffer(string: "")- Specifies a duration after which cross-cluster revocation requests will be removed as expired. This should be set high enough that, if a cluster disappears for a while but later comes back, any revocation requests which it should process will still be there, but not too long as to fill up storage with too many invalid requests. Defaults to48h.tidy_acme(bool: false)- Set to true to tidy stale ACME accounts, orders, authorizations, EABs, and challenges. ACME orders are tidied (deleted)safety_bufferafter the certificate associated with them expires, or after the order and relevant authorizations have expired if no certificate was produced. Authorizations are tidied with the corresponding order.When a valid ACME Account is at least
acme_account_safety_bufferold, and has no remaining orders associated with it, the account is marked as revoked. After anotheracme_account_safety_bufferhas passed from the revocation or deactivation date, a revoked or deactivated ACME account is deleted.acme_account_safety_buffer(string: "720h")- The amount of time that must pass after creation that an account with no orders is marked revoked, and the amount of time after being marked revoked or deactivated. The default is 30 days as hours.
Sample payload
Sample request
Read automatic tidy configuration
This endpoint fetches the current automatic tidy configuration.
This is the combination of the periodic invocation parameters described in the below write handler and the tidy parameters described above in the tidy endpoint.
GET
/pki/config/auto-tidy
Sample request
Sample response
Set automatic tidy configuration
This endpoint allows configuring periodic tidy operations, using the tidy mechanism described above. Status is from automatically run tidies are still reported at the status endpoint described below.
POST
/pki/config/auto-tidy
Parameters
The below parameters are in addition to the regular parameters accepted by the /pki/tidy endpoint documented above.
enabled(bool: false)- Specifies whether automatic tidy is enabled or not.interval_duration(string: "")- Specifies the duration between automatic tidy operations; note that this is from the end of one operation to the start of the next so the time of the operation itself does not need to be considered. Defaults to 12hmaintain_stored_certificate_counts(bool: false)- When enabled, maintains expensive counts of certificates. During initialization of the mount, a LIST of all certificates is performed to get a baseline figure and throughout operations like issuance, revocation, and subsequent tidies, the figure is updated.
Note: It is strongly recommend to not enable this value if 50k or more certificates are stored in the mount or if many PKI mounts are in use in this cluster. Instead, use audit logs and aggregate this data externally to Vault so as not to impact Vault performance.
publish_stored_certificate_count_metrics(bool: false)- When enabled, publishes the value computed bymaintain_stored_certificate_countsto the mount's metrics. This requires the former to be enabled.
Sample payload
Sample request
Tidy status
This is a read only endpoint that returns information about the current tidy operation, or the most recent if none are currently running.
The result includes the following fields:
safety_buffer: the value of this parameter when initiating the tidy operationtidy_cert_store: the value of this parameter when initiating the tidy operationtidy_revoked_certs: the value of this parameter when initiating the tidy operationstate: one of Inactive, Running, Finished, Error, Cancelling, or Cancellederror: the error message, if the operation ran into an errortime_started: the time the operation startedtime_finished: the time the operation finishedmessage: One of Tidying certificate store: checking entry N of TOTAL or Tidying revoked certificates: checking certificate N of TOTALcert_store_deleted_count: The number of certificate storage entries deletedrevoked_cert_deleted_count: The number of revoked certificate entries deletedmissing_issuer_cert_count: The number of revoked certificates which were missing a valid issuer referencetidy_expired_issuers: the value of this parameter when initiating the tidy operationissuer_safety_buffer: the value of this parameter when initiating the tidy operationtidy_move_legacy_ca_bundle: the value of this parameter when initiating the tidy operationtidy_revocation_queue: the value of this parameter when initiating the tidy operationrevocation_queue_deleted_count: the number of revocation queue entries deletedtidy_cross_cluster_revoked_certs: the value of this parameter when initiating the tidy operationcross_revoked_cert_deleted_count: the number of cross-cluster revoked certificate entries deletedrevocation_queue_safety_buffer: the value of this parameter when initiating the tidy operationpause_duration: the value of this parameter when initiating the tidy operationlast_auto_tidy_finished: the time when the last auto-tidy operation finished; may be different thantime_finishedespecially if the last operation was a manually executed tidy operation. Set to current time at mount time to delay the initial auto-tidy operation; not persisted.
GET
/pki/tidy-status
Sample request
Sample response
Cancel tidy
This endpoint allows cancelling a running tidy operation. It takes no parameter and cancels the tidy at the next available checkpoint, which may process additional certificates between when the operation was marked as cancelled and when the operation stopped.
The response to this endpoint is the same as the status.
POST
/pki/tidy-cancel
Sample request
Sample response
Cluster scalability
See PKI Cluster Scalability in the considerations page.
Managed keys
Note: Managed keys are an Enterprise only feature.
The Generate Root and Generate Intermediate API calls can leverage the Managed Keys feature, delegating operations that require private key material to an external system.
To leverage a Managed Key, assuming it has already been configured, set the type parameter to kms within either, Generate Root or Generate Intermediate APIs, and one of either managed_key_name or managed_key_id parameters specifying a Managed Key to use. As with the internal type for those APIs, if the type parameter is set to kms, there is no way to read/fetch the private key.
The API call will fail if the specified Managed Key is not properly configured or arguments detailing private key attributes are specified such as key_type or key_bits.
Once either of the certificate APIs have successfully executed, all other PKI operations behave the same, with no other special configuration or parameters required.
Vault CLI with DER/PEM responses
The Vault CLI can only display JSON responses. For APIs that return non-JSON formatted data such as DER and PEM formats, vault read will fail without the -format=raw option added in Vault 1.13 or another client such as curl must be used.
Last updated