Add api-docs for PKI CIEPS sign-intermediate (#22371)

* Add api-docs for PKI CIEPS sign-intermediate - This adds the CIEPS sign-intermediate api-docs and tweaks the existing CIEPS apis to mark the policy url argument as optional. * Define CIEPS in the first use per section
2025-11-01 02:57:59 +00:00 · 2023-08-17 08:57:55 -04:00
parent a53e78699f
commit aa81aeaba0
1 changed files with 101 additions and 17 deletions
--- 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 <EnterpriseAlert inline="true" />](#sign-certificate-with-external-policy)
  - [Sign Intermediate](#sign-intermediate)
+  - [Sign Intermediate with External Policy <EnterpriseAlert inline="true" />](#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 <EnterpriseAlert inline="true" /> is used for
+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.
@@ -707,7 +709,8 @@ 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 <EnterpriseAlert inline="true" />. The
+passed verbatim to the Certificate Issuance External
+Policy Service (CIEPS)<EnterpriseAlert inline="true" />. The
 response format is the same between both endpoints.

 It is suggested to limit access to the path-overridden issue endpoint (on
@@ -715,13 +718,13 @@ It is suggested to limit access to the path-overridden issue endpoint (on
 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      |
+| :----- |:----------------------------------------------------------| :-------------------------- |
+| `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: <required>)` - Specifies the name of the policy to create
+- `policy` `(string: <optional>)` - 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,8 +921,8 @@ 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 <EnterpriseAlert inline="true" />. The response format is the same
+passed to this endpoint are passed verbatim to the Certificate Issuance External
+Policy Service (CIEPS)<EnterpriseAlert inline="true" />. The response format is the same
 between both endpoints.

 It is suggested to limit access to the path-overridden sign endpoint (on
@@ -927,13 +930,13 @@ It is suggested to limit access to the path-overridden sign endpoint (on
 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      |
+| :----- |:---------------------------------------------------------| :-------------------------- |
+| `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: <required>)` - Specifies the name of the policy to create
+- `policy` `(string: <optional>)` - 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 <EnterpriseAlert inline="true" />
+
+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)<EnterpriseAlert inline="true" />.
+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: <optional>)` - 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: <required>)` - 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: <required>)` - 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