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.

Table of contents

• Notice About New Multi-Issuer Functionality
• ACME Certificate Issuance
  • ACME Directories
  • Get ACME EAB Binding Token
  • List Unused ACME EAB Binding Tokens
  • Delete Unused ACME EAB Binding Tokens
  • Get ACME Configuration
  • Set ACME Configuration
• Issuing Certificates
  • List Roles
  • Read Role
  • Generate Certificate and Key
  • Sign Certificate
  • Sign Intermediate
  • Sign Self-Issued
  • Sign Verbatim
  • Revoke Certificate
  • Revoke Certificate with Private Key
  • List Revoked Certificates
  • List Revocation Requests
  • List Cross-Cluster Revocations
• Accessing Authority Information
  • List Issuers
  • Read Issuer Certificate
  • Read Default Issuer Certificate Chain
  • Read Issuer CRL
  • OCSP Request
  • List Certificates
  • Read Certificate
• Managing Keys and Issuers
  • List Issuers
  • List Keys
  • Generate Key
  • Generate Root
  • Generate Intermediate CSR
  • Import CA Certificates and Keys
  • Read Issuer
  • Update Issuer
  • Revoke Issuer
  • Delete Issuer
  • Import Key
  • Read Key
  • Update Key
  • Delete Key
  • Delete All Issuers and Keys
• Managing Authority Information
  • List Roles
  • Create/Update Role
  • Read Role
  • Delete Role
  • Read URLs
  • Set URLs
  • Read Issuers Configuration
  • Set Issuers Configuration
  • Read Keys Configuration
  • Set Keys Configuration
  • Read Cluster Configuration
  • Set Cluster Configuration
  • Read CRL Configuration
  • Set CRL Configuration
  • Rotate CRLs
  • Rotate Delta CRLs
  • Combining CRLs from the Same Issuer
  • Sign Revocation List
  • Tidy
  • Read Automatic Tidy Configuration
  • Set Automatic Tidy Configuration
  • Tidy Status
  • Cancel Tidy
• Cluster Scalability
• Managed Key (Enterprise Only)
• Vault CLI with DER/PEM responses

Notice about new Multi-Issuer functionality

Vault since 1.11.0 allows a single PKI mount to have multiple Certificate Authority (CA) certificates ("issuers") in a single mount, for the purpose of facilitating rotation. All issuers within a single mount are treated as a single Authority, meaning that:

1. Certificate Revocation List (CRL) configuration is common to all issuers,
2. All authority access URLs are common to all issuers,
3. Issued certificates' serial numbers will be unique across all issuers.

However, since each issuer may have a distinct subject and keys, different issuers may have different CRLs.

It is strongly encouraged to limit the scope of CAs within a mount and not to mix different types of CAs (roots and intermediates).

ACME certificate issuance

Starting with Vault 1.14, Vault supports the ACME certificate lifecycle management protocol for issuing and renewing leaf server certificates.

In order to use ACME, a cluster path must be set and ACME must be enabled in its configuration with the required headers enabled on the mount tuning.

Using ACME with a role requires no_store=false to be set on the role; this allows the certificate to be stored and later fetched through the ACME protocol.

ACME directories

Vault PKI supports the following ACME directories, providing different restrictions around usage (defaults, a specific issuer and/or a specific role). To interact with these directories, specify the directory URL in an ACME client. For example, with the EFF's CertBot:

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

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

When a role is not specified (for the first two directory URLs, or four lines in the table), 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.

ACME challenge types

Vault supports the following ACME challenge types presently:

• http-01, supporting both dns and ip identifiers.
• dns-01, supporting dns identifiers including wildcards.
• tls-alpn-01, supporting only non-wildcard dns identifiers.

A custom DNS resolver used by the server for looking up DNS names for use with both mechanisms can be added via the ACME configuration.

ACME external account bindings

ACME External Account Binding (EAB) Policy can enforce that clients need to have a valid external account binding to Vault. Before registering a new account, an authenticated Vault client will need to fetch a new EAB token. This returns two values: a key identifier and an HMAC key used by the ACME client to authenticate with EAB. For example:

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

With or without EAB, requests from the ACME client are not authenticated using traditional Vault authentication, but are instead authenticated through the ACME protocol. With EAB however, a Vault authenticated client will have to fetch an EAB token and pass it to the ACME client for use on the initial registration: this binds the ACME client's registration to an authenticated Vault endpoint, but not further to the client's entity or other information.

ACME accounts

ACME Accounts are created specific to a particular directory and are not portable across Performance Secondary clusters.

ACME required headers

ACME requires the following response headers (allowed_response_headers) to be specified by mount tuning:

• Replay-Nonce
• Link
• Location

On an existing mount, these can be specified by running the following command:

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

Get ACME EAB binding token

This endpoint returns a new ACME binding token. The id response field can be used as the key identifier and the key response field be used as the EAB HMAC key in the ACME Client.

Each call to this endpoint will generate and return a new EAB binding token that is linked to the specific ACME directory it resides under. EAB tokens are not usable across different ACME directories.

Parameters

No parameters.

Sample request

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

Sample response

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

List unused ACME EAB binding tokens

This endpoint returns a list of all unused ACME binding tokens; once used, they will be removed from this list.

Sample request

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

Sample response

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

Delete unused ACME EAB binding tokens

This endpoint allows the deletion of an unused ACME binding token.

Parameters

• key_id (string: <required>) - The id of the EAB binding token to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd

Get ACME configuration

This endpoint allows reading of the current ACME server configuration used by this mount.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/acme

Sample response

{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true
  },
}

Set ACME configuration

This endpoint allows setting the ACME server configuration used by this mount.

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 the default_directory_policy specifies a role, it must be allowed under this configuration.

• default_directory_policy (string: "sign-verbatim") - Specifies the behavior of the default ACME directory. Can be forbid, sign-verbatim or a role given by role:<role_name>. If a role is used, it must be present in allowed_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

{
    "enabled": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/acme

Sample response

{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true
  }
}

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.

Sample request

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

Sample response

{
  "auth": null,
  "data": {
    "keys": ["dev", "prod"]
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false
}

Read role

This endpoint queries the role definition. It is useful to both operators and users.

Parameters

• name (string: <required>) - Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/roles/my-role

Sample response

{
  "data": {
    "allow_any_name": false,
    "allow_ip_sans": true,
    "allow_localhost": true,
    "allow_subdomains": false,
    "allowed_domains": ["example.com", "foobar.com"],
    "allowed_uri_sans": ["example.com", "spiffe://*"],
    "allowed_other_sans": [
      "1.3.6.1.4.1.311.20.2.3;utf8:devops@example.com",
      "1.3.6.1.4.1.311.20.2.4;UTF-8:*"
    ],
    "client_flag": true,
    "code_signing_flag": false,
    "key_bits": 2048,
    "key_type": "rsa",
    "ttl": "6h",
    "max_ttl": "12h",
    "server_flag": true,
    ... additional fields elided ...
  }
}

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).

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 string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

• 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 one common_name is desired, specify the alternative names in the alt_names list.

• 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 in allowed_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 is UTF8. 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's max_ttl value. If not provided, the role's ttl value will be used. Note that the role values default to system values if not explicitly set. See not_after as an alternative for setting an absolute end date (rather than a relative one).

• format (string: "pem") - Specifies the format for returned data. Can be pem, der, or pem_bundle; defaults to pem. If der, the output is base64 encoded. If pem_bundle, the certificate field 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 to der which will return either base64-encoded DER or PEM-encoded DER, depending on the value of format. The other option is pkcs8 which will return the key marshalled as PEM-encoded PKCS8.

• exclude_cn_from_sans (bool: false) - If true, the given common_name will 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 format YYYY-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 returned ca_chain field 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 against allowed_user_ids on the role.

Sample payload

{
  "common_name": "www.example.com"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/issue/my-role

Sample response

{
  "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05",
  "renewable": false,
  "lease_duration": 21600,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n",
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"
    ],
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n",
    "private_key_type": "rsa",
    "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58"
  },
  "warnings": "",
  "auth": null
}

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).

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 string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

• 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 one common_name is desired, specify the alternative names in the alt_names list.

• 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 in allowed_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 is UTF8. 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's max_ttl value. If not provided, the role's ttl value will be used. Note that the role values default to system values if not explicitly set. See not_after as an alternative for setting an absolute end date (rather than a relative one).

• format (string: "pem") - Specifies the format for returned data. Can be pem, der, or pem_bundle. If der, the output is base64 encoded. If pem_bundle, the certificate field 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 given common_name will 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 format YYYY-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 returned ca_chain field 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 against allowed_user_ids on the role.

Sample payload

{
  "csr": "...",
  "common_name": "example.com"
}

Sample response

{
  "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05",
  "renewable": false,
  "lease_duration": 21600,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n",
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"
    ],
    "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58"
  },
  "auth": null
}

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.

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

• 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 one common_name is desired, specify the alternative names in the alt_names list.

• 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 in allowed_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 is UTF8. 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. See not_after as an alternative for setting an absolute end date (rather than a relative one).

• format (string: "pem") - Specifies the format for returned data. Can be pem, der, or pem_bundle. If der, the output is base64 encoded. If pem_bundle, the certificate field 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 of 0 means a literal path length of zero.

• exclude_cn_from_sans (bool: false) - If true, the given common_name will 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 to true, 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 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 requested Subject's named Serial Number value, if any. If you want more than one, specify alternative names in the alt_names map 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 the ttl field. 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 format YYYY-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).

• 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.

• 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

{
  "csr": "...",
  "common_name": "example.com"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/root/sign-intermediate

Sample response

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n",
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"
    ],
    "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58"
  },
  "auth": null
}

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 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).

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

• 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

{
  "certificate": "..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/root/sign-self-issued

Sample response

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"
  },
  "auth": null
}

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.

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

• name (string: "") - Specifies a role. If set, the following parameters from the role will have effect: ttl, max_ttl, generate_lease, no_store and not_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 the KeyUsage part of the value. Values are not case-sensitive. To specify no default key usage constraints, set this to an empty list.

• 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 the ExtKeyUsage part of the value. Values are not case-sensitive. To specify no key default usage constraints, set this to an empty list.

• ext_key_usage_oids (string: "") - A comma-separated string or list of extended key usage oids.

• ttl (string: "") - Specifies the requested Time To Live. Cannot be greater than the engine's max_ttl value. If not provided, the engine's ttl value will be used, which defaults to system values if not explicitly set. See not_after as an alternative for setting an absolute end date (rather than a relative one).

• format (string: "pem") - Specifies the format for returned data. Can be pem, der, or pem_bundle. If der, the output is base64 encoded. If pem_bundle, the certificate field 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 format YYYY-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).

• 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 returned ca_chain field 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

{
  "csr": "..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/sign-verbatim

Sample response

{
  "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05",
  "renewable": false,
  "lease_duration": 21600,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n",
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"
    ],
    "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58"
  },
  "auth": null
}

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.

Parameters

• 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

{
  "serial_number": "39:dd:2e..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/revoke

Sample response

{
  "data": {
    "revocation_time": 1433269787
  }
}

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.

Parameters

• 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

{
  "serial_number": "39:dd:2e...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/revoke-with-key

Sample response

{
  "data": {
    "revocation_time": 1433269787
  }
}

List revoked certificates

This endpoint returns a list of serial numbers that have been revoked on the local cluster.

Sample request

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

Sample response

{
  "data": {
    "keys": [
      "3d:80:91:c3:c2:34:3b:81:69:3d:92:a3:80:69:db:53:04:26:ab:b4"
    ]
  }
}

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.

Sample request

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

Sample response

{
  "data": {
    "key_info": {
      "3d:80:91:c3:c2:34:3b:81:69:3d:92:a3:80:69:db:53:04:26:ab:b4": {
        "requesting_cluster": "48327b28-8325-6d79-6a0b-4cbaa6f27b4a"
      }
    },
    "keys": [
      "3d:80:91:c3:c2:34:3b:81:69:3d:92:a3:80:69:db:53:04:26:ab:b4"
    ]
  }
}

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.

Sample request

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

Sample response

{
  "data": {
    "key_info": {
      "7f:fd:12:5b:16:29:bb:28:ea:24:bc:a1:80:f7:4e:6e:a0:69:b9:95": {
        "revoking_clusters": [
          "48327b28-8325-6d79-6a0b-4cbaa6f27b4a"
        ]
      }
    },
    "keys": [
      "7f:fd:12:5b:16:29:bb:28:ea:24:bc:a1:80:f7:4e:6e:a0:69:b9:95"
    ]
  }
}

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.

Sample request

$ curl \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/issuers

Sample response

{
  "data": {
    "key_info": {
      "1ae8ce9d-2f70-0761-a465-8c9840a247a2": {
        "issuer_name": "imported-root"
      },
      "3dc79a5a-7a6c-70e2-1123-94b88557ba12": {
        "issuer_name": "root-x1"
      }
    },
    "keys": [
      "1ae8ce9d-2f70-0761-a465-8c9840a247a2",
      "3dc79a5a-7a6c-70e2-1123-94b88557ba12"
    ]
  }
}

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.

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

Sample request

$ curl \
    http://127.0.0.1:8200/v1/pki/issuer/root-x1/json

Sample response

{
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
      "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..."
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nnMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL...",
    "revocation_time": 0
  }
}

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.

Sample request

$ curl \
    http://127.0.0.1:8200/v1/pki/ca_chain

Sample response

<PEM-encoded certificate chain>

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.

These are unauthenticated endpoints.

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

Sample request

$ curl \
    http://127.0.0.1:8200/v1/pki/issuer/root-x1/crl

Sample response

{
  "data": {
    "crl": "-----BEGIN X509 CRL-----\nMIIBizB1AgEBMA0GCSqGSIb3DQEBCwUAMBIxEDAOBgNVBAMTB3Jvb3QgeDEXDTIy\n..."
  }
}

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.

At this time there are certain limitations of the OCSP implementation at this path:

1. Only a single serial number within the request will appear in the response,
2. None of the extensions defined in the RFC are supported for requests or responses,
3. Ed25519 backed CA's are not supported for OCSP requests,
4. Note that this API will not work with the Vault client as both request and responses are DER encoded, and
5. 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

openssl ocsp -no_nonce -issuer issuer.pem -CAfile ca_chain.pem -cert cert-to-revoke.pem -text -url $VAULT_ADDR/v1/pki/ocsp

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.

Sample request

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

Sample response

{
  "data": {
    "keys": [
      "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1",
      "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21"
    ]
  }
}

Read certificate

This endpoint retrieves the certificate specified by its serial number, including issued certificates.

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 for serial are:

• <serial> for the certificate with the given serial number, in hyphen-separated or colon-separated hexadecimal.
• ca for the default issuer's CA certificate
• crl for the default issuer's CRL
• ca_chain for the default issuer's CA trust chain.

Sample request

$ curl \
    http://127.0.0.1:8200/v1/pki/cert/67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72

Sample response

{
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n...",
    "revocation_time": 1667400107,
    "revocation_time_rfc3339": "2022-11-02T14:41:47.327515Z",
    "issuer_id": "e27bf456-51e1-d937-0001-4a609184fd9b"
  }
}

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.

Sample request

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

Sample response

{
  "data": {
    "key_info": {
      "f9244f54-adc7-4a5c-6b08-6ca3a3325620": {
        "key_name": "imported-root-key"
      },
    },
    "keys": [
      "f9244f54-adc7-4a5c-6b08-6ca3a3325620",
    ]
  }
}

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.

Parameters

• type (string: <required>) - Specifies the type of the key to create. If exported, the private key will be returned in the response; if internal the private key will not be returned and cannot be retrieved later; kms is 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 ref default may not be used as a name.

• key_type (string: "rsa") - Specifies the desired key type; must be rsa, ed25519 or ec.

• key_bits (int: 0) - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with key_type=rsa, allowed values are: 2048 (default), 3072, or 4096; with key_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored with key_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

{
  "key_type": "ec",
  "key_bits": "256",
  "key_name": "root-key-2022"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/keys/generate/internal

Sample response

{
  "request_id": "8ad22b2f-7d14-f2cd-a10a-d1abc33676ab",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "key_id": "adda2443-a8aa-d181-9d07-07c7be6a76ab",
    "key_name": "root-key-2022",
    "key_type": "ec"
  },
  "warnings": null
}

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.

Parameters

• type (string: <required>) - Specifies the type of the root to create. If exported, the private key will be returned in the response; if internal the private key will not be returned and cannot be retrieved later; if existing, we use the value of the key_ref parameter to find existing key material to create the CSR; kms is 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 value default. 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 ref default may not be used as a name.

• key_ref (string: "default") - Specifies the key (either default, by name, or by identifier) to use for generating this request. Only suitable for type=existing requests.

• common_name (string: <required>) - Specifies the requested CN for the certificate. If more than one common_name is desired, specify the alternative names in the alt_names list.

• 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 in allowed_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 is UTF8. 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). See not_after as an alternative for setting an absolute end date (rather than a relative one).

• format (string: "pem") - Specifies the format for returned data. Can be pem, der, or pem_bundle. If der, the output is base64 encoded. If pem_bundle, the certificate field 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 to der which will return either base64-encoded DER or PEM-encoded DER, depending on the value of format. The other option is pkcs8 which will return the key marshalled as PEM-encoded PKCS8.

• key_type (string: "rsa") - Specifies the desired key type; must be rsa, ed25519 or ec.

• key_bits (int: 0) - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with key_type=rsa, allowed values are: 2048 (default), 3072, or 4096; with key_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored with key_type=ed25519.

• 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 of 0 means a literal path length of zero.

• exclude_cn_from_sans (bool: false) - If true, the given common_name will 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 the alt_names map 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 the ttl field. 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 format YYYY-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 rsa currently 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

{
  "common_name": "example.com"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/root/generate/internal

Sample response

{
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "expiration": "1654105687",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n",
    "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58",
    "issuer_id": "7b493f17-6c08-ff73-cf1a-99bfcc448a73",
    "issuer_name": "",
    "key_id": "22b82e37-529d-7251-7d78-3862bfd069ac",
    "key_name": ""
  },
  "auth": null
}

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.

Parameters

• type (string: <required>) - Specifies the type of the intermediate to create. If exported, the private key will be returned in the response; if internal the private key will not be returned and cannot be retrieved later; if existing, we expect the key_ref parameter to use existing key material to create the CSR; kms is 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 one common_name is desired, specify the alternative names in the alt_names list.

• 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 in allowed_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 is UTF8. This can be a comma-delimited list or a JSON string slice.

• format (string: "pem") - Specifies the format for returned data. This can be pem, der, or pem_bundle; defaults to pem. If der, the output is base64 encoded. If pem_bundle, the csr field 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 to der which will return either base64-encoded DER or PEM-encoded DER, depending on the value of format. The other option is pkcs8 which will return the key marshalled as PEM-encoded PKCS8.

• key_type (string: "rsa") - Specifies the desired key type; must be rsa, ed25519 or ec. Not suitable for type=existing requests.

• key_bits (int: 0) - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with key_type=rsa, allowed values are: 2048 (default), 3072, or 4096; with key_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored with key_type=ed25519. Not suitable for type=existing requests.

• key_name (string: "") - When a new key is created with this request, optionally specifies the name for this. The global ref default may not be used as a name.

• key_ref (string: "default") - Specifies the key (either default, by name, or by identifier) to use for generating this request. Only suitable for type=existing requests.

• 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).

• exclude_cn_from_sans (bool: false) - If true, the given common_name will 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 the alt_names map 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

{
  "common_name": "www.example.com"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/intermediate/generate/exported

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----",
    "private_key_type": "rsa"
  },
  "warnings": null,
  "auth": null
}

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.

Parameters

• pem_bundle (string: <required>) - Specifies the unencrypted private key and certificate, concatenated in PEM format.

• certificate (string: <required>) - Specifies the certificates to import, concatenated in PEM format.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data "@payload.json" \
    http://127.0.0.1:8200/v1/pki/config/ca

Note that if you provide the data through the HTTP API, it must be JSON-formatted, with newlines replaced with \n, like so:

{
  "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----"
}

Sample response

{
  "data": {
    "imported_issuers": ["1ae8ce9d-2f70-0761-a465-8c9840a247a2"],
    "imported_keys": ["97be2525-717a-e2f7-88da-0a20e11aad88"],
    "mapping": {
      "1ae8ce9d-2f70-0761-a465-8c9840a247a2": "97be2525-717a-e2f7-88da-0a20e11aad88"
    },
    "existing_issuers": [],
    "existing_keys": []
  }
}

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.

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/issuer/default

Sample response

{
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
      "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..."
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
    "issuer_id": "7545992c-1910-0898-9e64-d575549fbe9c",
    "issuer_name": "root-x1",
    "key_id": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf",
    "leaf_not_after_behavior": "truncate",
    "manual_chain": null,
    "usage": "read-only,issuing-certificates,crl-signing,ocsp-signing"
  }
}

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.

Parameters

• issuer_ref (string: <required>) - Reference to an existing issuer, either by Vault-generated identifier, the literal string default to 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 value default.

• leaf_not_after_behavior (string: "err") - Behavior of a leaf's NotAfter field during issuance. Valid options are:

  • err, to error if the computed NotAfter exceeds that of this issuer;
  • truncate to silently truncate the requested NotAfter value to that of this issuer; or
  • permit to allow this issuance to succeed with a NotAfter value exceeding that of this issuer.

• manual_chain ([]string: nil) - Chain of issuer references to build this issuer's computed CAChain field from, when non-empty.

• 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; or
  • crl-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

• revocation_signature_algorithm (string: "") - Which signature algorithm to use when building CRLs. See Go's x509.SignatureAlgorithm constant 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.

• 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.

• 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, and ocsp_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 of path from the cluster-local configuration endpoint /config/cluster, and the literal value '{{cluster_aia_path}}' with the value of aia_path from the cluster-local configuration endpoint /config/cluster.

Sample payload

{
  "issuer_name": "root-x1"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/issuer/default

Sample response

{
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
      "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..."
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
    "issuer_id": "7545992c-1910-0898-9e64-d575549fbe9c",
    "issuer_name": "root-x1",
    "key_id": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf",
    "leaf_not_after_behavior": "truncate",
    "manual_chain": null,
    "usage": "read-only,issuing-certificates,crl-signing,ocsp-signing",
    "revocation_signature_algorithm": "",
    "issuing_certificates": ["<url1>", "<url2>"],
    "crl_distribution_points": ["<url1>", "<url2>"],
    "ocsp_servers": ["<url1>", "<url2>"]
  }
}

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.

Parameters

No parameters.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/pki/issuer/old-intermediate/revoke

Sample response

{
  "data": {
    "ca_chain": [
      "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
      "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..."
    ],
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...",
    "issuer_id": "7545992c-1910-0898-9e64-d575549fbe9c",
    "issuer_name": "old-intermediate",
    "key_id": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf",
    "leaf_not_after_behavior": "truncate",
    "manual_chain": null,
    "usage": "read-only,issuing-certificates,crl-signing"
    "revocation_time": 1433269787,
  }
}

Delete issuer

This endpoint deletes the specified issuer. A warning is emitted and the default is cleared if this issuer is the default issuer.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/issuer/root-x1

Import key

This endpoint allows an operator to import a single pem encoded rsa, ec, or ed25519 key.

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 value default.

Sample payload

{
  "key_name": "my-imported-key",
  "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/keys/import

Sample response

{
  "data": {
    "key_id": "2cf03991-b052-1dc3-393e-374b41f8dcd8",
    "key_name": "my-imported-key",
    "key_type": "rsa"
  },
}

Read key

This endpoint allows an operator to fetch information about an existing key.

Parameters

• key_ref (string: <required>) - Reference to an existing key, either by Vault-generated identifier, the literal string default to refer to the currently configured default key, or the name assigned to a key. This parameter is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/key/default

Sample response

{
  "data": {
    "key_id": "8c4046f8-52a8-0974-29d2-745d8a0dd848",
    "key_name": "key-root-x1",
    "key_type": "rsa"
  }
}

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.

Parameters

• key_ref (string: <required>) - Reference to an existing key, either by Vault-generated identifier, the literal string default to 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 value default.

Sample payload

{
  "key_name": "key-root-x1"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/key/default

Sample response

{
  "data": {
    "key_id": "8c4046f8-52a8-0974-29d2-745d8a0dd848",
    "key_name": "key-root-x1",
    "key_type": "rsa"
  }
}

Delete key

This endpoint deletes the specified key. A warning is emitted and the default is cleared if this key is the default key.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/key/key-root-x1

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.

Sample request

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

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.

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 value default, a name, or an issuer ID. Use ACLs to prevent access to the /pki/issuer/:issuer_ref/{issue,sign}/:name paths to prevent users overriding the role's issuer_ref value.

• 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 of max_ttl, whichever is shorter. See not_after as 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 for localhost as one of the requested common names. This is useful for testing and to allow clients on a single host to talk securely.

• allowed_domains (list: []) - Specifies the domains this role is allowed to issue certificates for. This is used with the allow_bare_domains, allow_subdomains, and allow_glob_domains options to determine the type of matching between these domains and the values of common name, DNS-typed SAN entries, and Email-typed SAN entries. When allow_any_name is used, this attribute has no effect.

• allowed_domains_template (bool: false) - When set, allowed_domains may 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 with allowed_domains is example.com, this allows clients to actually request a certificate containing the name example.com as one of the DNS values on the final certificate. In some scenarios, this can be considered a security risk. Note that when an allowed_domain field contains a potential wildcard character (for example, allowed_domains=*.example.com) and allow_bare_domains and allow_wildcard_certificates are both enabled, issuance of a wildcard certificate for *.example.com will 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, an allowed_domains value of example.com with this option set to true will allow foo.example.com and bar.example.com as well as *.example.com. To restrict issuance of wildcards by this option, see allow_wildcard_certificates below. This option is redundant when using the allow_any_name option.

• allow_glob_domains (bool: false) - Allows names specified in allowed_domains to contain glob patterns (e.g. ftp*.example.com). Clients will be allowed to request certificates with names matching the glob patterns.

• allow_wildcard_certificates (bool: true) - Allows the issuance of certificates with RFC 6125 wildcards in the CN field. When set to false, 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, and
  • f*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 both enforce_hostnames and allow_wildcard_certificates are 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_sans may 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 is UTF8 or UTF-8. The value part of an element may be a * to allow any value with that OID. Alternatively, specifying a single * will allow any other_sans input.

• 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, and ed25519 are supported, or when signing existing CSRs, any can 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). When any is used, this role cannot generate certificates and can only be used to sign CSRs.

• key_bits (int: 0) - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with key_type=rsa, allowed values are: 2048 (default), 3072, or 4096; with key_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored with key_type=ed25519 or in signing operations when key_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).

• 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 the KeyUsage part 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 the ExtKeyUsage part 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; use use_csr_sans for 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; use use_csr_common_name for 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 by vault revoke <lease_id> when certificates are associated with leases. It can also be done using the pki/revoke endpoint. However, when lease generation is disabled, invoking pki/revoke would 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 of false for generate_lease.

• require_cn (bool: true) - If set to false, makes the common_name field 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 the ttl field.

• not_after (string) - Set the Not After field of the certificate with specified date value. The value format should be given in UTC format YYYY-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_domains and 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 the user_ids request parameter.

Sample payload

{
  "allowed_domains": ["example.com"],
  "allow_subdomains": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/roles/my-role

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.

Parameters

• name (string: <required>) - Specifies the name of the role to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/roles/my-role

Read URLs

This endpoint fetches the URLs to be encoded in generated certificates. No URL configuration will be returned until the configuration is set.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/urls

Sample response

{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "issuing_certificates": ["<url1>", "<url2>"],
    "crl_distribution_points": ["<url1>", "<url2>"],
    "ocsp_servers": ["<url1>", "<url2>"]
  },
  "auth": null
}

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.

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.

• 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, and ocsp_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 of path from the cluster-local configuration endpoint /config/cluster, and the literal value '{{cluster_aia_path}}' with the value of aia_path from 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}}/der
  • crl_distribution_points={{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der
  • ocsp_servers={{cluster_aia_path}}/ocsp

Sample payload

{
  "issuing_certificates": ["{{cluster_aia_path}}/issuer/{{issuer_id}}/der"],
  "crl_distribution_points": ["{{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der"],
  "ocsp_servers": ["{{cluster_aia_path}}/ocsp"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/urls

Read issuers configuration

This endpoint allows getting the value of the default issuer.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/issuers

Sample response