From 3f8aaedc2a97de2b5f348a898759ab3f40838a53 Mon Sep 17 00:00:00 2001 From: Alexander Scheel Date: Tue, 7 Feb 2023 13:51:33 -0500 Subject: [PATCH] Add suggested root rotation procedure (#19033) * Add suggested root rotation procedure Signed-off-by: Alexander Scheel * Clarify docs heading Signed-off-by: Alexander Scheel --------- Signed-off-by: Alexander Scheel --- .../docs/secrets/pki/rotation-primitives.mdx | 54 ++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/website/content/docs/secrets/pki/rotation-primitives.mdx b/website/content/docs/secrets/pki/rotation-primitives.mdx index e2f6dda01..066f3bb7b 100644 --- a/website/content/docs/secrets/pki/rotation-primitives.mdx +++ b/website/content/docs/secrets/pki/rotation-primitives.mdx @@ -167,7 +167,7 @@ Note that, due to restrictions in how end-entity certificates are used and validated (services and validation libraries expect only one), cross-signing most typically only applies to intermediate. -#### Cross-Signed Roots +#### A Note on Cross-Signed Roots Technically, cross-signing can occur between two roots, allowing trust bundles with either root to validate certs issued through the other. However, this @@ -177,6 +177,9 @@ Given this restriction, it's preferable to instead cross-sign the top-level intermediates under the root unless strictly necessary when the old root certificate has been used to directly issue leaf certificates. +So, the rest of this process flow assumes an intermediate is being +cross-signed as this is more common. + ##### Process Flow ``` @@ -431,6 +434,55 @@ CA with that serial. This does not work when using a reissuance primitive as the are technically the same authority and thus this authority must issue certificates with unique serial numbers. +## Suggested Root Rotation Procedure + +The following is a suggested process for achieving root rotation easily and +without (outage) impact to the broader organization, assuming [best +practices](/vault/docs/secrets/pki/considerations#use-a-ca-hierarchy) are +being followed. Some adaption will be necessary. + +Note that this process takes time. How much time is dependent on the +automation level and operational awareness of the organization. + +1. [Generate](/vault/api-docs/secret/pki#generate-root) the new root + certificate. For clarity, it is suggested to use a new common name + to distinguish it from the old root certificate. Key material need + not be the same. + +2. [Cross-sign](#cross-signed-primitive) all existing intermediates. + It is important to update the manual chain on the issuers as discussed + in that section, as we assume servers are configured to combine the + `certificate` field with the `ca_chain` field on renewal and issuance, + thus getting the cross-signed intermediates. + +3. Encourage rotation to pickup the new cross-signed intermediates. With + short-lived certificates, this should [happen + automatically](/vault/docs/secrets/pki/considerations#automate-leaf-certificate-renewal). + However, for some long-lived certs, it is suggested to rotate them + manually and proactively. This step takes time, and depends on the + types of certificates issued (e.g., server certs, code signing, or client + auth). + +4. Once _all_ chains have been updated, new systems can be brought online + with only the new root certificate, and connect to all existing systems. + +5. Existing systems can now be migrated with a one-shot root switch: the + new root can be added and the old root can be removed at the same time. + Assuming the above step 3 can be achieved in a reasonable amount of time, + this decreases the time it takes to move the majority of systems over to + fully using the new root and no longer trusting the old root. This step + also takes time, depending on how quickly the organization can migrate + roots and ensure all such systems are migrated. If some systems are + offline and only infrequently online (or, if they have hard-coded + certificate stores and need to reach obsolescence first), the organization + might not be ready to move on to future steps. + +6. At this point, since all systems now use the new root, it is safe to remove + or archive the old root and intermediates, updating the manual chain to + point strictly to the new intermediate+root. + +At this point, rotation is fully completed. + ## Tutorial Refer to the [Build Your Own Certificate Authority (CA)](/vault/tutorials/secrets-management/pki-engine)