diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki/index.mdx similarity index 91% rename from website/content/api-docs/secret/pki.mdx rename to website/content/api-docs/secret/pki/index.mdx index 1d3c48cee5..b196456b30 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki/index.mdx @@ -19,13 +19,6 @@ update your API calls accordingly. ## Table of contents - [Notice About New Multi-Issuer Functionality](#notice-about-new-multi-issuer-functionality) -- [ACME Certificate Issuance](#acme-certificate-issuance) - - [ACME Directories](#acme-directories) - - [Get ACME EAB Binding Token](#get-acme-eab-binding-token) - - [List Unused ACME EAB Binding Tokens](#list-unused-acme-eab-binding-tokens) - - [Delete Unused ACME EAB Binding Tokens](#delete-unused-acme-eab-binding-tokens) - - [Get ACME Configuration](#get-acme-configuration) - - [Set ACME Configuration](#set-acme-configuration) - [Issuing Certificates](#issuing-certificates) - [List Roles](#list-roles) - [Read Role](#read-role) @@ -93,10 +86,7 @@ update your API calls accordingly. - [Set Automatic Tidy Configuration](#set-automatic-tidy-configuration) - [Tidy Status](#tidy-status) - [Cancel Tidy](#cancel-tidy) -- [EST - Certificate Issuance ](#est-certificate-issuance) - - [EST Protocol Paths ](#est-protocol-paths) - - [Read EST Configuration ](#read-est-configuration) - - [Set EST Configuration ](#set-est-configuration) +- [Certificate Issuance Protocols](/vault/api-docs/secret/pki/issuance) - [Cluster Scalability](#cluster-scalability) - [Managed Key](#managed-keys) (Enterprise Only) - [Vault CLI with DER/PEM responses](#vault-cli-with-der-pem-responses) @@ -123,351 +113,6 @@ to mix different types of CAs (roots and intermediates). current issuing certificate on migration from an older Vault version (Vault < 1.11.0). -## ACME certificate issuance - -Starting with Vault 1.14, Vault supports the [ACME certificate lifecycle -management protocol](https://datatracker.ietf.org/doc/html/rfc8555) for issuing -and renewing leaf server certificates. - -In order to use ACME, a [cluster path](#set-cluster-configuration) must be -set and ACME must be [enabled in its configuration](#set-acme-configuration) -with the [required headers](#acme-required-headers) enabled on the mount -tuning. - -Using ACME with a role requires `no_store=false` to be set on the role; this -allows the certificate to be stored and later fetched through the ACME -protocol. - -### ACME directories - -Vault PKI supports the following ACME directories, providing different -restrictions around usage (defaults, a specific issuer and/or a specific -role). To interact with these directories, specify the directory URL in -an ACME client. For example, with the EFF's [CertBot](https://certbot.eff.org/): - -``` -$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory ... -``` - -These endpoints are unauthenticated from a Vault authentication model, but -internally authenticated via the ACME protocol. - -| Method | Path | Default Directory Policy | Issuer | Role | -|:-------|:-------------------------------------------------------------------|:---------------------------|:----------------------|:--------------| -| `ACME` | `/pki/acme/directory` | `sign-verbatim` | `default` | Sign-Verbatim | -| `ACME` | `/pki/acme/directory` | `role:role_ref` | Specified by the role | `:role_ref` | -| `ACME` | `/pki/acme/directory` | `external-policy(:policy)` | Specified by CIEPS | CIEPS | -| `ACME` | `/pki/issuer/:issuer_ref/acme/directory` | `sign-verbatim` | `:issuer_ref` | Sign-Verbatim | -| `ACME` | `/pki/issuer/:issuer_ref/acme/directory` | `role:role_ref` | `:issuer_ref` | `:role_ref` | -| `ACME` | `/pki/roles/:role/acme/directory` | (any) | Specified by the role | `:role` | -| `ACME` | `/pki/issuer/:issuer_ref/roles/:role/acme/directory` | (any) | `:issuer_ref` | `:role` | -| `ACME` | `/pki/external-policy(/:policy)/acme/directory` | (any) | Specified by CIEPS | CIEPS | -| `ACME` | `/pki/issuer/:issuer_ref/external-policy(/:policy)/acme/directory` | (any) | Specified by CIEPS | CIEPS | - -When a role is not explicitly specified, behavior is specified by the -`default_directory_policy` in the [ACME configuration](#set-acme-configuration). -These directories can also be forbidden by setting that policy as `forbid`. If -the policy is `sign-verbatim` then _any_ identifier for which the client can -prove ownership of will be issued for. This is similar to using the -[Sign Verbatim](#sign-verbatim) endpoint, but with additional verification -that the client has proven ownership (within the ACME protocol) of the -requested certificate identifiers. When `external-policy` is specified as the -default value, the Certificate Issuance External -Policy Service (CIEPS) is used for -validating and templating the certificate instead of a role; ACME's challenge -validation is still enforced. An optional policy name can be specified by using -`external-policy:policy`. Roles are not used when CIEPS is used. - -#### ACME challenge types - -Vault supports the following ACME challenge types presently: - - - `http-01`, supporting both `dns` and `ip` identifiers. - - `dns-01`, supporting `dns` identifiers including wildcards. - - `tls-alpn-01`, supporting only non-wildcard `dns` identifiers. - -A custom DNS resolver used by the server for looking up DNS names for use -with both mechanisms can be added via the [ACME configuration](#set-acme-configuration). - -#### ACME external account bindings - -ACME External Account Binding (EAB) Policy can enforce that clients need to -have a valid external account binding to Vault. Before registering a new account, -an authenticated Vault client will need to [fetch a new EAB -token](#get-acme-eab-binding-token). This returns two values: a key identifier -and an HMAC key used by the ACME client to authenticate with EAB. For example: - -``` -$ vault write -f /pki/acme/new-eab -$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory \ - --eab-kid --eab-hmac-key -``` - -With or without EAB, requests from the ACME client are not authenticated using -traditional Vault authentication, but are instead authenticated through the -ACME protocol. With EAB however, a Vault authenticated client will have to -fetch an EAB token and pass it to the ACME client for use on the initial -registration: this binds the ACME client's registration to an authenticated -Vault endpoint, but not further to the client's entity or other information. - -~> Note: Enabling EAB is strongly recommended for public-facing Vault - deployments. Use of the `VAULT_DISABLE_PUBLIC_ACME` environment variable - can be used to enforce all ACME instances have EAB enabled. - -#### ACME accounts - -ACME Accounts are created specific to a particular directory and are not -portable across Performance Secondary clusters. - -#### ACME required headers - -ACME requires the following response headers (`allowed_response_headers`) -to be specified by [mount tuning](/vault/api-docs/system/mounts#tune-mount-configuration): - - - `Replay-Nonce` - - `Link` - - `Location` - -On an existing mount, these can be specified by running the following command: - -``` -$ vault secrets tune -allowed-response-headers=Location -allowed-response-headers=Replay-Nonce \ - -allowed-response-headers=Link \ - pki/ -``` - -### Get ACME EAB binding token - -This endpoint returns a new ACME binding token. The `id` response field can -be used as the key identifier and the `key` response field be used as the -EAB HMAC key in the ACME Client. - -Each call to this endpoint will generate and return a new EAB binding token -that is linked to the specific ACME directory it resides under. EAB tokens -are not usable across different ACME directories. - -| Method | Path | -|:-------|:---------------------------------------------------| -| `POST` | `/pki/acme/new-eab` | -| `POST` | `/pki/issuer/:issuer_ref/acme/new-eab` | -| `POST` | `/pki/roles/:role/acme/new-eab` | -| `POST` | `/pki/issuer/:issuer_ref/roles/:role/acme/new-eab` | - -#### Parameters - -No parameters. - -#### Sample request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - http://127.0.0.1:8200/v1/pki/acme/new-eab -``` - -#### Sample response - -``` -{ - "data": { - "created_on": "2023-05-24T14:33:00-04:00", - "id": "bc8088d9-3816-5177-ae8e-d8393265f7dd", - "key_type": "hs", - "acme_directory": "acme/directory", - "key": "MHcCAQE... additional data elided ...", - } -} -``` - -### List unused ACME EAB binding tokens - -This endpoint returns a list of all unused ACME binding tokens; once used, -they will be removed from this list. - -| Method | Path | -| :----- | :--------- | -| `LIST` | `/pki/eab` | - -#### Sample request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request LIST \ - http://127.0.0.1:8200/v1/pki/eab -``` - -#### Sample response - -``` -{ - "data": { - "key_info": { - "bc8088d9-3816-5177-ae8e-d8393265f7dd": { - "created_on": "2023-05-24T14:33:00-04:00", - "key_type": "hs", - "acme_directory": "acme/directory" - } - }, - "keys": [ - "bc8088d9-3816-5177-ae8e-d8393265f7dd" - ] - } -} -``` - -### Delete unused ACME EAB binding tokens - -This endpoint allows the deletion of an unused ACME binding token. - -| Method | Path | -| :------- | :----------------- | -| `DELETE` | `/pki/eab/:key_id` | - -#### Parameters - - - `key_id` `(string: )` - The id of the EAB binding token to - delete. This is part of the request URL. - -#### Sample request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request DELETE \ - http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd -``` - -### Get ACME configuration - -This endpoint allows reading of the current ACME server configuration used by -this mount. - -| Method | Path | -| :----- | :----------------- | -| `GET` | `/pki/config/acme` | - -#### Sample request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - http://127.0.0.1:8200/v1/pki/config/acme -``` - -#### Sample response - -``` -{ - "data": { - "allowed_issuers": [ - "*" - ], - "allowed_roles": [ - "*" - ], - "default_directory_policy": "sign-verbatim", - "dns_resolver": "", - "eab_policy": "not-required", - "enabled": true, - "max_ttl": 776000 - }, -} -``` - -### Set ACME configuration - -This endpoint allows setting the ACME server configuration used by this -mount. - -| Method | Path | -| :----- | :----------------- | -| `POST` | `/pki/config/acme` | - -#### Parameters - - - `allowed_issuers` `(list: ["*"])` - Specifies a list issuers allowed to - issue certificates via explicit ACME paths. If an allowed role specifies - an issuer outside this list, it will be allowed. The default value `*` - allows every issuer within the mount. - - - `allow_role_ext_key_usage` `(bool: false)` - whether the ExtKeyUsage field - from a role is used, defaults to false meaning that certificate will be - signed with ServerAuth. - - - `allowed_roles` `(list: ["*"])` - Specifies a list of roles allowed to - issue certificates via explicit ACME paths. The default value `*` allows - every role within the mount to be used. If the `default_directory_policy` - specifies a role, it must be allowed under this configuration. - - - `default_directory_policy` `(string: "sign-verbatim")` - Specifies the - behavior of the default ACME directory. Can be `forbid`, `sign-verbatim` - or a role given by `role:`. If a role is used, it must be - present in `allowed_roles`. - - - `dns_resolver` `(string: "")` - An optional overriding DNS resolver to - use for challenge verification lookups. When not specified, the default - system resolver will be used. This allows domains on peered networks with - an accessible DNS resolver to be validated. - - - `eab_policy` `(string: "not-required")` - Specified policy to enforce - around [External Account Bindings (EABs)](#acme-external-account-bindings). - The allowed values are: - - - `not-required`, where EABs are not enforced but are validated if - specified. - - - `new-account-required`, where new accounts are required to have EAB - but existing accounts can still be used. - - - `always-required`, where all accounts regardless of age are required - to have EABs set. - - - `enabled` `(bool: false)` - Whether ACME is enabled on this mount. When - ACME is disabled, all requests to ACME directory URLs will return 404. - - - `max_ttl` `(string: "")` - Specifies the maximum Time To Live provided as a - string duration with time suffix. Hour is the largest suffix. If not set, - defaults to the previous hard-coded behavior of 90 days (2160 hours). - -#### Sample payload - -``` -{ - "enabled": true -} -``` - -#### Sample request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/pki/config/acme -``` - -#### Sample response - -``` -{ - "data": { - "allowed_issuers": [ - "*" - ], - "allowed_roles": [ - "*" - ], - "default_directory_policy": "sign-verbatim", - "dns_resolver": "", - "eab_policy": "not-required", - "enabled": true - } -} -``` - ## Issuing certificates The following API endpoints allow users or operators to request certificates @@ -4999,166 +4644,6 @@ $ curl \ "time_finished": null }, ``` - -## EST Certificate issuance - -@include 'alerts/beta.mdx' - -Within Vault Enterprise, support can be enabled for the -[EST (Enrollment over Secure Transport) protocol](https://datatracker.ietf.org/doc/html/rfc7030) -for issuing and renewing leaf certificates. - -### EST Protocol Paths - -These are the EST protocol API paths currently supported from Vault's authentication -point of view. Note that the `cacerts` endpoint is unauthenticated. - -@include 'pki-est-default-policy.mdx' - -### Read EST Configuration - -@include 'alerts/beta.mdx' - -This endpoint fetches the current EST configuration. - -| Method | Path | -| :----- |:-----------------| -| `GET` | `/pki/config/est` | - -#### Sample request - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - http://127.0.0.1:8200/v1/pki/config/est -``` - -#### Sample response - -```json -{ - "data": { - "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"], - "authenticators": { - "cert": { - "accessor": "auth_cert_7fe0c1cc", - "cert_role": "est-ca" - }, - "userpass": { - "accessor": "auth_userpass_2b333949" - } - }, - "default_mount": true, - "default_path_policy": "sign-verbatim", - "enable_sentinel_parsing": true, - "enabled": true, - "label_to_path_policy": { - "test-label": "role:est-clients" - }, - "last_updated": "2024-01-31T10:45:22-05:00" - } -} -``` - -### Set EST Configuration - -@include 'alerts/beta.mdx' - -This endpoint will update EST related configuration, returning the -updated values as a response along with an updated `last_updated` field. - -| Method | Path | -|:-------|:------------------| -| `POST` | `/pki/config/est` | - -#### Parameters - -- `enabled` `(bool: false)` - Specifies whether EST is enabled or not. - -- `default_mount` `(bool: false)` - Should this mount register the default .well-known/est URL path. - Only a single mount can enable this across a Vault cluster - -- `default_path_policy` `(string: "")` - Required to be set if `default_mount` is enabled. Specifies the - behavior for requests using the default EST label. Can be `sign-verbatim` or a role given by `role:`. - -- `label_to_path_policy` `(map[string]string: "")` - Configures a pairing of an EST label with the redirected - behavior for requests hitting that role. The path policy can be `sign-verbatim` or a role given by `role:`. - Labels must be unique across Vault cluster, and will register `.well-known/est/