aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:08:24 +0000
committertv <tv@krebsco.de>2026-11-17 14:23:18 +0100
commit98e8df4ab87f0f4fe0752d2c144b49ea0be1151c (patch)
treebc1ffb12e89f41e0bb51a48af0f47bec4624508e /docs
parentc3b5bd694333d69b6cc88f229c0e80833ab64cf9 (diff)
guides: a federated party's keys
The keys a version names, kept apart with the party's record, and those of its key set, signing its writes; changing a set and signing again what should stay; changing the keys a version names; a stolen key of either kind; and the node key, which is no party's.
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/keys.md85
2 files changed, 87 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index 690d0ad..369ac62 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -12,3 +12,5 @@ by them, in its words.
a write is refused, and signing again after a move.
* [`proposing-and-voting.md`](proposing-and-voting.md): writing a version, proposing it,
voting by a record, and when a proposal passes or dies.
+* [`keys.md`](keys.md): the keys a version names and those of a key set, changing them,
+ and a stolen key.
diff --git a/docs/guides/federation/keys.md b/docs/guides/federation/keys.md
new file mode 100644
index 0000000..48018a3
--- /dev/null
+++ b/docs/guides/federation/keys.md
@@ -0,0 +1,85 @@
+# Keys
+
+A party has two kinds of keys: those its version names, and those of its key set. The
+rules are the design's ([`federation.md`](../../federation.md), Keys); this guide says
+how to keep them, change them, and what to do when one is stolen.
+
+## The two kinds
+
+* **The keys a version names** vote, propose, and sign the party's key set and node list.
+ Only a version changes them, so changing them takes the parties' votes.
+* **The keys of its key set** sign everything else: its writes. The party changes its set
+ by itself, signing it with a key its version names. While it has written none, the
+ keys its version names sign its writes too.
+
+So keep the keys a version names apart, offline, on one machine with the party's record
+(votes go by it), and sign day-to-day writes with a key of the set on each device:
+
+```sh
+ssh-keygen -t ed25519 -N '' -f laptop.key
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ keys "$(cat laptop.key.pub)" "$(cat desk.key.pub)"
+continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \
+ --record tv.record write home/tv/motd '"from the laptop"'
+```
+
+Each key goes as one argument, an `authorized_keys` line; its comment is left out. A
+set holds up to 16 keys. A node voting by itself keeps a key its version names on that
+node (`--store-vote-key`): one stolen there votes for the party.
+
+A set counts where it is written under a version numbered at least the `since` the
+current version gives the party's keys: once a version names a party's keys anew, no set
+written before counts, and the party writes its set again.
+
+## Changing the keys of a set
+
+A write counts only while the key that signed it is among the party's keys: what a key
+signed counts no more once the party's set drops it, wherever in history it is. So
+before dropping a key, sign again with a new one what should stay:
+
+1. Write a set with the new keys beside the old.
+2. Write again, with a new key, every value the party wants kept, on heads that hold that
+ set (the client signs on the heads its node shows). For a namespace:
+
+ ```sh
+ curl -s -u tv:secret localhost:3000/events/counts |
+ jq -c '.values | to_entries[] | select(.key | startswith("home/tv/"))' |
+ while read -r entry; do
+ continuum-party --node http://tv:secret@localhost:3000 --key desk.key \
+ --record tv.record write "$(jq -r .key <<<"$entry")" "$(jq -c .value <<<"$entry")"
+ done
+ ```
+
+3. Write a set without the old keys.
+
+A key added back, from a backup say, brings back what it signed, where nothing the party
+signed since replaced it and no checkpoint left it out.
+
+## Changing the keys a version names
+
+A party proposes a version naming its keys anew (`since` that version's number), and the
+parties vote ([`proposing-and-voting.md`](proposing-and-voting.md)). Its votes and
+proposals use the new keys from that version on; its set written before counts no more,
+so it writes its set again, with the new version keys.
+
+A version naming a party's keys gives them as the version it changes gives them, `since`
+unchanged, unless naming them anew is the point: a `since` moved by mistake makes every
+set that party wrote count no more.
+
+## A stolen key
+
+* **A key of the set**: write a set without it, signed with a key the version names. No
+ vote needed: what the stolen key signed counts no more, wherever it is. Then sign again
+ what it signed that should stay, with a key of the new set.
+* **A key the version names**: only a version revokes it. Until one does, the thief votes,
+ proposes, and writes the party's set and node list as the party. Ask the other parties
+ to pass a version naming the party's keys anew, at once; then write the party's set and
+ node list under it, as a list the thief wrote stays until the party writes one under
+ the version that replaced the key. If the thief voted twice meanwhile, nodes may have
+ taken two versions: the parties answer that by forking.
+
+## The node key
+
+A node's own key (`--node-key-file`) is no party's: it is the node, the node ID its party
+lists. A stolen node key is a node the party takes off its list
+([`running-a-node.md`](running-a-node.md), Who syncs).