In the event of a key being compromised, or when a key approaches its expiry date, we need to be able to rotate the old key(s) out of use to be replaced with a newly-generated one.
As with your initial deployment, you must ensure you have reviewed and executed the Ceremony preparation steps to ensure the resulting TUF repository is trustworthy.
The process of rotating a root key is very similar to that for generating root
keys during the initial deployment. The important
difference is that because the TUF repository is already in operation, care
must be taken to retain the integrity of the system, respecting the threshold
of root key signatures required by your configuration.
For example, if your root key threshold is 2 (the default), and you need to
rotate both keys, you should perform the ceremony below at least twice: first
to add the new root keys (deploying n+1.root.json), and then a second time
to remove the old ones (deploying n+2.root.json). This ensures that the TUF
repository remains valid throughout. If we were to remove all the existing keys
at the same time as adding new ones, this would break the integrity of the
chain of root metadata files, and thus the validity of the TUF repository
itself.
Rotating online keys is generally simpler, since the Rugged system can re-sign the required metadata automatically, as it does regularly to refresh the expiry times on all the online roles (targets, timestamp, snapshot) already.
Note that you may also perform a key rotation ceremony without rotating any
keys at all. This is useful when your existing N.root.json is nearing expiry,
but your keys are still secure and valid, and you have no need to rotate keys.
To do so, simply omit generating any new keys, initialize and sign a new
partial root metadata for deployment.
Having prepared a secure environment and created a ceremony folder to hold the resulting artifacts, the high-level steps are:
This part of the process is exactly as it was during the initial deployment, where the relevant keyholders will use a ceremony computer (again, this is ideally an airgapped workstation) to generate a fresh root keypair, and then share the verification key with the ceremony coordinator.
In most cases, if you need to generate Root keys, we suggest you also rotate the online keys for the Targets, Timestamp, and Snapshot roles. You may also need to rotate these if you suspect a compromise, or the expiry date for one of these keys is imminent.
The process for rotating online keys is deliberately undocumented for the time being, due to it being confusing and error-prone. This will be revised once we complete #184: Rotate an online key.
Once the ceremony coordinator has collected any new root verification keys
from keyholders, we can prepare and sign the next version of the root metadata
for the TUF repository (eg. 2.root.json). This process consists of:
rugged commands to add and remove verification keys, and prepare a new “signable” partial root metadata file to be signed by keyholders.N+1.root.json, the next version of the live root metadata file.As before, once the ceremony coordinator has created the updated root metadata file, they need to deploy it into the TUF repository. This requires pausing Rugged’s processing of new targets temporarily, then deploying the updated root metadata and triggering the re-signing of the other metadata roles, before resuming processing.