mirror of
https://github.com/hashicorp/vault.git
synced 2026-05-05 12:26:34 +02:00
Document Cross-Cluster CRLs/OCSP for Vault Enterprise (#18970)
* Add documentation on fetching unified CRLs Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add documentation on unified OCSP Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Clarify that OCSP requests need to be URL encoded Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Document new CRL config parameters Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Clarify notes about cross-cluster options Co-authored-by: Steven Clark <steven.clark@hashicorp.com> Signed-off-by: Alexander Scheel <alex.scheel@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
GitHub
parent
80485f927b
commit
3083f755f3
@ -1261,6 +1261,16 @@ corresponding full CRL when it has been regenerated; otherwise, some serial
|
||||
numbers may not appear in the local copy of the full CRL if the remote
|
||||
complete and delta CRLs has been regenerated.
|
||||
|
||||
Endpoints with source `local` only include cluster-local revocations. When
|
||||
the `unified_crl` parameters is enabled in the [CRL
|
||||
configuration](#set-crl-configuration), endpoints with source `unified`
|
||||
will have revocations from all clusters. Generally use of the `unified`
|
||||
source is more consistent with expectations of external apps, but see
|
||||
the [PKI Considerations](/vault/docs/secrets/pki/considerations) page
|
||||
for a discussion on cluster size and unified CRLs/OCSP.
|
||||
|
||||
~> Note: Unified CRLs are a Vault Enterprise only feature.
|
||||
|
||||
These are unauthenticated endpoints.
|
||||
|
||||
~> **Note**: As of Vault 1.11.0, these endpoints now serve a [version 2](https://datatracker.ietf.org/doc/html/rfc5280#section-5.1.2.1) CRL response.
|
||||
@ -1272,20 +1282,32 @@ These are unauthenticated endpoints.
|
||||
header `Last-Modified` needs to be added to the mount tunable
|
||||
`allowed_response_headers`.
|
||||
|
||||
| Method | Path | Issuer | Format | Type |
|
||||
| :----- | :-------------------------------------- | :-------- | :-------------------------------------------------------------------------------- | :------- |
|
||||
| `GET` | `/pki/cert/crl` | `default` | JSON | Complete |
|
||||
| `GET` | `/pki/crl` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
|
||||
| `GET` | `/pki/crl/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
|
||||
| `GET` | `/pki/cert/delta-crl` | `default` | JSON | Delta |
|
||||
| `GET` | `/pki/crl/delta` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta |
|
||||
| `GET` | `/pki/crl/delta/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl` | Selected | JSON | Complete |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/delta` | Selected | JSON | Delta |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/delta/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/delta/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta |
|
||||
| Method | Path | Issuer | Format | Type | Source |
|
||||
| :----- | :---------------------------------------------- | :-------- | :-------------------------------------------------------------------------------- | :------- | :------ |
|
||||
| `GET` | `/pki/cert/crl` | `default` | JSON | Complete | Local |
|
||||
| `GET` | `/pki/crl` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local |
|
||||
| `GET` | `/pki/crl/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local |
|
||||
| `GET` | `/pki/cert/delta-crl` | `default` | JSON | Delta | Local |
|
||||
| `GET` | `/pki/crl/delta` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local |
|
||||
| `GET` | `/pki/crl/delta/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl` | Selected | JSON | Complete | Local |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/delta` | Selected | JSON | Delta | Local |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/delta/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/crl/delta/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local |
|
||||
| `GET` | `/pki/cert/unified-crl` | `default` | JSON | Complete | Unified |
|
||||
| `GET` | `/pki/unified-crl` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified |
|
||||
| `GET` | `/pki/unified-crl/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified |
|
||||
| `GET` | `/pki/cert/unified-delta-crl` | `default` | JSON | Delta | Unified |
|
||||
| `GET` | `/pki/unified-crl/delta` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified |
|
||||
| `GET` | `/pki/unified-crl/delta/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/unified-crl` | Selected | JSON | Complete | Unified |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/unified-crl/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/unified-crl/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/unified-crl/delta` | Selected | JSON | Delta | Unified |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/unified-crl/delta/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified |
|
||||
| `GET` | `/pki/issuer/:issuer_ref/unified-crl/delta/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified |
|
||||
|
||||
#### Parameters
|
||||
|
||||
@ -1319,19 +1341,32 @@ $ curl \
|
||||
This endpoint retrieves an OCSP response (revocation status) for a given serial number. The request/response formats are
|
||||
based on [RFC 6960](https://datatracker.ietf.org/doc/html/rfc6960)
|
||||
|
||||
At this time there are certain limitations of the OCSP implementation at this path.
|
||||
1. Only a single serial number within the request will appear in the response
|
||||
1. None of the extensions defined in the RFC are supported for requests or responses
|
||||
1. Ed25519 backed CA's are not supported for OCSP requests
|
||||
1. Note that this api will not work with the Vault client as both request and responses are DER encoded
|
||||
Endpoints with source `local` only include cluster-local revocations. When
|
||||
the `unified_crl` parameters is enabled in the [CRL
|
||||
configuration](#set-crl-configuration), endpoints with source `unified`
|
||||
will have revocations from all clusters. Generally use of the `unified`
|
||||
source is more consistent with expectations of external apps, but see
|
||||
the [PKI Considerations](/vault/docs/secrets/pki/considerations) page
|
||||
for a discussion on cluster size and unified CRLs/OCSP.
|
||||
|
||||
~> Note: Unified OCSP is a Vault Enterprise only feature.
|
||||
|
||||
At this time there are certain limitations of the OCSP implementation at this path:
|
||||
|
||||
1. Only a single serial number within the request will appear in the response,
|
||||
1. None of the extensions defined in the RFC are supported for requests or responses,
|
||||
1. Ed25519 backed CA's are not supported for OCSP requests,
|
||||
1. Note that this API will not work with the Vault client as both request and responses are DER encoded, and
|
||||
1. Note that KMS based issuers which require PSS support are not supported either (such as PKCS#11 HSMs or GCP in certain scenarios).
|
||||
|
||||
These are unauthenticated endpoints.
|
||||
|
||||
| Method | Path | Response Format |
|
||||
| :----- |:-----------------------------------------------|:----------------------------------------------------------------------------------|
|
||||
| `GET` | `/pki/ocsp/<base 64 encoded ocsp DER request>` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") |
|
||||
| `POST` | `/pki/ocsp` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") |
|
||||
| Method | Path | Response Format | Source |
|
||||
| :----- | :--------------------------------------------------------- | :-------------------------------------------------------------------------------- | :------ |
|
||||
| `GET` | `/pki/ocsp/<base 64+URL encoded ocsp DER request>` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Local |
|
||||
| `POST` | `/pki/ocsp` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Local |
|
||||
| `GET` | `/pki/unified-ocsp/<base 64+URL encoded ocsp DER request>` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Unified |
|
||||
| `POST` | `/pki/unified-ocsp` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Unified |
|
||||
|
||||
#### Parameters
|
||||
|
||||
@ -3357,7 +3392,10 @@ $ curl \
|
||||
"auto_rebuild": false,
|
||||
"auto_rebuild_grace_period": "12h",
|
||||
"enable_delta": false,
|
||||
"delta_rebuild_interval": "15m"
|
||||
"delta_rebuild_interval": "15m",
|
||||
"cross_cluster_revocation": true,
|
||||
"unified_crl": true,
|
||||
"unified_crl_on_existing_paths": true
|
||||
},
|
||||
"auth": null
|
||||
}
|
||||
@ -3396,6 +3434,11 @@ the CRL.
|
||||
and delta CRLs only executes once a minute; this prevents high system load
|
||||
but limits the granularity of the temporal options below.
|
||||
|
||||
~> Note: The `unified_crl`, `unified_crl_on_existing_paths`, and
|
||||
`cross_cluster_revocation` parameters are all Vault Enterprise only
|
||||
functionality. While they appear in the responses on Vault OSS, they cannot
|
||||
be enabled.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :---------------- |
|
||||
| `POST` | `/pki/config/crl` |
|
||||
@ -3403,22 +3446,66 @@ the CRL.
|
||||
#### Parameters
|
||||
|
||||
- `expiry` `(string: "72h")` - The amount of time the generated CRL should be valid.
|
||||
|
||||
- `disable` `(bool: false)` - Disables or enables CRL building.
|
||||
|
||||
- `ocsp_disable` `(bool: false)` - Disables or enables the OCSP responder in Vault.
|
||||
|
||||
- `ocsp_expiry` `(string: "12h")` - The amount of time an OCSP response can be cached for,
|
||||
(controls the NextUpdate field), useful for OCSP stapling refresh durations. Setting to 0
|
||||
should effectively disable caching in third party systems.
|
||||
|
||||
- `auto_rebuild` `(bool: false)` - Enables or disables periodic rebuilding of
|
||||
the CRL upon expiry.
|
||||
|
||||
- `auto_rebuild_grace_period` `(string: "12h")` - Grace period before CRL expiry
|
||||
to attempt rebuild of CRL. Must be shorter than the CRL expiry period.
|
||||
|
||||
- `enable_delta` `(bool: false)` - Enables or disables building of delta CRLs
|
||||
with up-to-date revocation information, augmenting the last complete CRL.
|
||||
This option requires `auto_rebuild` to also be enabled.
|
||||
|
||||
- `delta_rebuild_interval` `(string: "15m")` - Interval to check for new
|
||||
revocations on, to regenerate the delta CRL. Must be shorter than CRL
|
||||
expiry.
|
||||
|
||||
- `cross_cluster_revocation` `(bool: false)` - Enable cross-cluster revocation
|
||||
request queues. When a serial not issued on this local cluster is presented
|
||||
to Vault via the [`/revoke` API](#revoke-certificate), it is replicated
|
||||
across clusters and the cluster which issued that certificate will revoke
|
||||
it if it is online.
|
||||
|
||||
~> Note: API calls to revoke a certificate with Bring Your Own Certificate
|
||||
(BYOC) will always trigger a local revocation of that certificate. No
|
||||
cross-cluster revocation request will be created.<br /><br />
|
||||
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.
|
||||
|
||||
~> Note: `cross_cluster_revocation` is a Vault Enterprise only feature.
|
||||
|
||||
- `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)
|
||||
cluster. Any node in any PR cluster will be able to serve this unified CRL
|
||||
and respond to unified OCSP inquiries.
|
||||
|
||||
~> Note: This option ensures existing, non-expired revocations are
|
||||
consistently reported. If a certificate was issued and stored on one
|
||||
cluster, but revoked via BYOC on another, this option will inform the
|
||||
issuing cluster of the revocation.
|
||||
|
||||
~> Note: `unified_crl` is a Vault Enterprise only feature.
|
||||
|
||||
- `unified_crl_on_existing_paths` `(bool: false)` - Enables serving the
|
||||
unified CRL and OCSP on the existing, previously cluster-local paths
|
||||
(e.g., `/pki/crl` will now contain the unified CRL when enabled). This
|
||||
allows transitioning AIA-based consumption of CRLs to a unified view
|
||||
without having to re-issue certificates or update scripts pulling the
|
||||
a single CRL.
|
||||
|
||||
~> Note: `unified_crl_on_existing_paths` is a Vault Enterprise only feature.
|
||||
|
||||
#### Sample Payload
|
||||
|
||||
```json
|
||||
@ -3431,6 +3518,9 @@ the CRL.
|
||||
"auto_rebuild_grace_period": "8h",
|
||||
"enable_delta": "true",
|
||||
"delta_rebuild_interval": "10m",
|
||||
"cross_cluster_revocation": true,
|
||||
"unified_crl": true,
|
||||
"unified_crl_on_existing_paths": true,
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user