1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
# 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`), an Ed25519 key in a file: 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.
## Keys in an ssh-agent
A key no file holds, in a security key, a phone or a Secure Enclave, signs through an
ssh-agent. Give the client its public key, a `.pub` file, as `--key`: it asks the agent
at `SSH_AUTH_SOCK` to sign, and writes the signature as `ssh-keygen -Y sign` does
through that agent. Such a key is `ecdsa-sha2-nistp256` or `ssh-ed25519`.
```sh
ssh-add -L # ecdsa-sha2-nistp256 AAAA… tv@phone
ssh-add -L | grep tv@phone > phone.pub
cut -d' ' -f1,2 phone.pub # the key as a version or a set names it
continuum-party --node http://tv:secret@localhost:3000 --key phone.pub \
--record tv.record write home/tv/motd '"from the phone"'
```
Of an ECDSA signature, `s` and the curve's order less `s` both check. The federation
takes the low one alone, so that nobody makes another event of what the party signed;
the client makes `s` low, whichever the agent gives.
## 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).
|