From 3083f755f34931eda27ae319b6876af108c6ed55 Mon Sep 17 00:00:00 2001 From: Alexander Scheel Date: Fri, 3 Feb 2023 16:30:23 -0500 Subject: [PATCH] Document Cross-Cluster CRLs/OCSP for Vault Enterprise (#18970) * Add documentation on fetching unified CRLs Signed-off-by: Alexander Scheel * Add documentation on unified OCSP Signed-off-by: Alexander Scheel * Clarify that OCSP requests need to be URL encoded Signed-off-by: Alexander Scheel * Document new CRL config parameters Signed-off-by: Alexander Scheel * Clarify notes about cross-cluster options Co-authored-by: Steven Clark Signed-off-by: Alexander Scheel --------- Signed-off-by: Alexander Scheel Co-authored-by: Steven Clark --- website/content/api-docs/secret/pki.mdx | 138 +++++++++++++++++++----- 1 file changed, 114 insertions(+), 24 deletions(-) diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index cab7701907..61379e5496 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -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/` | 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/` | 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/` | 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.

+ 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, } ```