luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Add suggested root rotation procedure (#19033) 

* Add suggested root rotation procedure

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Clarify docs heading

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

---------

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
This commit is contained in:
Alexander Scheel 2023-02-07 13:51:33 -05:00 committed by GitHub
parent 5e91770d51
commit 3f8aaedc2a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 53 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
website/content/docs/secrets/pki/rotation-primitives.mdx
View File

@ -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)