diff --git a/website/content/docs/secrets/pki/considerations.mdx b/website/content/docs/secrets/pki/considerations.mdx index 3a97016c9..bc8eff240 100644 --- a/website/content/docs/secrets/pki/considerations.mdx +++ b/website/content/docs/secrets/pki/considerations.mdx @@ -72,6 +72,16 @@ by the HSM and one backed by Vault -- can satisfy both use cases. Operators can make roles setting maximum TTLs for each issuer and consumers of the mount can decide which to use. +### Always Configure a Default Issuer + +For backwards compatibility, [the default issuer](/api-docs/secret/pki#read-issuers-configuration) +is used to service PKI endpoints without an explicit issuer (either via path +selection or role-based selection). When certificates are revoked and their +issuer is no longer part of this PKI mount, Vault places them on the default +issuer's CRL. This means maintaining a default issuer is important for both +backwards compatibility for issuing certificates and for ensuring revoked +certificates land on a CRL. + ## Use a CA Hierarchy It is generally recommended to use a hierarchical CA setup, with a root @@ -154,6 +164,30 @@ range of 30 to 90 days), and the [rotation strategies discussed in other sections](/docs/secrets/pki/rotation-primitives), this should keep the CRLs adequately small. +### Cluster Performance and Quantity of Leaf Certificates + +As mentioned above, keeping TTLs short (or using `no_store=true`, preventing +revocation) and avoiding leases is important for a healthy cluster. However +it is important to note this is a scale problem: 10-1000 long-lived, stored +certificates are probably fine, but 50k-100k become a problem and 500k+ +stored, unexpired certificates can negatively impact even large Vault +clusters--even with short TTLs! + +However, once these certificates are expired, a [tidy operation](/api-docs/secret/pki#tidy) +will clean up CRLs and Vault cluster storage. + +Note that organizational risk assessments for certificate compromise might +mean certain certificate types should always be issued with `no_store=false`; +even short-lived broad wildcard certificates (say, `*.example.com`) might be +important enough to have precise control over revocation. However, an internal +service with a well-scoped certificate (say, `service.example.com`) might be +of low enough risk to issue a 90-day TTL with `no_store=true`, preventing +the need for revocation in the unlikely case of compromise. + +Having a shorter TTL decreases the likelihood of needing to revoke a cert +(but cannot prevent it entirely) and decrease the impact of any such +compromise. + ## You must configure issuing/CRL/OCSP information _in advance_ This secrets engine serves CRLs from a predictable location, but it is not @@ -163,6 +197,22 @@ OCSP servers manually using the `config/urls` endpoint. It is supported to have more than one of each of these by passing in the multiple URLs as a comma-separated string parameter. +~> Note: when using Vault Enterprise's Performance Replication features with a + PKI Secrets Engine mount, each cluster will have its own CRL; this means + each cluster's unique CRL address should be included in the [AIA + information](https://datatracker.ietf.org/doc/html/rfc5280#section-5.2.7) + field separately, or the CRLs should be consolidated and served outside of + Vault. + +## 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](/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