upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-02-18 18:38:08 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Docs CIEPS Configuration (#22259)

Browse source 
* Clarify wording, add missing expiration fields

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add API docs on CIEPS configuration

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Fix ToC, headers to include EnterpriseAlert

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

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

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

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

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

---------

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
Co-authored-by: Steven Clark <steven.clark@hashicorp.com>
This commit is contained in:
Alexander Scheel 2023-08-09 08:27:06 -05:00 committed by GitHub
parent 04a081226d
commit d4e402d597
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 125 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

132
website/content/api-docs/secret/pki.mdx
View file

@ -30,9 +30,9 @@ update your API calls accordingly.
- [List Roles](#list-roles)
- [Read Role](#read-role)
- [Generate Certificate and Key](#generate-certificate-and-key)
- [Generate Certificate and Key with External Policy](#generate-certificate-and-key-with-external-policy)
- [Generate Certificate and Key with External Policy <EnterpriseAlert inline="true" />](#generate-certificate-and-key-with-external-policy)
- [Sign Certificate](#sign-certificate)
- [Sign Certificate with External Policy](#sign-certificate-with-external-policy)
- [Sign Certificate with External Policy <EnterpriseAlert inline="true" />](#sign-certificate-with-external-policy)
- [Sign Intermediate](#sign-intermediate)
- [Sign Self-Issued](#sign-self-issued)
- [Sign Verbatim](#sign-verbatim)
@ -70,6 +70,8 @@ update your API calls accordingly.
- [Create/Update Role](#create-update-role)
- [Read Role](#read-role)
- [Delete Role](#delete-role)
- [Read Certificate Issuance External Policy Service (CIEPS) Configuration <EnterpriseAlert inline="true" />](#read-certificate-issuance-external-policy-service-cieps-configuration)
- [Set Certificate Issuance External Policy Service (CIEPS) Configuration <EnterpriseAlert inline="true" />](#set-certificate-issuance-external-policy-service-cieps-configuration)
- [Read URLs](#read-urls)
- [Set URLs](#set-urls)
- [Read Issuers Configuration](#read-issuers-configuration)
@ -165,9 +167,9 @@ prove ownership of will be issued for. This is similar to using the
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 CIEPS engine <EnterpriseAlert inline="true" /> is used for
validating and templating the certificate. An optional policy name can be
specified by using `external-policy:policy`. Roles are not used when CIEPS is
used.
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
@ -684,6 +686,7 @@ $ curl \
"renewable": false,
"lease_duration": 21600,
"data": {
"expiration": "1654105687",
"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": [
@ -698,7 +701,7 @@ $ curl \
}
```
### Generate certificate and key with external policy
### Generate certificate and key with external policy <EnterpriseAlert inline="true" />
Similar to the [generate certificate and key](#generate-certificate-and-key)
endpoint, this endpoint generate key material and certificate via an external
@ -784,6 +787,7 @@ recognized based on external CIEPS engine definition.
"renewable": false,
"lease_duration": 0,
"data": {
"expiration": "1654105687",
"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": [
@ -898,6 +902,7 @@ It is suggested to limit access to the path-overridden sign endpoint (on
"renewable": false,
"lease_duration": 21600,
"data": {
"expiration": "1654105687",
"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": [
@ -909,7 +914,7 @@ It is suggested to limit access to the path-overridden sign endpoint (on
}
```
### Sign certificate with external policy
### Sign certificate with external policy <EnterpriseAlert inline="true" />
Similar to the [sign certificate](#sign-certificate) endpoint, this endpoint
signs the specified leaf CSR via an external policy engine. Any parameters
@ -983,6 +988,7 @@ recognized based on external CIEPS engine definition.
"renewable": false,
"lease_duration": 0,
"data": {
"expiration": "1654105687",
"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": [
@ -1180,6 +1186,7 @@ $ curl \
"renewable": false,
"lease_duration": 0,
"data": {
"expiration": "1654105687",
"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": [
@ -3535,6 +3542,117 @@ $ curl \
http://127.0.0.1:8200/v1/pki/roles/my-role
```
### Read Certificate Issuance External Policy Service (CIEPS) configuration <EnterpriseAlert inline="true" />
This endpoint reads the Certificate Issuance External Policy Service
(CIEPS) engine <EnterpriseAlert inline="true" /> connection properties.
On top of the configuration parameters documented below, this endpoint
returns the following parameters:
- `external_service_last_updated` - An RFC 3339 timestamp indicating when the
configuration was last modified.
- `external_service_validated` - Indicates whether a successful connection to
the external policy engine has been made under this configuration.
- `last_successful_request` - Timestamp of the last successful request to
the external policy engine.
Note that the last two parameters are node-specific and will be reset
whenever the mount reloads (e.g., leadership election or seal/unseal).
| Method | Path |
| :----- | :---------------------------- |
| `GET` | `/pki/config/external-policy` |
#### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
--data @payload.json \
http://127.0.0.1:8200/v1/pki/config/external-policy
```
#### Sample Response
```
{
"data": {
"enabled": false,
"external_service_last_updated": "0001-01-01T00:00:00Z",
"external_service_url": "",
"external_service_validated": false,
"last_successful_request": "",
"timeout": 15000000000,
"trusted_ca": "",
"trusted_leaf_certificate_bundle": "",
"vault_client_cert_bundle": ""
},
}
```
### Set Certificate Issuance External Policy Service (CIEPS) configuration <EnterpriseAlert inline="true" />
This endpoint allows enabling the Certificate Issuance External Policy Service
(CIEPS) <EnterpriseAlert inline="true" /> engine and configuring connection
properties.
| Method | Path |
| :----- | :---------------------------- |
| `POST` | `/pki/config/external-policy` |
#### Parameters
- `enabled` `(bool: false)` - Enables or disables the external policy
service. When disabled, issuance mechanisms under `external-policy`
paths (e.g., `/pki/external-policy/sign/:policy`) will not work.
- `external_service_url` `(string: <required>)` - URI to the external
policy engine. Must use the `https://` scheme.
- `timeout` `(string: "")` - This is how long any particular API request
should wait for a timeout at various layers of the stack. Defaults to
`15s`.
- `trusted_ca` `(string: "")` - A PEM bundle of trusted CAs to verify the
certificates presented by the external policy engine against. Optional;
one of `trusted_ca` or `trusted_leaf_certificate_bundle` must be specified.
- `trusted_leaf_certificate_bundle` `(string: "")` - A PEM bundle of pinned
non-CA leaf certificates that must be presented by the external policy
engine. Optional; one of `trusted_ca` or `trusted_leaf_certificate_bundle`
must be specified.
- `vault_client_cert_bundle` `(string: "")` - A PEM bundle of a private key
and one or more certificates to present during authentication to the
external policy service.
- `entity_jmespath` `(string: "")` - A JMESPath expression that will select and filter entity metadata to the service. By default no entity metadata beyond the entity id is sent, use "@" to send all information
- `group_jmespath` `(string: "")` - A JMESPath expression that will select and filter entity group metadata to the service. By default no group entity metadata is sent, use "@" to send all information
#### Sample payload
```json
{
"enabled": true,
"external_service_url": "https://cieps.dadgarcorp.internal",
"trusted_ca": "-----BEGIN CERTIFICATE-----...."
}
```
#### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/pki/config/external-policy
```
### Read URLs
This endpoint fetches the URLs to be encoded in generated certificates. No URL