mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-29 01:32:33 +00:00
807 lines
26 KiB
Plaintext
807 lines
26 KiB
Plaintext
---
|
|
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)
|
|
- [List ACME Account Keys](#list-acme-account-keys)
|
|
- [Get ACME Account Info](#get-acme-account-info)
|
|
- [Update ACME Account Info](#update-acme-account-info)
|
|
- [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 title="Require EAB for public-facing Vault deployments">
|
|
|
|
We strongly recommend enabling EAB for public-facing Vault
|
|
deployments. Use the `VAULT_DISABLE_PUBLIC_ACME` environment
|
|
variable to force-enable EAB for all ACME instances.
|
|
|
|
</Note>
|
|
|
|
#### 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
|
|
}
|
|
}
|
|
```
|
|
|
|
### List ACME account keys
|
|
|
|
The `ListAcmeAccountKeys` endpoint returns a list of ACME account key
|
|
identifiers.
|
|
|
|
| Method | Path |
|
|
|:-------|:-------------------------------|
|
|
| `LIST` | `/pki/acme/mgmt/account/keyid` |
|
|
|
|
#### Sample request
|
|
|
|
```
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
--request LIST \
|
|
http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid
|
|
```
|
|
|
|
#### Sample response
|
|
|
|
```
|
|
{
|
|
"data": {
|
|
"keys": [
|
|
"2ea9859a-eba8-ff24-cd03-2a51639fc7d5"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Get ACME account info
|
|
|
|
The `GetAcmeAccountInfo` endpoint returns account information,
|
|
including orders and certificate details, for the provided ACME account
|
|
key.
|
|
|
|
| Method | Path |
|
|
|:-------|:---------------------------------------|
|
|
| `GET` | `/pki/acme/mgmt/account/keyid/:key_id` |
|
|
|
|
#### Path parameters
|
|
|
|
- `key_id` `(string: <required>)` - ID of the target ACME account.
|
|
|
|
#### Sample request
|
|
|
|
```
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5
|
|
```
|
|
|
|
#### Sample response
|
|
|
|
```
|
|
{
|
|
"data": {
|
|
"contacts": null,
|
|
"created_time": "2024-12-12T12:55:50-05:00",
|
|
"directory": "acme/",
|
|
"eab": {
|
|
"created_time": "2024-12-12T12:55:29-05:00",
|
|
"directory": "acme/",
|
|
"eab_id": "24c0673a-df53-0671-a628-e7b9c995485c",
|
|
"key_type": "hs"
|
|
},
|
|
"key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5",
|
|
"orders": [
|
|
{
|
|
"cert_expiry": "2024-12-13T17:55:28Z",
|
|
"cert_serial_number": "4a:6f:d0:f7:13:55:f7:c9:19:82:fc:34:69:67:77:2e:58:27:02:8b",
|
|
"identifiers": [
|
|
"testing.dadgarcorp.com"
|
|
],
|
|
"order_expiry": "2024-12-13T12:56:04-05:00",
|
|
"order_id": "90699994-8863-571c-26b0-46755e0db351",
|
|
"status": "valid"
|
|
}
|
|
],
|
|
"revoked_time": "",
|
|
"status": "valid"
|
|
},
|
|
}
|
|
```
|
|
|
|
### Update ACME account info
|
|
|
|
The `UpdateAcmeAccountInfo` endpoint revokes or re-enables an ACME
|
|
account and returns the account details excluding order or certificate
|
|
details.
|
|
|
|
| Method | Path |
|
|
|:-------|:---------------------------------------|
|
|
| `POST` | `/pki/acme/mgmt/account/keyid/:key_id` |
|
|
|
|
#### Path parameters
|
|
|
|
- `key_id` `(string: <required>)` - ID of the target ACME account.
|
|
|
|
|
|
### Parameters
|
|
|
|
- `status` `(string: <required>)` - The new account status. Must be one of:
|
|
`revoked`, `valid`.
|
|
|
|
<Note title="ACME account revocation does not revoke certificates">
|
|
|
|
Revoking an ACME account forbids further operations on the account
|
|
without revoking existing certificates. You must revoke any existing
|
|
certificates manually.
|
|
|
|
</Note>
|
|
|
|
#### Sample request
|
|
|
|
```
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5
|
|
```
|
|
|
|
#### Sample response
|
|
|
|
```
|
|
{
|
|
"data": {
|
|
"contacts": null,
|
|
"created_time": "2024-12-12T12:55:50-05:00",
|
|
"directory": "acme/",
|
|
"eab": {
|
|
"created_time": "2024-12-12T12:55:29-05:00",
|
|
"directory": "acme/",
|
|
"eab_id": "24c0673a-df53-0671-a628-e7b9c995485c",
|
|
"key_type": "hs"
|
|
},
|
|
"key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5",
|
|
"revoked_time": "2024-12-12T12:59:02-05:00",
|
|
"status": "revoked"
|
|
},
|
|
}
|
|
```
|
|
|
|
## EST Certificate issuance <EnterpriseAlert inline="true" />
|
|
|
|
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" />
|
|
|
|
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" />
|
|
|
|
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" />
|
|
|
|
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" />
|
|
|
|
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",
|
|
"disabled_validations": [],
|
|
"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" />
|
|
|
|
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`
|
|
|
|
- `disabled_validations` `(list: [])` - Checks to skip during request validation. Possible values are
|
|
`DisableMatchingKeyIdValidation`, and 'DisableCertTimeValidation'. `DisableMatchingKeyIdValidation` disables
|
|
the check that sender key ID in the request header needs to match the subject public key ID in the signing
|
|
certificate. `DisableCertTimeValidation` disables the not before/not after verifications within the signing
|
|
certificate. Disabling any validation is highly discouraged.
|
|
|
|
#### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"enabled": true,
|
|
"authenticators": {
|
|
"cert": {
|
|
"accessor": "auth_cert_0f1df449",
|
|
"cert_role": "cert1"
|
|
},
|
|
"default_path_policy": "sign-verbatim",
|
|
"disabled_validations": ["DisableMatchingKeyIdValidation"],
|
|
"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",
|
|
"disabled_validations": ["DisableMatchingKeyIdValidation"],
|
|
"enabled": true,
|
|
"enable_sentinel_parsing": true,
|
|
"last_updated": "2024-02-02T10:49:20-05:00"
|
|
}
|
|
}
|
|
```
|