diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index c952dec9c1..d8bf059183 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -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 ](#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 ](#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 ](#read-certificate-issuance-external-policy-service-cieps-configuration) + - [Set Certificate Issuance External Policy Service (CIEPS) Configuration ](#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 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 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 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 + +This endpoint reads the Certificate Issuance External Policy Service +(CIEPS) engine 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 + +This endpoint allows enabling the Certificate Issuance External Policy Service +(CIEPS) 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: )` - 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