diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index 67165ebbe1..59eedc4544 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -34,6 +34,7 @@ update your API calls accordingly. - [Sign Certificate](#sign-certificate) - [Sign Certificate with External Policy ](#sign-certificate-with-external-policy) - [Sign Intermediate](#sign-intermediate) + - [Sign Intermediate with External Policy ](#sign-intermediate-with-external-policy) - [Sign Self-Issued](#sign-self-issued) - [Sign Verbatim](#sign-verbatim) - [Revoke Certificate](#revoke-certificate) @@ -166,7 +167,8 @@ 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 CIEPS engine is used for +default value, the Certificate Issuance External +Policy Service (CIEPS) is used for validating and templating the certificate instead of a role; ACME's challenge validation is still enforced. An optional policy name can be specified by using `external-policy:policy`. Roles are not used when CIEPS is used. @@ -707,21 +709,22 @@ Similar to the [generate certificate and key](#generate-certificate-and-key) endpoint, this endpoint generate key material and certificate via an external policy engine. The private key material stays local to Vault, with the external service getting only an empty CSR. Any parameters passed to this endpoint are -passed verbatim to the CIEPS engine . The +passed verbatim to the Certificate Issuance External +Policy Service (CIEPS). The response format is the same between both endpoints. It is suggested to limit access to the path-overridden issue endpoint (on `/pki/issuer/:issuer_ref/external-policy/issue/:policy`) and let the CIEPS engine override the issuer as necessary. -| Method | Path | Issuer | -| :----- | :------------------------------------------------------ | :-------------------------- | -| `POST` | `/pki/external-policy/issue/:policy` | `default` or CIEPS-selected | -| `POST` | `/pki/issuer/:issuer_ref/external-policy/issue/:policy` | Path or CIEPS selected | +| Method | Path | Issuer | +| :----- |:----------------------------------------------------------| :-------------------------- | +| `POST` | `/pki/external-policy/issue(/:policy)` | `default` or CIEPS-selected | +| `POST` | `/pki/issuer/:issuer_ref/external-policy/issue(/:policy)` | Path or CIEPS selected | #### Parameters -- `policy` `(string: )` - Specifies the name of the policy to create +- `policy` `(string: )` - Specifies the name of the policy to create the certificate against. This is part of the request URL and is passed to the external CIEPS engine. @@ -918,22 +921,22 @@ It is suggested to limit access to the path-overridden sign endpoint (on Similar to the [sign certificate](#sign-certificate) endpoint, this endpoint signs the specified leaf CSR via an external policy engine. Any parameters -passed to this endpoint are passed verbatim to the CIEPS -engine . The response format is the same +passed to this endpoint are passed verbatim to the Certificate Issuance External +Policy Service (CIEPS). The response format is the same between both endpoints. It is suggested to limit access to the path-overridden sign endpoint (on `/pki/issuer/:issuer_ref/external-policy/sign/:policy`) and let the CIEPS engine override the issuer as necessary. -| Method | Path | Issuer | -| :----- | :----------------------------------------------------- | :-------------------------- | -| `POST` | `/pki/external-policy/sign/:policy` | `default` or CIEPS-selected | -| `POST` | `/pki/issuer/:issuer_ref/external-policy/sign/:policy` | Path or CIEPS selected | +| Method | Path | Issuer | +| :----- |:---------------------------------------------------------| :-------------------------- | +| `POST` | `/pki/external-policy/sign(/:policy)` | `default` or CIEPS-selected | +| `POST` | `/pki/issuer/:issuer_ref/external-policy/sign(/:policy)` | Path or CIEPS selected | #### Parameters -- `policy` `(string: )` - Specifies the name of the policy to create +- `policy` `(string: )` - Specifies the name of the policy to create the certificate against. This is part of the request URL and is passed to the external CIEPS engine. @@ -1198,6 +1201,87 @@ $ curl \ } ``` +### Sign Intermediate with External Policy + +Similar to [sign intermediate](#sign-intermediate), this endpoint accepts a +CSR and returns a certificate with appropriate values for acting as an +intermediate CA via an external policy engine. Any parameters passed to this +endpoint are passed verbatim to the Certificate Issuance External Policy Service +(CIEPS). +The response format is the same between both endpoints. + +It is suggested to limit access to the path-overridden issue endpoint +(on /pki/issuer/:issuer_ref/external-policy/issue/:policy) and let the CIEPS +engine override the issuer as necessary. + +| Method | Path | Issuer | +|--------|---------------------------------------------------------------------|---------------------------| +| POST | /pki/external-policy/sign-intermediate(/:policy) | default or CIEPS-selected | +| POST | /pki/issuer/:issuer_ref/external-policy/sign-intermediate(/:policy) | Path or CIEPS selected | + +#### Parameters + +- `policy` `(string: )` - Specifies the name of the policy to create + the certificate against. This is part of the request URL and is passed to the + external CIEPS engine. + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/external-policy/sign-intermediate` +path and takes its value from the CIEPS engine response's `issuer_ref` +field, which can override the user-requested issuer. + +- `csr` `(string: )` - Specifies the PEM-encoded CSR. + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `certificate` field will contain the + private key and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `private_key_format` `(string: "pem")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate +field if `format=pem_bundle` parameter is specified. + +Other parameters may be specified and will not be parsed by Vault but may be +recognized based on external CIEPS engine definition. + +#### Sample payload + +```json +{ + "csr": "..." +} +``` + +#### Sample response + +```json +{ + "lease_id": "", + "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": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + ### Sign Self-Issued This endpoint uses the configured CA certificate to sign a self-issued @@ -3631,7 +3715,7 @@ properties. 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 @@ -4144,9 +4228,9 @@ the CRL. cross-cluster revocation request will be created.

API calls to revoke a certificate with Proof of Possession (PoP) cannot be satisfied if the certificate is not available locally and will - not result in a cross-cluster revocation request. + not result in a cross-cluster revocation request. -- `unified_crl` `(bool: false)` - +- `unified_crl` `(bool: false)` - Enables unified CRL and OCSP building. This synchronizes all revocations between clusters; a single, unified CRL will be built on the active node of the primary performance replication (PR)