From ab290d33b2f5b53d40326936e78bde43aefd86ea Mon Sep 17 00:00:00 2001
From: Marina Moore <mnm678@gmail.com>
Date: Tue, 20 Sep 2022 15:47:11 -0400
Subject: [PATCH] docs: Add docs for adding and rotating root keys

Signed-off-by: Marina Moore <mnm678@gmail.com>
---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index b1a4b6ea..9a055603 100644
--- 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 to 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.