docs: Add docs for adding and rotating root keys (#389)

* docs: Add docs for adding and rotating root keys Signed-off-by: Marina Moore <[email protected]> * typo fix from review Signed-off-by: Marina Moore <[email protected]> Signed-off-by: Marina Moore <[email protected]>
theupdateframework · Sep 21, 2022 · 0e33cdf · 0e33cdf
1 parent f237d7c
commit 0e33cdf
Showing 1 changed file with 33 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -603,6 +603,39 @@ $ tree .
 └── staged
 ```
 
+#### Adding a new root key
+
+Copy `staged/root.json` to the root box and generate a new root key on the root box:
+
+```bash
+$ tuf gen-key root
+$ tuf sign root.json
+```
+
+Copy `staged/root.json` from the root box and commit:
+
+```bash
+$ tuf commit
+```
+
+#### Rotating root key(s)
+
+Copy `staged/root.json` to the root box to do the rotation, where `abcd` is the keyid of the key that is being replaced:
+
+```bash
+$ tuf gen-key root
+$ tuf revoke-key root abcd
+$ tuf sign root.json
+```
+
+Note that `revoke-key` removes the old key from `root.json`, but the key remains in the `keys/` directory on the root box as it is needed to sign the next `root.json`. After this signing is done, the old key may be removed from `keys/`. Any number of keys may be added or revoked during this step, but ensure that at least a threshold of valid keys remain.
+
+Copy `staged/root.json` from the root box to commit:
+
+```bash
+$ tuf commit
+```
+
 ## Client
 
 For the client package, see https://godoc.org/github.com/theupdateframework/go-tuf/client.