--- layout: api page_title: PKI - Secrets Engines - HTTP API description: This is the API documentation for the Vault PKI secrets engine. --- # 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](/docs/secrets/pki). 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](#notice-about-new-multi-issuer-functionality) - [Issuing Certificates](#issuing-certificates) - [List Roles](#list-roles) - [Read Role](#read-role) - [Generate Certificate and Key](#generate-certificate-and-key) - [Sign Certificate](#sign-certificate) - [Sign Intermediate](#sign-intermediate) - [Sign Self-Issued](#sign-self-issued) - [Sign Verbatim](#sign-verbatim) - [Revoke Certificate](#revoke-certificate) - [Accessing Authority Information](#accessing-authority-information) - [List Issuers](#list-issuers) - [Read Issuer Certificate](#read-issuer-certificate) - [Read Default Issuer Certificate Chain](#read-default-issuer-certificate-chain) - [Read Issuer CRL](#read-issuer-crl) - [List Certificates](#list-certificates) - [Read Certificate](#read-certificate) - [Managing Keys and Issuers](#managing-keys-and-issuers) - [List Issuers](#list-issuers) - [List Keys](#list-keys) - [Generate Root](#generate-root) - [Generate Intermediate CSR](#generate-intermediate-csr) - [Import CA Certificates and Keys](#import-ca-certificates-and-keys) - [Read Issuer](#read-issuer) - [Update Issuer](#update-issuer) - [Delete Issuer](#delete-issuer) - [Import Key](#import-key) - [Read Key](#read-key) - [Update Key](#update-key) - [Delete Key](#delete-key) - [Delete All Issuers and Keys](#delete-all-issuers-and-keys) - [Managing Authority Information](#managing-authority-information) - [List Roles](#list-roles) - [Create/Update Role](#create-update-role) - [Read Role](#read-role) - [Delete Role](#delete-role) - [Read URLs](#read-urls) - [Set URLs](#set-urls) - [Read Issuers Configuration](#read-issuers-configuration) - [Set Issuers Configuration](#set-issuers-configuration) - [Read Keys Configuration](#read-keys-configuration) - [Set Keys Configuration](#set-keys-configuration) - [Read CRL Configuration](#read-crl-configuration) - [Set CRL Configuration](#set-crl-configuration) - [Rotate CRLs](#rotate-crls) - [Tidy](#tidy) - [Tidy Status](#tidy-status) - [Cluster Scalability](#cluster-scalability) - [Managed Key](#managed-keys) (Enterprise Only) - [Vault CLI with DER/PEM responses](#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). ~> **Note**: Some functionality will not work if a default issuer is not configured. Vault automatically selects the default issuer from the current issuing certificate on migration from an older Vault version (Vault < 1.11.0). ## 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. | Method | Path | | :----- | :----------- | | `LIST` | `/pki/roles` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/pki/roles ``` #### Sample Response ```json { "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. | Method | Path | | :----- | :----------------- | | `GET` | `/pki/roles/:name` | #### Parameters - `name` `(string: )` - Specifies the name of the role to read. This is part of the request URL. #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/roles/my-role ``` #### Sample Response ```json { "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`). ~> **Note**: The private key is _not_ stored. If you do not save the private key from the response, you will need to request a new certificate. | Method | Path | Issuer | | :----- | :------------------------------------ | :------------ | | `POST` | `/pki/issue/:name` | Role selected | | `POST` | `/pki/issuer/:issuer_ref/issue/:name` | Path selected | #### Parameters - `name` `(string: )` - Specifies the name of the role to create the certificate against. This is part of the request URL. - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/issue/:name` path and takes its value from the role's `issuer_ref` field. - `common_name` `(string: )` - Specifies the requested CN for the certificate. If the CN is allowed by role policy, it will be issued. If more than 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: `;:` 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. 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`. #### Sample Payload ```json { "common_name": "www.example.com" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/issue/my-role ``` #### Sample Response ```json { "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`). | Method | Path | Issuer | | :----- | :----------------------------------- | :------------ | | `POST` | `/pki/sign/:name` | Role selected | | `POST` | `/pki/issuer/:issuer_ref/sign/:name` | Path selected | #### Parameters - `name` `(string: )` - Specifies the name of the role to create the certificate against. This is part of the request URL. - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/sign/:name` path and takes its value from the role's `issuer_ref` field. - `csr` `(string: )` - Specifies the PEM-encoded CSR. - `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 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: `;:` 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`. #### Sample Payload ```json { "csr": "...", "common_name": "example.com" } ``` #### Sample Response ```json { "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. ~> **Note**: This is a privileged endpoint, as callers are granted a new intermediate certificate, with which they can issue for arbitrary names. Access to this endpoint should be restricted by policy to only trusted operators. | Method | Path | Issuer | | :----- | :------------------------------------------ | :------- | | `POST` | `/pki/root/sign-intermediate` | `default` | | `POST` | `/pki/issuer/:issuer_ref/sign-intermediate` | Selected | #### Parameters - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/root/sign-intermediate` path and takes the value `default`. - `csr` `(string: )` - Specifies the PEM-encoded CSR to be signed. - `common_name` `(string: )` - 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: `;:` 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](https://tools.ietf.org/html/rfc5280#section-4.2.1.10). - `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](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) 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. - `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`. #### Sample Payload ```json { "csr": "...", "common_name": "example.com" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/root/sign-intermediate ``` #### Sample Response ```json { "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 an extremely privileged endpoint_**. The given certificate will be signed as-is with only minimal validation performed (is it a CA cert, and is it actually self-issued). The only values that will be changed will be the authority key ID, the issuer DN, and, if set, any distribution points.

It is recommended to limit this endpoint to only trusted operators. This is generally only needed for root certificate rolling in cases where you don't want/can't get access to a CSR (such as if it's a root stored in Vault where the key is not exposed). If you don't know whether you need this endpoint, you most likely should be using a different endpoint (such as `sign-intermediate`). | Method | Path | Issuer | Requires `sudo` capability | | :----- | :----------------------------------------- | :-------- | :------------------------- | | `POST` | `/pki/root/sign-self-issued` | `default` | yes | | `POST` | `/pki/issuer/:issuer_ref/sign-self-issued` | Selected | no | #### Parameters - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/root/sign-self-issued` path and takes the value `default`. - `certificate` `(string: )` - 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 ```json { "certificate": "..." } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/root/sign-self-issued ``` #### Sample Response ```json { "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.** | Method | Path | Issuer | | :----- | :---------------------------------------------- | :-------- | | `POST` | `/pki/sign-verbatim(/:name)` | `default` | | `POST` | `/pki/issuer/:issuer_ref/sign-verbatim(/:name)` | Selected | #### Parameters - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/root/sign-self-issued` path and takes the value `default`. - `name` `(string: "")` - Specifies a role. If set, the following parameters from the role will have effect: `ttl`, `max_ttl`, `generate_lease`, `no_store` and `not_before_duration`. - `csr` `(string: )` - 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. ~> Note: previous versions of this document incorrectly called this a constraint; this value is only used as a default when the `KeyUsage` extension is missing from the CSR. - `ext_key_usage` `(list: [])` - Specifies the default extended key usage constraint on the issued certificate. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage - simply drop the `ExtKeyUsage` part of the value. Values are not case-sensitive. To specify no key default usage constraints, set this to an empty list. ~> Note: previous versions of this document incorrectly called this a constraint; this value is only used as a default when the `ExtendedKeyUsage` extension is missing from the CSR. - `ext_key_usage_oids` `(string: "")` - A comma-separated string or list of extended key usage oids. ~> Note: This value is only used as a default when the `ExtendedKeyUsage` extension is missing from the CSR. - `ttl` `(string: "")` - Specifies the requested Time To Live. Cannot be greater than the engine'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`. #### Sample Payload ```json { "csr": "..." } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/sign-verbatim ``` #### Sample Response ```json { "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. ~> **Note**: This operation is privileged as it allows revocation of arbitrary certificates based purely on their serial number. It does not validate that the requesting user issued the certificate or has possession of the private key.

It is not possible to revoke issuers using this path. | Method | Path | | :----- | :------------ | | `POST` | `/pki/revoke` | #### Parameters - `serial_number` `(string: )` - Specifies the serial number of the certificate to revoke, in hyphen-separated or colon-separated hexadecimal. #### Sample Payload ```json { "serial_number": "39:dd:2e..." } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/revoke ``` #### Sample Response ```json { "data": { "revocation_time": 1433269787 } } ``` --- ## 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](#read-issuer-certificate), [their chains](#read-default-issuer-certificate-chain), and [their signed CRLs](#read-issuer-crl), containing an encoded list of revoked certificates previously issued by this authority. Individual issued [certificates can also be read](#read-certificate), assuming their serial number is known. Finally, the list of issuing certificates is public information in this mount. However, the endpoint for [listing all issuers](#list-issuers) in this mount is authenticated, though not generally considered privileged information from a PKI perspective; organizations may choose to lock this down as they see fit. ### 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. | Method | Path | | :----- | :------------- | | `LIST` | `/pki/issuers` | #### Sample Request ```shell-session $ curl \ --request LIST \ http://127.0.0.1:8200/v1/pki/issuers ``` #### Sample Response ```json { "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. | Method | Path | Issuer | Format | | :----- | :----------------------------- | :-------- |:----------------------------------------------------------------------------------| | `GET` | `/pki/cert/ca` | `default` | JSON | | `GET` | `/pki/ca` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/ca/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/issuer/:issuer_ref/json` | Selected | JSON | | `GET` | `/pki/issuer/:issuer_ref/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/issuer/:issuer_ref/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | #### Parameters - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/cert/ca` and `/pki/ca(/pem)?` paths and takes the implicit value `default`. #### Sample Request ```shell-session $ curl \ http://127.0.0.1:8200/v1/pki/issuer/root-x1/json ``` #### Sample Response ```text { "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](#read-issuer-certificate), use the `/pki/issuer/:issuer_ref/json` endpoint instead. These are unauthenticated endpoints. | Method | Path | Issuer | Format | | :----- | :------------------- | :-------- |:----------------------------------------------------------------------------------| | `GET` | `/pki/ca_chain` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/cert/ca_chain` | `default` | JSON | ~> **Note**: As of Vault 1.11.0, these endpoints now return the full chain (including the default issuer's certificate and all parent issuers known to Vault) in these responses. #### Sample Request ```shell-session $ curl \ http://127.0.0.1:8200/v1/pki/ca_chain ``` #### Sample Response ```text ``` ### 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. These are unauthenticated endpoints. ~> **Note**: As of Vault 1.11.0, these endpoints now serve a [version 2](https://datatracker.ietf.org/doc/html/rfc5280#section-5.1.2.1) CRL response. | Method | Path | Issuer | Format | | :----- | :-------------------------------- | :-------- |:----------------------------------------------------------------------------------| | `GET` | `/pki/cert/crl` | `default` | JSON | | `GET` | `/pki/crl` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/crl/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/issuer/:issuer_ref/crl` | Selected | JSON | | `GET` | `/pki/issuer/:issuer_ref/crl/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/issuer/:issuer_ref/crl/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | #### Parameters - `issuer_ref` `(string: )` - 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. ~> Note: This parameter is not present on the `/pki/cert/crl` and `/pki/crl(/pem)?` paths and takes the implicit value `default`. #### Sample Request ```shell-session $ curl \ http://127.0.0.1:8200/v1/pki/issuer/root-x1/crl ``` #### Sample Response ```json { "data": { "crl": "-----BEGIN X509 CRL-----\nMIIBizB1AgEBMA0GCSqGSIb3DQEBCwUAMBIxEDAOBgNVBAMTB3Jvb3QgeDEXDTIy\n..." } } ``` ### List Certificates This endpoint returns a list of the current certificates by serial number only. The response does not include the [special serial numbers](#read-certificate-serial-param-values) (`ca`, `ca_chain`, and `crl`) that can be used with `/pki/cert/:serial`. ~> Note: The endpoint to list all certificates is authenticated. This is to prevent automated enumeration of issued certificates for internal services; however, this information should generally be considered non-sensitive and the certificates themselves are exposed without authentication (provided their serial number is known).

Many Public CAs participate in the Certificate Transparency initiative, where all issued certificates are publicly disclosed in the interest of third-party verification of CA integrity. | Method | Path | | :----- | :----------- | | `LIST` | `/pki/certs` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/pki/certs ``` #### Sample Response ```json { "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. ~> Note: With the exception of the special values (`ca`, `crl`, and `ca_chain`), `/pki/cert/:serial` will return different results on different clusters. This is because stored certificates are not replicated across different Performance Replication clusters. These are unauthenticated endpoints. | Method | Path | Format | | :----- | :-------------------------- |:----------------------------------------------------------------------------------| | `GET` | `/pki/cert/:serial` | JSON | | `GET` | `/pki/cert/:serial/raw` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | | `GET` | `/pki/cert/:serial/raw/pem` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | #### Parameters - `serial` `(string: )` - Specifies the serial of the key to read. This is part of the request URL. Valid values for `serial` are: - `` 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. ~> **Note**: As of Vault 1.11.0, these endpoints return the full chain (including this certificate and all parent issuers known to Vault) in the `ca_chain` response, for both the `certificate` and newer `ca_chain` fields. The root certificate is no longer elided. #### Sample Request ```shell-session $ 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 ```json { "data": { "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." } } ``` --- ## 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](#list-issuers) 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. | Method | Path | | :----- | :----------- | | `LIST` | `/pki/keys` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/pki/keys ``` #### Sample Response ```json { "data": { "key_info": { "f9244f54-adc7-4a5c-6b08-6ca3a3325620": { "key_name": "imported-root-key" }, }, "keys": [ "f9244f54-adc7-4a5c-6b08-6ca3a3325620", ] } } ``` ### 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](#managed-keys) will be used. This generated root will sign its own CRL. Authority Access distribution points use the values set via `config/urls`. ~> **Note**: As of Vault 1.11.0, the PKI Secrets Engine now supports multiple issuers under a single mount. Use the management operations in this section to [list](#list-issuers) and [modify issuers](#update-issuer) within this mount. No issuers will be overridden by calling this operation. Deleting individual keys and issuers should be preferred to calling `DELETE /pki/root`, [which deletes everything](#delete-all-issuers-and-keys). | Method | Path | | :----- | :--------------------------------- | | `POST` | `/pki/root/generate/:type` | | `POST` | `/pki/issuers/generate/root/:type` | #### Parameters - `type` `(string: )` - 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](#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`. - `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. - `common_name` `(string: )` - 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: `;:` 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. 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`. ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `ed25519`. - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); 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](https://tools.ietf.org/html/rfc5280#section-4.2.1.10). - `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](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) 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. - `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](#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 ```json { "common_name": "example.com" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/root/generate/internal ``` #### Sample Response ```json { "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](/docs/enterprise/managed-keys); additional details are available [below in a dedicated section](#managed-keys). The parameters below are mostly meant as a helper function; not all possible parameters that can be set in a CSR are supported in this request. No new issuer is yet created by this call; note that a new key may be generated depending on the `type` request parameter. ~> **Note**: In order to complete the intermediate generation, the CSR must be signed and the resulting certificate imported. This may involve working with external systems (such as an external or offline root CA) to transmit the CSR and complete the signing before the signed intermediate certificate is [imported](#import-ca-certificate-and-keys) into this mount. | Method | Path | Private key source (`type`) | | :----- | :--------------------------------- | :-------------------------- | | `POST` | `/pki/intermediate/generate/:type` | specified per request | | `POST` | `/pki/generate/intermediate/:type` | specified per request | | `POST` | `/pki/intermediate/cross-sign` | `existing` | #### Parameters - `type` `(string: )` - 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](#managed-keys). This parameter is part of the request URL. - `common_name` `(string: )` - 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: `;:` 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. 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. ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `ed25519`. ~> **Note**: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures. This includes any managed keys. - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); 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. - `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](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) 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](#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 ```json { "common_name": "www.example.com" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/intermediate/generate/exported ``` ```json { "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). | Method | Path | Allows private keys | Request Parameter | | :----- | :----------------------------- | :------------------ | :---------------- | | `POST` | `/pki/config/ca` | yes | `pem_bundle` | | `POST` | `/pki/issuers/import/bundle` | yes | `pem_bundle` | | `POST` | `/pki/issuers/import/cert` | no | `pem_bundle` | | `POST` | `/pki/intermediate/set-signed` | no | `certificate` | ~> **Note**: endpoints which allow importing private keys _should_ be considered highly privileged and restricted appropriately. Endpoints which allow importing issuers should also be restricted, but note that issuers without keys are unable to issue certificates or CRLs. ~> Note: Vault will deduplicate differently-encoded but same-valued keys and issuers. This means the returned certificate _may_ differ in encoding from the one provided on subsequent re-imports of the same issuer or key. #### Parameters - `pem_bundle` `(string: )` - Specifies the unencrypted private key and certificate, concatenated in PEM format. ~> Note: this parameter is on the `/pki/config/ca` and `/pki/issuers/import/*` paths; it is not on the `/pki/intermediate/set-signed` path. - `certificate` `(string: )` - Specifies the certificates to import, concatenated in PEM format. ~> Note: this parameter is **only** on the `/pki/intermediate/set-signed` path. #### Sample Request ```shell-session $ 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: ```json { "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" } ``` #### Sample Response ```json { "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" } } } ``` ### 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`](#read-issuer-certificate) 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. | Method | Path | | :----- | :------------------------ | | `GET` | `/pki/issuer/:issuer_ref` | #### Parameters - `issuer_ref` `(string: )` - 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 ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/issuer/default ``` #### Sample Response ```text { "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" } } ``` ### 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. | Method | Path | | :------ | :------------------------ | | `POST` | `/pki/issuer/:issuer_ref` | | `PATCH` | `/pki/issuer/:issuer_ref` | ~> **Note** `POST`ing to this endpoint causes Vault to overwrite the previous contents of the issuer, using the provided request data (and any defaults for elided parameters). It does not update only the provided fields.

Since Vault 1.11.0, Vault supports the PATCH operation to this endpoint, using the [JSON patch format](https://datatracker.ietf.org/doc/html/rfc6902) supported by KVv2, allowing update of specific fields. Note that `vault write` uses `POST`. #### Parameters - `issuer_ref` `(string: )` - 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. ~> Note: Not all values result in leaf certificates that can be validated through the entire validity period. It is suggested to use `truncate` for intermediate CAs and `permit` only for root CAs. This is because (root) certificates in browsers' trust stores typically aren't checked for validity, whereas intermediate CA certificates sent in TLS connections are checked for validity at the time of use. This means that a leaf certificate permitted to be issued for longer than the intermediate likely won't continue to validate after the intermediate has expired. - `manual_chain` `([]string: nil)` - Chain of issuer references to build this issuer's computed CAChain field from, when non-empty. ~> Note: the `manual_chain` field is an advanced field useful when automatic chain building isn't desired. The first element _must_ be the present issuer's reference. Subsequent references _should_ validate previous entries, terminating with a root certificate. _Ideally_ a single linear chain would come first (from this issuer to a single root certificate) before any parallel, alternate chains appear. - `usage` `([]string: read-only,issuing-certificates,crl-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. ~> Note: The `usage` field allows for a soft-delete capability on the issuer, or to prevent use of the issuer prior to it being enabled. For example, as issuance is rotated to a new issuer, the old issuer could be marked `usage=read-only,crl-signing`, allowing existing certificates to be revoked (and the CRL updated), but preventing new certificate issuance. After all certificates issued under this certificate have expired, this certificate could be marked `usage=read-only`, freezing the CRL. Finally, after a grace period, the issuer could be deleted. #### Sample Payload ```json { "issuer_name": "root-x1" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/issuer/default ``` #### Sample Response ```text { "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" } } ``` ### Delete Issuer This endpoint deletes the specified issuer. A warning is emitted and the default is cleared if this issuer is the default issuer. ~> **Note**: If an issuer is incorrectly deleted, but its key material remains, it is possible to re-import just the issuer certificate. The `issuer_id` will change, but the name can be re-assigned to the new issuer. | Method | Path | | :------- | :------------------------ | | `DELETE` | `/pki/issuer/:issuer_ref` | #### Sample Request ```shell-session $ 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. ~> **Note**: This API does not protect against importing keys using insecure combinations of algorithm and key length. | Method | Path | |:-------|:-------------------| | `POST` | `/pki/keys/import` | #### Parameters - `pem_bundle` `(string: )` - 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 ```json { "key_name": "my-imported-key", "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/keys/import ``` #### Sample Response ```text { "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. ~> **Note**: Vault does not allow reading the value of the private key after it has been created. | Method | Path | | :----- | :------------------ | | `GET` | `/pki/key/:key_ref` | #### Parameters - `key_ref` `(string: )` - 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 ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/key/default ``` #### Sample Response ```text { "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. | Method | Path | | :----- | :------------------ | | `POST` | `/pki/key/:key_ref` | ~> **Note** `POST`ing to this endpoint causes Vault to overwrite the previous contents of the key, using the provided request data (and any defaults for elided parameters). It does not update only the provided fields. #### Parameters - `key_ref` `(string: )` - 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 ```json { "key_name": "key-root-x1" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/key/default ``` #### Sample Response ```text { "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. ~> **Note**: Because Vault does not allow exporting the private key after it is initially generated, deletion of keys is a sensitive operation. Additionally, one key may be used by more than one issuer. As a result, Vault prohibits deletion of keys until **all** issuers using this key have also been deleted. If these issuers are still necessary for chain building, re-import them without the corresponding keys after the key has been deleted or use the soft-delete feature of issuers. | Method | Path | | :------- | :------------------ | | `DELETE` | `/pki/key/:key_ref` | #### Sample Request ```shell-session $ 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._ | Method | Path | | :------- | :---------- | | `DELETE` | `/pki/root` | #### Sample Request ```shell-session $ 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](#list-roles) 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. | Method | Path | | :------ | :----------------- | | `POST` | `/pki/roles/:name` | | `PATCH` | `/pki/roles/:name` | ~> **Note** `POST`ing to this endpoint when the role already exists causes Vault to overwrite the contents of the role, using the provided request data (and any defaults for elided parameters). It does not update only the provided fields.

Since Vault 1.11.0, Vault supports the PATCH operation to this endpoint, using the [JSON patch format](https://datatracker.ietf.org/doc/html/rfc6902) supported by KVv2, allowing update of specific fields. Note that `vault write` uses `POST`. #### Parameters - `name` `(string: )` - 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. ~> Note: This parameter is stored as-is; if the reference is to a name, it is **not** resolve to an identifier. Deletion of issuers (or updating their names) **may** result in issuance failing or using an unexpected issuer. ~> **Note**: existing roles from previous Vault versions are migrated to use the `issuer_ref=default`. - `ttl` `(string: "")` - Specifies the Time To Live value to be used for the validity period of the requested certificate, provided as a string duration with time suffix. Hour is the largest suffix. The value specified is strictly used for future validity. If not set, uses the system default value or the value 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. ~> **Note**: This strictly applies to `localhost` and `localdomain` when this option is enabled. Additionally, even if this option is disabled, if either name is included in `allowed_domains`, the match rules for that option could permit issuance of a certificate for `localhost`. - `allowed_domains` `(list: [])` - Specifies the domains this role is allowed to issue certificates for. This is used with 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. ~> **Note**: The three options `allow_bare_domains`, `allow_subdomains`, and `allow_glob_domains` are each independent of each other. That is, at least one type of allowed matching must describe the relationship between the `allowed_domains` list and the names on the issued certificate. For example, given `allowed_domain=foo.*.example.com` and `allow_subdomains=true` and `allow_glob_domains=true`, a request for `bar.foo.baz.example.com` won't be permitted, even though it `foo.baz.example.com` matches the glob `foo.*.example.com` and `bar` is a subdomain of that. - `allowed_domains_template` `(bool: false)` - When set, `allowed_domains` may contain templates, as with [ACL Path Templating](/docs/concepts/policies). 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. ~> **Note**: These globs behave like shell-style globs and can match across multiple domain parts. For example, `allowed_domains=*.example.com` with `allow_glob_domains` enabled will match not only `foo.example.com` but also `baz.bar.foo.example.com`. ~> **Warning**: Glob patterns will match wildcard domains and permit their issuance unless otherwise restricted by `allow_wildcard_certificates`. For instance, with `allowed_domains=*.*.example.com` and both `allow_glob_domains` and `allow_wildcard_certificates` enabled, we will permit the issuance of a wildcard certificate for `*.foo.example.com`. - `allow_wildcard_certificates` `(bool: true)` - Allows the issuance of certificates with [RFC 6125](https://tools.ietf.org/html/rfc6125) 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](/docs/concepts/policies). 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: `;:`, 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](https://datatracker.ietf.org/doc/html/rfc5280#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](https://datatracker.ietf.org/doc/html/rfc5280#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](https://datatracker.ietf.org/doc/html/rfc5280#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](https://datatracker.ietf.org/doc/html/rfc5280#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 >1024 bits for RSA keys). ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `ed25519`. - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); 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`. - `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 key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves). ~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the `signature_bits` value; only RSA issuers will change signature types based on this parameter. - `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](https://datatracker.ietf.org/doc/html/rfc5280#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](https://datatracker.ietf.org/doc/html/rfc5280#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 ` 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, so this option is recommended only for certificates that are non-sensitive, or extremely short-lived. 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`. #### Sample Payload ```json { "allowed_domains": ["example.com"], "allow_subdomains": true } ``` #### Sample Request ```shell-session $ 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](#read-role) 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. | Method | Path | | :------- | :----------------- | | `DELETE` | `/pki/roles/:name` | #### Parameters - `name` `(string: )` - Specifies the name of the role to delete. This is part of the request URL. #### Sample Request ```shell-session $ 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. | Method | Path | | :----- | :----------------- | | `GET` | `/pki/config/urls` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/config/urls ``` #### Sample Response ```json { "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "issuing_certificates": ["", ""], "crl_distribution_points": ["", ""], "ocsp_servers": ["", ""] }, "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. | Method | Path | | :----- | :----------------- | | `POST` | `/pki/config/urls` | #### Parameters - `issuing_certificates` `(array: 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](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) for information about the Authority Information Access field. - `crl_distribution_points` `(array: 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](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.13) for information about the CRL Distribution Points field. ~> Note: When multiple Performance Replication clusters are enabled, each cluster will have its own CRL. Additionally, when multiple issuers are in use under a single mount, each issuer will also have its own CRL distribution point. These separate CRLs should either be aggregated into a single CRL (externally; as Vault does not support this functionality) or multiple `crl_distribution_points` should be specified here, pointing to each cluster and issuer. - `ocsp_servers` `(array: 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](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) for information about the Authority Information Access field. #### Sample Payload ```json { "ocsp_servers": ["https://..."] } ``` #### Sample Request ```shell-session $ 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. | Method | Path | | :----- | :-------------------- | | `GET` | `/pki/config/issuers` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/config/issuers ``` #### Sample Response ```json { "data": { "default": "3dc79a5a-7a6c-70e2-1123-94b88557ba12" } } ``` ### Set Issuers Configuration This endpoint allows setting the value of the default issuer. | Method | Path | | :----- | :-------------------- | | `POST` | `/pki/config/issuers` | #### Parameters - `default` `(string: "")` - Specifies the default issuer (by reference; either a name or an ID). #### Sample Payload ```json { "default": "root-x1" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/config/issuers ``` #### Sample Response ```json { "data": { "default": "3dc79a5a-7a6c-70e2-1123-94b88557ba12" } } ``` ### Read Keys Configuration This endpoint allows getting the value of the default key. | Method | Path | | :----- | :----------------- | | `GET` | `/pki/config/keys` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/config/keys ``` #### Sample Response ```json { "data": { "default": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf" } } ``` ### Set Keys Configuration This endpoint allows setting the value of the default key. | Method | Path | | :----- | :----------------- | | `POST` | `/pki/config/keys` | #### Parameters - `default` `(string: "")` - Specifies the default key (by reference; either a name or an ID). #### Sample Payload ```json { "default": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/config/keys ``` #### Sample Response ```json { "data": { "default": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf" } } ``` ### Read CRL Configuration This endpoint allows getting the duration for which the generated CRL should be marked valid. No CRL configuration will be returned until the configuration is set, but the CRL will still default to enabled with 72h expiration. | Method | Path | | :----- | :---------------- | | `GET` | `/pki/config/crl` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/config/crl ``` #### Sample Response ```json { "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "disable": false, "expiry": "72h" }, "auth": null } ``` ### Set CRL Configuration This endpoint allows setting the duration for which the generated CRL should be marked valid. If the CRL is disabled, it will return a signed but zero-length CRL for any request. If enabled, it will re-build the CRL. ~> **Note**: This parameter is global, across all clusters and issuers. Use the per-issuer `usage` field to disable CRL building for a specific issuer, while leaving the global CRL building enabled. ~> Note: Disabling the CRL does not affect whether revoked certificates are stored internally. Certificates that have been revoked when a role's certificate storage is enabled will continue to be marked and stored as revoked until `tidy` has been run with the desired safety buffer. Re-enabling CRL generation will then result in all such certificates becoming a part of the CRL. | Method | Path | | :----- | :---------------- | | `POST` | `/pki/config/crl` | #### Parameters - `expiry` `(string: "72h")` - The amount of time the generated CRL should be valid. - `disable` `(bool: false)` - Disables or enables CRL building. #### Sample Payload ```json { "expiry": "48h" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/config/crl ``` ### Rotate CRLs This endpoint forces a rotation of all issuers' CRLs. This can be used by administrators to cut the size of the CRL if it contains a number of certificates that have now expired, but has not been rotated due to no further certificates being revoked. If no certificates have been revoked, but the CRL has expired or is close to expiring, administrators **must** hit this endpoint to manually rotate the CRL. This rotates all CRLs on the present cluster, and **must** be called on every cluster. ~> **Note**: Mirroring the behavior of earlier Vault versions, we add certificates revoked by an unknown issuer to the default issuer's CRL. To fully purge old revoked, unexpired certificates, it is not sufficient to delete their issuer and is instead necessary to **remove** the mount completely. | Method | Path | | :----- | :---------------- | | `GET` | `/pki/crl/rotate` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/pki/crl/rotate ``` #### Sample Response ```json { "data": { "success": true } } ``` ### Tidy This endpoint allows tidying up the storage backend and/or CRL by removing certificates that have expired and are past a certain buffer period beyond their expiration time. | Method | Path | | :----- | :---------- | | `POST` | `/pki/tidy` | #### Parameters - `tidy_cert_store` `(bool: false)` Specifies whether to tidy up the certificate store. - `tidy_revoked_certs` `(bool: false)` Set to true to remove all invalid and expired certificates from storage. A revoked storage entry is considered invalid if the entry is empty, or the value within the entry is empty. If a certificate is removed due to expiry, the entry will also be removed from the CRL, and the CRL will be rotated. - `safety_buffer` `(string: "")` Specifies A duration (given as an integer number of seconds or a string; defaults to `72h`) used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep certificates from being removed from the CRL that, due to clock skew, might still be considered valid on other hosts. For a certificate to be expunged, the time must be after the expiration time of the certificate (according to the local clock) plus the duration of `safety_buffer`. #### Sample Payload ```json { "safety_buffer": "24h" } ``` #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/pki/tidy ``` ### Tidy Status This is a read only endpoint that returns information about the current tidy operation, or the most recent if none are currently running. The result includes the following fields: * `safety_buffer`: the value of this parameter when initiating the tidy operation * `tidy_cert_store`: the value of this parameter when initiating the tidy operation * `tidy_revoked_certs`: the value of this parameter when initiating the tidy operation * `state`: one of *Inactive*, *Running*, *Finished*, *Error* * `error`: the error message, if the operation ran into an error * `time_started`: the time the operation started * `time_finished`: the time the operation finished * `message`: One of *Tidying certificate store: checking entry N of TOTAL* or *Tidying revoked certificates: checking certificate N of TOTAL* * `cert_store_deleted_count`: The number of certificate storage entries deleted * `revoked_cert_deleted_count`: The number of revoked certificate entries deleted | Method | Path | | :----- | :----------------- | | `GET` | `/pki/tidy-status` | #### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request GET \ http://127.0.0.1:8200/v1/pki/tidy-status ``` #### Sample Response ```json "data": { "safety_buffer": 60, "tidy_cert_store": true, "tidy_revoked_certs": true, "error": null, "message": "Tidying certificate store: checking entry 234 of 488", "revoked_cert_deleted_count": 0, "cert_store_deleted_count": 2, "state": "Running", "time_started": "2021-10-20T14:52:13.510161-04:00", "time_finished": null }, ``` --- ## Cluster Scalability See [PKI Cluster Scalability](/docs/secrets/pki/considerations#cluster-scalability) in the considerations page. ## Managed Keys ~> Note: Managed keys are an Enterprise only feature. The [Generate Root](#generate-root) and [Generate Intermediate](#generate-intermediate) API calls can leverage the Managed Keys feature, delegating operations that require private key material to an external system. To leverage a Managed Key, assuming it has already been configured, set the type parameter to `kms` within either, [Generate Root](#generate-root) or [Generate Intermediate](#generate-intermediate) APIs, and one of either `managed_key_name` or `managed_key_id` parameters specifying a Managed Key to use. As with the `internal` type for those APIs, if the type parameter is set to `kms`, there is no way to read/fetch the private key. The API call will fail if the specified Managed Key is not properly configured or arguments detailing private key attributes are specified such as `key_type` or `key_bits`. Once either of the certificate APIs have successfully executed, all other PKI operations behave the same, with no other special configuration or parameters required. ## Vault CLI with DER/PEM responses The Vault CLI can only display JSON responses. For APIs that return non-JSON formatted data such as DER and PEM formats, `vault read` will fail and another client such as curl must be used.