diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index cd280b138d..b138361cff 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -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 diff --git a/website/content/docs/secrets/pki/considerations.mdx b/website/content/docs/secrets/pki/considerations.mdx index 9bdbed75bd..42b9091489 100644 --- a/website/content/docs/secrets/pki/considerations.mdx +++ b/website/content/docs/secrets/pki/considerations.mdx @@ -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