scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-10-29 09:42:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document CMPv2 (#27915)

Browse Source 
* CMPv2 Documentation, and restructuring of Issuance Protocols into its own section for PKI.

* title

* CMPv2 API

* Add default path policy

* Update website/content/docs/secrets/pki/cmpv2.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/docs/secrets/pki/cmpv2.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/docs/secrets/pki/cmpv2.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/docs/secrets/pki/cmpv2.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* respond to some PR feedback

* pr feedback

* Fix nav and add key_usage

* Update website/content/docs/secrets/pki/cmpv2.mdx

Co-authored-by: Steven Clark <steven.clark@hashicorp.com>

* Update website/content/docs/secrets/pki/cmpv2.mdx

Co-authored-by: Steven Clark <steven.clark@hashicorp.com>

* Update website/content/api-docs/secret/pki/issuance.mdx

Co-authored-by: Steven Clark <steven.clark@hashicorp.com>

* Docs fixes

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
Co-authored-by: Steven Clark <steven.clark@hashicorp.com>
This commit is contained in:
Scott Miller
2024-09-04 17:24:50 -05:00
committed by GitHub
parent f6701b3672
commit 047ec756c0
6 changed files with 843 additions and 527 deletions
Download Patch File Download Diff File Expand all files Collapse all files

517
website/content/api-docs/secret/pki.mdx → website/content/api-docs/secret/pki/index.mdx
View File

@@ -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 <EnterpriseAlert inline="true" />](#est-certificate-issuance)
- [EST Protocol Paths <EnterpriseAlert inline="true" />](#est-protocol-paths)
- [Read EST Configuration <EnterpriseAlert inline="true" />](#read-est-configuration)
- [Set EST Configuration <EnterpriseAlert inline="true" />](#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)<EnterpriseAlert inline="true" /> 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 <id> --eab-hmac-key <hmac-key>
```
With or without EAB, requests from the ACME client are not authenticated using
traditional Vault authentication, but are instead authenticated through the
ACME protocol. With EAB however, a Vault authenticated client will have to
fetch an EAB token and pass it to the ACME client for use on the initial
registration: this binds the ACME client's registration to an authenticated
Vault endpoint, but not further to the client's entity or other information.
~> 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: <required>)` - The id of the EAB binding token to
delete. This is part of the request URL.
#### Sample request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd
```
### Get ACME configuration
This endpoint allows reading of the current ACME server configuration used by
this mount.
| 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:<role_name>`. If a role is used, it must be
present in `allowed_roles`.
- `dns_resolver` `(string: "")` - An optional overriding DNS resolver to
use for challenge verification lookups. When not specified, the default
system resolver will be used. This allows domains on peered networks with
an accessible DNS resolver to be validated.
- `eab_policy` `(string: "not-required")` - Specified policy to enforce
around [External Account Bindings (EABs)](#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 <EnterpriseAlert inline="true" />
@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 <EnterpriseAlert inline="true" />
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 <EnterpriseAlert inline="true" />
@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 <EnterpriseAlert inline="true" />
@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:<role_name>`.
- `label_to_path_policy` `(map[string]string: "")` - Configures a pairing of an EST label with the redirected
behavior for requests hitting that role. The path policy can be `sign-verbatim` or a role given by `role:<role_name>`.
Labels must be unique across Vault cluster, and will register `.well-known/est/<label>` URL paths.
- `authenticators` `(map[string]map[string]string: "")` - Specifies the mount accessors EST should delegate authentication
requests. Map keys can be either `cert` or `userpass`, with associated maps containing the key `accessor` with a value
containing the auth mount's accessor. For the `cert` type, an optional key `cert_role` parameter is supported which
will be passed as the [name](/vault/api-docs/auth/cert#name-6) parameter during certificate authentication attempts.
- `enable_sentinel_parsing` `(bool: false)` - Parse out fields from the provided CSR making them available for
Sentinel policies.
- `audit_fields` `(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])` - Fields parsed from the CSR that
appear in the audit and can be used by sentinel policies. Allowed values are `csr`, `common_name`, `alt_names`,
`ip_sans`, `uri_sans`, `other_sans`, `signature_bits`, `exclude_cn_from_sans`, `ou`, `organization`, `country`,
`locality`, `province`, `street_address`, `postal_code`, `serial_number`, `use_pss`, `key_type`, `key_bits`,
`add_basic_constraints`
#### Sample Payload
```json
{
"enabled": true,
"default_mount": true,
"label_to_path_policy": {
"test-label": "role:est-clients",
"sign-all": "sign-verbatim"
},
"authenticators": {
"cert": {
"accessor": "auth_cert_0f1df449",
"cert_role": "cert1"
},
"userpass": {
"accessor": "auth_userpass_b2b08fac"
}
},
"enable_sentinel_parsing": true,
"audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}
```
#### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/pki/config/est
```
#### Sample response
```json
{
"data": {
"authenticators": {
"cert": {
"accessor": "auth_cert_0f1df449",
"cert_role": "cert1"
},
"userpass": {
"accessor": "auth_userpass_b2b08fac"
}
},
"default_mount": true,
"default_path_policy": "sign-verbatim",
"enabled": true,
"label_to_path_policy": {
"sign-all": "sign-verbatim",
"test-label": "role:est-clients"
},
"last_updated": "2024-02-02T10:49:20-05:00"
}
}
```
---
## Cluster scalability

664
website/content/api-docs/secret/pki/issuance.mdx Normal file
View File

@@ -0,0 +1,664 @@
---
layout: api
page_title: PKI - Secrets Engines - Issuance Protocols
description: This is the API documentation for the issuance protocol support in Vault PKI.
---
# Standard Issuance Protocols (API)
- [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)
- [EST - Certificate Issuance <EnterpriseAlert inline="true" />](#est-certificate-issuance)
- [EST Protocol Paths <EnterpriseAlert inline="true" />](#est-protocol-paths)
- [Read EST Configuration <EnterpriseAlert inline="true" />](#read-est-configuration)
- [Set EST Configuration <EnterpriseAlert inline="true" />](#set-est-configuration)
- [CMPv2 - Certificate Management Protocol (v2) <EnterpriseAlert inline="true"/>](#cmpv2-certificate-issuance)
- [CMPv2 Protocol Paths <EnterpriseAlert inline="true" />](#cmpv2-protocol-paths)
- [Read CMPv2 Configuration <EnterpriseAlert inline="true" />](#read-cmpv2-configuration)
- [Set CMPv2 Configuration <EnterpriseAlert inline="true" />](#set-cmpv2-configuration)
## 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)<EnterpriseAlert inline="true" /> 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 <id> --eab-hmac-key <hmac-key>
```
With or without EAB, requests from the ACME client are not authenticated using
traditional Vault authentication, but are instead authenticated through the
ACME protocol. With EAB however, a Vault authenticated client will have to
fetch an EAB token and pass it to the ACME client for use on the initial
registration: this binds the ACME client's registration to an authenticated
Vault endpoint, but not further to the client's entity or other information.
~> 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: <required>)` - The id of the EAB binding token to
delete. This is part of the request URL.
#### Sample request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd
```
### Get ACME configuration
This endpoint allows reading of the current ACME server configuration used by
this mount.
| 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:<role_name>`. If a role is used, it must be
present in `allowed_roles`.
- `dns_resolver` `(string: "")` - An optional overriding DNS resolver to
use for challenge verification lookups. When not specified, the default
system resolver will be used. This allows domains on peered networks with
an accessible DNS resolver to be validated.
- `eab_policy` `(string: "not-required")` - Specified policy to enforce
around [External Account Bindings (EABs)](#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
}
}
```
## EST Certificate issuance <EnterpriseAlert inline="true" />
@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 <EnterpriseAlert inline="true" />
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 <EnterpriseAlert inline="true" />
@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 <EnterpriseAlert inline="true" />
@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:<role_name>`.
- `label_to_path_policy` `(map[string]string: "")` - Configures a pairing of an EST label with the redirected
behavior for requests hitting that role. The path policy can be `sign-verbatim` or a role given by `role:<role_name>`.
Labels must be unique across Vault cluster, and will register `.well-known/est/<label>` URL paths.
- `authenticators` `(map[string]map[string]string: "")` - Specifies the mount accessors EST should delegate authentication
requests. Map keys can be either `cert` or `userpass`, with associated maps containing the key `accessor` with a value
containing the auth mount's accessor. For the `cert` type, an optional key `cert_role` parameter is supported which
will be passed as the [name](/vault/api-docs/auth/cert#name-6) parameter during certificate authentication attempts.
- `enable_sentinel_parsing` `(bool: false)` - Parse out fields from the provided CSR making them available for
Sentinel policies.
- `audit_fields` `(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])` - Fields parsed from the CSR that
appear in the audit and can be used by sentinel policies. Allowed values are `csr`, `common_name`, `alt_names`,
`ip_sans`, `uri_sans`, `other_sans`, `signature_bits`, `exclude_cn_from_sans`, `ou`, `organization`, `country`,
`locality`, `province`, `street_address`, `postal_code`, `serial_number`, `use_pss`, `key_type`, `key_bits`,
`add_basic_constraints`
#### Sample Payload
```json
{
"enabled": true,
"default_mount": true,
"label_to_path_policy": {
"test-label": "role:est-clients",
"sign-all": "sign-verbatim"
},
"authenticators": {
"cert": {
"accessor": "auth_cert_0f1df449",
"cert_role": "cert1"
},
"userpass": {
"accessor": "auth_userpass_b2b08fac"
}
},
"enable_sentinel_parsing": true,
"audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}
```
#### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/pki/config/est
```
#### Sample response
```json
{
"data": {
"authenticators": {
"cert": {
"accessor": "auth_cert_0f1df449",
"cert_role": "cert1"
},
"userpass": {
"accessor": "auth_userpass_b2b08fac"
}
},
"default_mount": true,
"default_path_policy": "sign-verbatim",
"enabled": true,
"label_to_path_policy": {
"sign-all": "sign-verbatim",
"test-label": "role:est-clients"
},
"last_updated": "2024-02-02T10:49:20-05:00"
}
}
```
## CMPv2 Certificate issuance <EnterpriseAlert inline="true" />
@include 'alerts/beta.mdx'
Within Vault Enterprise, support can be enabled for the
[CMPv2 (Certificate Management Protocol) protocol](https://datatracker.ietf.org/doc/html/rfc4210)
for issuing and renewing leaf certificates.
### CMPv2 Protocol Paths <EnterpriseAlert inline="true" />
These are the CMP protocol API paths currently supported from Vault's authentication
point of view.
### Read CMPv2 Configuration <EnterpriseAlert inline="true" />
@include 'alerts/beta.mdx'
This endpoint fetches the current CMPv2 configuration.
| Method | Path |
| :----- |:------------------|
| `GET` | `/pki/config/cmp` |
#### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/pki/config/cmp
```
#### Sample response
```json
{
"data": {
"audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
"default_path_policy": "role:example-role",
"authenticators": {
"cert": {
"accessor": "auth_cert_7fe0c1cc",
"cert_role": "cmp-ca"
},
},
"enable_sentinel_parsing": true,
"enabled": true,
"last_updated": "2024-01-31T10:45:22-05:00"
}
}
```
### Set CMPv2 Configuration <EnterpriseAlert inline="true" />
@include 'alerts/beta.mdx'
This endpoint will update CMPv2 related configuration, returning the
updated values as a response along with an updated `last_updated` field.
| Method | Path |
|:-------|:------------------|
| `POST` | `/pki/config/cmp` |
#### Parameters
- `enabled` `(bool: false)` - Specifies whether CMPv2 is enabled or not.
- `authenticators` `(map[string]map[string]string: "")` - Specifies the mount accessors CMPv2 should delegate authentication
requests. Map key can only be `cert`, with associated value containing the key `accessor` with a value
containing the auth mount's accessor. An optional key `cert_role` parameter is supported which
will be passed as the [name](/vault/api-docs/auth/cert#name-6) parameter during certificate authentication attempts.
- `default_path_policy` `(string: required)`: Specify the default issuance policy
when the non role based cmp path is called. Must be set to either `sign-verbatim`
(to issue via the sign-verbatim function) or `role:` followed by the name of a configured
role.
- `enable_sentinel_parsing` `(bool: false)` - Parse out fields from the provided CSR making them available for
Sentinel policies.
- `audit_fields` `(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])` - Fields parsed from the CSR that
appear in the audit and can be used by sentinel policies. Allowed values are `csr`, `common_name`, `alt_names`,
`ip_sans`, `uri_sans`, `other_sans`, `signature_bits`, `exclude_cn_from_sans`, `ou`, `organization`, `country`,
`locality`, `province`, `street_address`, `postal_code`, `serial_number`, `use_pss`, `key_type`, `key_bits`,
`add_basic_constraints`
#### Sample Payload
```json
{
"enabled": true,
"authenticators": {
"cert": {
"accessor": "auth_cert_0f1df449",
"cert_role": "cert1"
},
"default_path_policy": "sign-verbatim",
"audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
"enable_sentinel_parsing": true
}
}
```
#### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/pki/config/cmp
```
#### Sample response
```json
{
"data": {
"audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
"authenticators": {
"cert": {
"accessor": "auth_cert_0f1df449",
"cert_role": "cert1"
},
"default_path_policy": "sign-verbatim",
"enabled": true,
"enable_sentinel_parsing": true,
"last_updated": "2024-02-02T10:49:20-05:00"
}
}
```

144
website/content/docs/secrets/pki/cmpv2.mdx Normal file
View File

@@ -0,0 +1,144 @@
---
layout: docs
page_title: Certificate Management Protocol v2 (CMPv2) within Vault | PKI - Secrets Engines
description: An overview of the Certificate Management Protocol (v2) implementation within Vault.
---
# PKI secrets engine - Certificate Management Protocol v2 (CMPv2) <EnterpriseAlert inline="true" />
This document summarizes Vault's PKI Secrets Engine
implementation of the [CMPv2 protocol](https://datatracker.ietf.org/doc/html/rfc4210) <EnterpriseAlert inline="true" />,
its configuration, and limitations.
## What is Certificate Management Protocol v2 (CMPv2)?
The CMP protocol is an IETF standardized protocol, [RFC 4210](https://datatracker.ietf.org/doc/html/rfc4210),
that allows clients to acquire client certificates and their associated Certificate
Authority (CA) certficates.
## Enabling CMPv2 support on a Vault PKI mount
To configure an existing mount to serve CMPv2 clients, the following steps are
required, which are broken down into three main categories:
1. [Configuring an Issuer](#configuring-an-issuer)
1. [Authentication mechanisms](#configuring-cmpv2-authentication)
1. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)
1. [PKI CMPv2 configuration](#enabling-cmpv2)
### Configuring an Issuer
CMPv2 is a bit unique, in that it uses the Issuer CA certificate to sign the
CMP messages. This means your issuer must have the `DigitalSignature` key
usage.
Existing CA issuers likely do not have this, so you will need to generate a new
issuer (likely an intermediate) that has this property. If you are configuring PKI
for the first time or creating a new issuer, ensure you set `key_usage` to,
as an example, `CRL,CASign,DigitalSignature`.
See [Generate intermediate CSR](/vault/api-docs/secret/pki#generate-intermediate-csr)
### Configuring CMPv2 Authentication
At this time, Vault's implementation of CMPv2 supports only
[Certificate TLS authentication](/vault/docs/auth/cert), where clients proof
of posession of a TLS client certificate authenticates them to Vault.
Authentication leverages a separate Vault authentication
mount, within the same namespace, to validate the client provided credentials
along with the client's ACL policy to enforce.
For proper accounting, a mount supporting CMPv2 authentication should be
dedicated to this purpose, not shared with other workflows. In other words,
create a new certificate auth mount for CMPv2 even if you already have one
another in use for other purposes.
When setting up the authentication mount for CMPv2 clients, the token type must
be configured to return [batch tokens](/vault/docs/concepts/tokens#batch-tokens).
Batch tokens are required to avoid an excessive amount of leases being generated
and persisted as every CMPv2 incoming request needs to be authenticated.
The path within an ACL policy must match the `cmp` path underneath the
PKI mount. The path to use can be the default `cmp` path or a role based one.
If using the `sign-verbatim` as a path policy, the following
ACL policy will allow an authenticated client access the required PKI CMP path.
```
path “pki/cmp” {
capabilities=[“update”, “create”]
}
```
For a role base path policy, this sample policy can be used
```
path “pki/roles/my-role-name/cmp” {
capabilities=[“update”, “create”]
}
```
#### Updating the PKI mount tunable parameters
Once the authentication mount has been created and configured, the authentication mount's accessor
will need to be captured and added within the PKI mount's [delegated auth accessors](/vault/api-docs/system/mounts#delegated_auth_accessors).
To get an authentication mount's accessor field, the following command can be used.
```shell-session
$ vault read -field=accessor sys/auth/auth/cert
```
For CMP to work within certain clients, a few response headers need to be explicitly allowed
along with configuring the list of accessors the mount can delegate authentication towards.
The following will grant the required response headers, you will need to replace the values for the `delegated-auth-accessors`
to match your values.
```shell-session
$ vault secrets tune \
-allowed-response-headers="Content-Transfer-Encoding" \
-allowed-response-headers="Content-Length" \
-allowed-response-headers="WWW-Authenticate" \
-delegated-auth-accessors="auth_cert_4088ac2d" \
pki
```
#### Enabling CMPv2
Enabling CMP is a matter of writing to the `config/cmp` endpoint, to set it
enabled and configure default path policy and authentication.
```shell-session
vault write pki/config/cmp -<<EOC
{
"enabled": true,
"default_path_policy": "role:example-role",
"authenticators": {
"cert": {
"accessor": "auth_cert_4088ac2d"
}
},
"audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}
EOC
```
Of course, substituting your own role and accessor values. After this, the
CMP endpoints will be able to handle client requests, authenticated with the
previously configured Cert Auth method.
## Limitations
The initial release of CMPv2 support is intentionally limited to a subset of the
protocol, covering Initialization, Certification, and Key Update, over HTTP.
In particular, the following are not yet supported:
* Basic authentication scheme using PasswordBasedMac
* Revocation
* CRL fetching via CMP itself.
* CA creation/update operations.
Note that CMPv2 is not integrated with these existing Vault PKI features:
* Certificate Metadata - CMPv2 has no means of providing metadata.
* Certificate Issuance External Policy Service [(CIEPS)](/vault/docs/secrets/pki/cieps)

16
website/content/docs/secrets/pki/index.mdx
View File

@@ -41,17 +41,23 @@ The PKI Secrets Engine documentation is split into the following pieces:
- [Considerations](/vault/docs/secrets/pki/considerations) - A list of helpful
considerations to keep in mind when using and operating the PKI Secrets
Engine.
- [Troubleshooting ACME](/vault/docs/secrets/pki/troubleshooting-acme) - A list of
advice for troubleshooting failures with ACME issuance and Vault PKI.
- [Rotation Primitives](/vault/docs/secrets/pki/rotation-primitives) - A document
which explains different types of certificates used to achieve rotation.
- [CIEPS Protocol <EnterpriseAlert inline="true" />](/vault/docs/secrets/pki/cieps) - A
document which explains the Certificate Issuance External Policy Service (CIEPS)
protocol (request and response structure), along with an overview of the difference
between it and `/pki/sign-verbatim`.
- [EST Protocol <EnterpriseAlert inline="true" />](/vault/docs/secrets/pki/est) - A
document which explains Vault's implementation of the EST protocol, from configuration
to limitations.
- Issuance Protocols: Using standard certificate management protocols with Vault PKI.
- [EST <EnterpriseAlert inline="true" />](/vault/docs/secrets/pki/est) -
Explains Vault's implementation of the EST protocol, from configuration
to limitations.
- [CMPv2 <EnterpriseAlert inline="true" />](/vault/docs/secrets/pki/cmpv2) -
Explains Vault's implementation of the CMPv2 protocol, from configuration
to limitations.
- [Troubleshooting ACME](/vault/docs/secrets/pki/troubleshooting-acme) - A list of
advice for troubleshooting failures with ACME issuance and Vault PKI.
## Tutorial

11
website/data/api-docs-nav-data.json
View File

@@ -259,7 +259,16 @@
},
{
"title": "PKI",
"path": "secret/pki"
"routes": [
{
"title": "Overview",
"path": "secret/pki"
},
{
"title": "Issuance Protocols",
"path": "secret/pki/issuance"
}
]
},
{
"title": "RabbitMQ",

18
website/data/docs-nav-data.json
View File

@@ -1592,11 +1592,6 @@
"title": "Considerations",
"path": "secrets/pki/considerations"
},
{
"title": "Troubleshooting ACME integration",
"path": "secrets/pki/troubleshooting-acme"
},
{
"title": "Rotation Primitives",
"path": "secrets/pki/rotation-primitives"
@@ -1618,6 +1613,19 @@
"color": "highlight"
},
"path": "secrets/pki/est"
},
{
"title": "Certificate Management Protocol (CMPv2)",
"badge": {
"text": "BETA",
"type": "outlined",
"color": "highlight"
},
"path": "secrets/pki/cmpv2"
},
{
"title": "Troubleshooting ACME",
"path": "secrets/pki/troubleshooting-acme"
}
]
},