mirror of
https://github.com/hashicorp/vault.git
synced 2026-06-10 17:32:29 -04:00
Add notes on cross cluster CRLs (#18986)
* Group CRL related sections Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Fix casing Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add notes about cluster size and revocation Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Apply suggestions from code review Thanks Yoko! Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> --------- Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>
This commit is contained in:
Alexander Scheel
GitHub
parent
576c12e2ec
commit
acef4c2800
2 changed files with 70 additions and 24 deletions
|
|
@ -71,7 +71,7 @@ update your API calls accordingly.
|
|||
- [Set CRL Configuration](#set-crl-configuration)
|
||||
- [Rotate CRLs](#rotate-crls)
|
||||
- [Rotate Delta CRLs](#rotate-delta-crls)
|
||||
- [Combining CRLs from the same Issuer](#combine-crls-from-the-same-issuer)
|
||||
- [Combining CRLs from the Same Issuer](#combine-crls-from-the-same-issuer)
|
||||
- [Sign Revocation List](#sign-revocation-list)
|
||||
- [Tidy](#tidy)
|
||||
- [Configure Automatic Tidy](#configure-automatic-tidy)
|
||||
|
|
@ -3446,7 +3446,7 @@ $ curl \
|
|||
}
|
||||
```
|
||||
|
||||
### Combine CRLs From The Same Issuer
|
||||
### Combine CRLs from the Same Issuer
|
||||
|
||||
This endpoint allows combining multiple different CRLs that have been signed by the
|
||||
same issuer into a single signed CRL. This is useful to generate a single authoritative
|
||||
|
|
|
|||
|
|
@ -25,8 +25,9 @@ generating the CA to use with this secrets engine.
|
|||
- [Cluster Performance and Quantity of Leaf Certificates](#cluster-performance-and-quantity-of-leaf-certificates)
|
||||
- [You must configure issuing/CRL/OCSP information _in advance_](#you-must-configure-issuingcrlocsp-information-_in-advance_)
|
||||
- [Distribution of CRLs and OCSP](#distribution-of-crls-ocsp)
|
||||
- [Automate Leaf Certificate Renewal](#automate-leaf-certificate-renewal)
|
||||
- [Automate CRL Building and Tidying](#automate-crl-building-and-tidying)
|
||||
- [Issuer Subjects and CRLs](#issuer-subjects-and-crls)
|
||||
- [Automate Leaf Certificate Renewal](#automate-leaf-certificate-renewal)
|
||||
- [Safe Minimums](#safe-minimums)
|
||||
- [Token Lifetimes and Revocation](#token-lifetimes-and-revocation)
|
||||
- [Safe Usage of Roles](#safe-usage-of-roles)
|
||||
|
|
@ -36,7 +37,6 @@ generating the CA to use with this secrets engine.
|
|||
- [Replicated DataSets](#replicated-datasets)
|
||||
- [Cluster Scalability](#cluster-scalability)
|
||||
- [PSS Support](#pss-support)
|
||||
- [Issuer Subjects and CRLs](#issuer-subjects-and-crls)
|
||||
- [Issuer Storage Migration Issues](#issuer-storage-migration-issues)
|
||||
|
||||
## Be Careful with Root CAs
|
||||
|
|
@ -300,15 +300,6 @@ OCSP responses are signed by the issuing CA within Vault). This means both are
|
|||
fine to distribute over non-secure and non-authenticated channels, such as
|
||||
HTTP.
|
||||
|
||||
## Automate Leaf Certificate Renewal
|
||||
|
||||
As much as possible, for managing certificates for services at scale, it is
|
||||
best to automate renewal of certificates. Vault agent [has support for
|
||||
automatically renewing requested certificates](/vault/docs/agent/template#certificates)
|
||||
based on the `validTo` field. Other solutions might involve using
|
||||
[cert-manager](https://cert-manager.io/) in Kubernetes or OpenShift, backed
|
||||
by the Vault CA.
|
||||
|
||||
## Automate CRL Building and Tidying
|
||||
|
||||
Since Vault 1.12, the PKI Secrets Engine supports automated CRL rebuilding
|
||||
|
|
@ -318,6 +309,72 @@ revoked and expired certificates can be configured automatically via the
|
|||
`/config/auto-tidy` endpoint. Both of these should be enabled to ensure
|
||||
compatibility with the wider PKIX ecosystem and performance of the cluster.
|
||||
|
||||
## Spectrum of Revocation Support
|
||||
|
||||
Starting with Vault 1.13, the PKI secrets engine has the ability to support a
|
||||
spectrum of cluster sizes and certificate revocation quantities.
|
||||
|
||||
For users with few revocations or who want a unified view and have the
|
||||
inter-cluster bandwidth to support it, we recommend turning on auto
|
||||
rebuilding of CRLs, cross-cluster revocation queues, and cross-cluster CRLs.
|
||||
This allows all consumers of the CRLs to have the most accurate picture of
|
||||
revocations, regardless of which cluster they talk to.
|
||||
|
||||
If the unified CRL becomes too big for the underlying storage mechanism or
|
||||
for a single host to build, we recommend relying on OCSP instead of CRLs.
|
||||
These have much smaller storage entries, and the CRL `disabled` flag is
|
||||
independent of `unified_crls`, allowing unified OCSP to remain.
|
||||
|
||||
However, when cross-cluster traffic becomes too high (or if CRLs are still
|
||||
necessary in addition to OCSP), we recommend sharding the CRL between
|
||||
different clusters. This has been the default behavior of Vault, but with
|
||||
the introduction of per-cluster, templated AIA information, the leaf
|
||||
certificate's Authority Information Access (AIA) info will point directly
|
||||
to the cluster which issued it, allowing the correct CRL for this cert to
|
||||
be identified by the application. This more correctly mimics the behavior
|
||||
of [Let's Encrypt's CRL sharding](https://letsencrypt.org/2022/09/07/new-life-for-crls.html).
|
||||
|
||||
This sharding behavior can also be used for OCSP, if the cross-cluster
|
||||
traffic for revocation entries becomes too high.
|
||||
|
||||
For users who wish to manage revocation manually, using the audit logs to
|
||||
track certificate issuance would allow an external system to identify which
|
||||
certificates were issued. These can be manually tracked for revocation, and
|
||||
a [custom CRL can be built](/vault/api-docs/secret/pki#combine-crls-from-the-same-issuer)
|
||||
using externally tracked revocations. This would allow usage of roles set to
|
||||
`no_store=true`, so Vault is strictly used as an issuing authority and isn't
|
||||
storing any certificates, issued or revoked. For the highest of revocation
|
||||
volumes, this could be the best option.
|
||||
|
||||
Notably, this last approach can either be used for the creation of externally
|
||||
stored unified or sharded CRLs. If a single external unified CRL becomes
|
||||
unreasonably large, each cluster's certificates could have AIA info point
|
||||
to an externally stored and maintained, sharded CRL. However,
|
||||
Vault has no mechanism to sign OCSP requests at this time.
|
||||
|
||||
## Issuer Subjects and CRLs
|
||||
|
||||
As noted on several [GitHub issues](https://github.com/hashicorp/vault/issues/10176),
|
||||
Go's x509 library has an opinionated parsing and structuring mechanism for
|
||||
certificate's Subjects. Issuers created within Vault are fine, but when using
|
||||
externally created CA certificates, these may not be parsed
|
||||
correctly throughout all parts of the PKI. In particular, CRLs embed a
|
||||
(modified) copy of the issuer name. This can be avoided by using OCSP to
|
||||
track revocation, but note that performance characteristics are different
|
||||
between OCSP and CRLs.
|
||||
|
||||
~> Note: As of Go 1.19 and Vault 1.12, Go correctly formats the CRL's issuer
|
||||
name and this notice does not apply.
|
||||
|
||||
## Automate Leaf Certificate Renewal
|
||||
|
||||
To manage certificates for services at scale, it is best to automate the
|
||||
certificate renewal as much as possible. Vault Agent [has support for
|
||||
automatically renewing requested certificates](/vault/docs/agent/template#certificates)
|
||||
based on the `validTo` field. Other solutions might involve using
|
||||
[cert-manager](https://cert-manager.io/) in Kubernetes or OpenShift, backed
|
||||
by the Vault CA.
|
||||
|
||||
## Safe Minimums
|
||||
|
||||
Since its inception, this secrets engine has enforced SHA256 for signature
|
||||
|
|
@ -638,17 +695,6 @@ certain KMS devices (like HSMs and GCP) may not support this with the
|
|||
same key. As a result, the OCSP responder may fail to sign responses,
|
||||
returning an internal error.
|
||||
|
||||
## Issuer Subjects and CRLs
|
||||
|
||||
As noted on several [GitHub issues](https://github.com/hashicorp/vault/issues/10176),
|
||||
Go's x509 library has an opinionated parsing and structuring mechanism for
|
||||
certificate's Subjects. Issuers created within Vault are fine, but when using
|
||||
externally created CA certificates, note that these may not be parsed
|
||||
correctly throughout all parts of the PKI. In particular, CRLs embed a
|
||||
(modified) copy of the issuer name. This can be avoided by using OCSP to
|
||||
track revocation, but note that performance characteristics are different
|
||||
between OCSP and CRLs.
|
||||
|
||||
## Issuer Storage Migration Issues
|
||||
|
||||
When Vault migrates to the new multi-issuer storage layout on releases prior
|
||||
|
|
|
|||
Loading…
Reference in a new issue