aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/keys.md
blob: 7f5bd7ac00452299656ebd41c327dc93f4faba34 (plain)
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
106
107
108
109
110
111
112
113
114
115
116
117
118
# 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 --set "$(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.
`--set` writes the set whole; `--add` and `--remove` write it as it counts at the node,
with those keys added or taken off (`keys --add "$(cat phone.pub)"`); `keys` alone shows
it. A set left empty, so that none of the party's writes count, is written with
`--force` only. A set holds up to 16 keys, signed with a key the current version names
for the party, which the client checks first. 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 signs through an ssh-agent holding it: a smartcard's or a security
key's PIV key, which the agent reaches through PKCS#11 (`ssh-add -s`), or a key in a
Secure Enclave or a phone, held by an agent there. Such a key is `ecdsa-sha2-nistp256` or
`ssh-ed25519`. A security key's FIDO key (`ssh-keygen -t ecdsa-sk` or `-t ed25519-sk`,
its type ending in `@openssh.com`) is neither: it signs otherwise than the federation
takes, and is no party's key.

Give the client its public key as `--key`, the key itself (an `authorized_keys` line) or
a file holding it: it asks the agent at `SSH_AUTH_SOCK` to sign, and writes the signature
as `ssh-keygen -Y sign` does through that agent. Of a file holding several keys (all
`ssh-add -L` lists, say), the first signs, and the client warns: give another itself to
sign with it. An agent that doesn't hold the key given signs nothing, and the client stops
before it records or puts what it would have signed.

```sh
ssh-add -L                                # ecdsa-sha2-nistp256 AAAA… tv@phone
ssh-add -L | grep tv@phone | cut -d' ' -f1,2   # the key as a version or a set names it
continuum-party --node http://tv:secret@localhost:3000 \
  --key "$(ssh-add -L | grep tv@phone)" --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. Add the new keys to the set, beside the old (`keys --add`).
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. Take the old keys off the set (`keys --remove`).

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).