aboutsummaryrefslogtreecommitdiffstats

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, 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:

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.

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:

    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). 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, Who syncs).