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.
DO NOT DELETE older keys until the key rotation is complete. You will require a threshold of signatures from the previous set of keys to maintain the chain of trust when deploying the N+1.root.json metadata.
In order to meet thresholds, you may need signatures from old keys that have
been removed. For example, if your root key threshold is 2 (the default), and
you need to rotate both keys, then you need to ensure that your n+1.root.json
includes signatures from 2 of the “old” keys (present in n.root.json) as
well as signatures from 2 of the “new” keys (those newly present in
n+1.root.json).
See Section 5.3.4 and Section 6.1 for more details.
Rotating online keys is generally simpler, since we don’t need to keep older
keys. We can incorporate newly generated online keys into a new n+1.root.json
metadata file, and they can immediately provide signatures for their role
metadata. Note that we still need to complete a full ceremony to update the
Root metadata in this scenario.
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.