diff --git a/website/content/docs/secrets/pki/considerations.mdx b/website/content/docs/secrets/pki/considerations.mdx index 0359423978..cf395360dc 100644 --- a/website/content/docs/secrets/pki/considerations.mdx +++ b/website/content/docs/secrets/pki/considerations.mdx @@ -73,6 +73,14 @@ recommended that operators limit a mount to a single issuer. If you want to issu certificates from multiple disparate CAs, mount the PKI secrets engine at multiple mount points with separate CA certificates in each. +The rationale for separating mounts is to simplify permissions management: +very few individuals need access to perform operations with the root, but +many need access to create leaves. The operations on a root should generally +be limited to issuing and revoking intermediate CAs, which is a highly +privileged operation; it becomes much easier to audit these operations when +they're in a separate mount than if they're mixed in with day-to-day leaf +issuance. + A common pattern is to have one mount act as your root CA and to use this CA only to sign intermediate CA CSRs from other PKI secrets engines. @@ -175,13 +183,12 @@ store generated private keys, except for CA certificates). In most cases, if the key is lost, the certificate can simply be ignored, as it will expire shortly. If a certificate must truly be revoked, the normal Vault revocation function can -be used; alternately a root token can be used to revoke the certificate using -the certificate's serial number. Any revocation action will cause the CRL to be -regenerated. When the CRL is regenerated, any expired certificates are removed -from the CRL (and any revoked, expired certificate are removed from secrets -engine storage). This is an expensive operation! Due to the structure of the -CRL standard, Vault must read **all** revoked certificates into memory in order -to rebuild the CRL and clients must fetch the regenerated CRL. +be used, and any revocation action will cause the CRL to be regenerated. When +the CRL is regenerated, any expired certificates are removed from the CRL (and +any revoked, expired certificate are removed from secrets engine storage). This +is an expensive operation! Due to the structure of the CRL standard, Vault must +read **all** revoked certificates into memory in order to rebuild the CRL and +clients must fetch the regenerated CRL. This secrets engine does not support multiple CRL endpoints with sliding date windows; often such mechanisms will have the transition point a few days apart, @@ -202,6 +209,16 @@ is down. This is again a rationale for keeping TTLs short and avoiding revocation if possible. +~> Note: Since Vault 1.12.0, we support two complementary revocation + mechanisms: Delta CRLs, which allow for rebuilds of smaller, incremental + additions to the last complete CRL, and OCSP, which allows responding to + revocation status requests for individual certificates. When coupled with + the new CRL auto-rebuild functionality, this means that the revoking step + isn't as costly (as the CRL isn't always rebuilt on each revocation), + outside of storage considerations. However, while the rebuild operation + still can be expensive with lots of certificates, it will be done on a + schedule rather than on demand. + ### NotAfter Behavior on Leaf Certificates In Vault 1.11.0, the PKI Secrets Engine has introduced a new