scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-01 02:57:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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
This commit is contained in:
Steven Clark
2023-08-17 08:57:55 -04:00
committed by GitHub
parent a53e78699f
commit aa81aeaba0
1 changed files with 101 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
website/content/api-docs/secret/pki.mdx
View File

@@ -34,6 +34,7 @@ update your API calls accordingly.
- [Sign Certificate](#sign-certificate) - [Sign Certificate](#sign-certificate)
- [Sign Certificate with External Policy <EnterpriseAlert inline="true" />](#sign-certificate-with-external-policy) - [Sign Certificate with External Policy <EnterpriseAlert inline="true" />](#sign-certificate-with-external-policy)
- [Sign Intermediate](#sign-intermediate) - [Sign Intermediate](#sign-intermediate)
- [Sign Intermediate with External Policy <EnterpriseAlert inline="true" />](#sign-intermediate-with-external-policy)
- [Sign Self-Issued](#sign-self-issued) - [Sign Self-Issued](#sign-self-issued)
- [Sign Verbatim](#sign-verbatim) - [Sign Verbatim](#sign-verbatim)
- [Revoke Certificate](#revoke-certificate) - [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 [Sign Verbatim](#sign-verbatim) endpoint, but with additional verification
that the client has proven ownership (within the ACME protocol) of the that the client has proven ownership (within the ACME protocol) of the
requested certificate identifiers. When `external-policy` is specified as 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 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 validation is still enforced. An optional policy name can be specified by using
`external-policy:policy`. Roles are not used when CIEPS is used. `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 endpoint, this endpoint generate key material and certificate via an external
policy engine. The private key material stays local to Vault, with the 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 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. response format is the same between both endpoints.
It is suggested to limit access to the path-overridden issue endpoint (on 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 `/pki/issuer/:issuer_ref/external-policy/issue/:policy`) and let the CIEPS
engine override the issuer as necessary. engine override the issuer as necessary.
| Method | Path | Issuer | | Method | Path | Issuer |
| :----- | :------------------------------------------------------ | :-------------------------- | | :----- |:----------------------------------------------------------| :-------------------------- |
| `POST` | `/pki/external-policy/issue/:policy` | `default` 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 | | `POST` | `/pki/issuer/:issuer_ref/external-policy/issue(/:policy)` | Path or CIEPS selected |
#### Parameters #### 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 the certificate against. This is part of the request URL and is passed to the
external CIEPS engine. 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 Similar to the [sign certificate](#sign-certificate) endpoint, this endpoint
signs the specified leaf CSR via an external policy engine. Any parameters signs the specified leaf CSR via an external policy engine. Any parameters
passed to this endpoint are passed verbatim to the CIEPS passed to this endpoint are passed verbatim to the Certificate Issuance External
engine <EnterpriseAlert inline="true" />. The response format is the same Policy Service (CIEPS)<EnterpriseAlert inline="true" />. The response format is the same
between both endpoints. between both endpoints.
It is suggested to limit access to the path-overridden sign endpoint (on 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 `/pki/issuer/:issuer_ref/external-policy/sign/:policy`) and let the CIEPS
engine override the issuer as necessary. engine override the issuer as necessary.
| Method | Path | Issuer | | Method | Path | Issuer |
| :----- | :----------------------------------------------------- | :-------------------------- | | :----- |:---------------------------------------------------------| :-------------------------- |
| `POST` | `/pki/external-policy/sign/:policy` | `default` 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 | | `POST` | `/pki/issuer/:issuer_ref/external-policy/sign(/:policy)` | Path or CIEPS selected |
#### Parameters #### 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 the certificate against. This is part of the request URL and is passed to the
external CIEPS engine. 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 ### Sign Self-Issued
This endpoint uses the configured CA certificate to sign a 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 and one or more certificates to present during authentication to the
external policy service. 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 - `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 - `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 #### Sample payload
@@ -4144,9 +4228,9 @@ the CRL.
cross-cluster revocation request will be created.<br /><br /> cross-cluster revocation request will be created.<br /><br />
API calls to revoke a certificate with Proof of Possession (PoP) cannot API calls to revoke a certificate with Proof of Possession (PoP) cannot
be satisfied if the certificate is not available locally and will 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)` -
<EnterpriseAlert product="vault" inline /> Enables unified CRL and OCSP building. This <EnterpriseAlert product="vault" inline /> Enables unified CRL and OCSP building. This
synchronizes all revocations between clusters; a single, unified CRL will be synchronizes all revocations between clusters; a single, unified CRL will be
built on the active node of the primary performance replication (PR) built on the active node of the primary performance replication (PR)