diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration.md | 4 | ||||
| -rw-r--r-- | docs/federation-tests.md | 7 | ||||
| -rw-r--r-- | docs/federation.md | 47 | ||||
| -rw-r--r-- | docs/guides/federation/building-on-the-api.md | 8 | ||||
| -rw-r--r-- | docs/guides/federation/getting-started.md | 6 | ||||
| -rw-r--r-- | docs/guides/federation/keys.md | 31 | ||||
| -rw-r--r-- | docs/guides/federation/upgrades.md | 7 |
7 files changed, 86 insertions, 24 deletions
diff --git a/docs/configuration.md b/docs/configuration.md index d246082..989f268 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -256,4 +256,8 @@ record = "/home/tv/.config/continuum/tv.record" continuum-party --config tv.toml write home/tv/motd '"hello"' ``` +`key` is an OpenSSH private key file, or a public key an ssh-agent holds: the key itself +(`key = "ecdsa-sha2-nistp256 AAAA…"`), or a file of such lines, whose first signs +([`guides/federation/keys.md`](guides/federation/keys.md), Keys in an ssh-agent). + `node` and `token` are secrets: never logged, however they are given. diff --git a/docs/federation-tests.md b/docs/federation-tests.md index d7e4a43..ba182ad 100644 --- a/docs/federation-tests.md +++ b/docs/federation-tests.md @@ -29,7 +29,9 @@ built to: a stage is done when its tests are. ## The harness * **Keys.** Ed25519 keys made from seeds, signing as `ssh-keygen -Y sign` does; a vector - checks one signature against `ssh-keygen` itself. + checks one signature against `ssh-keygen` itself. An ECDSA key `ssh-keygen` made, and + events it signed with it, are vectors; a test signs through a running `ssh-agent`, and + `ssh-keygen -Y verify` checks what it signed: the machine testing needs OpenSSH. * **Events.** A builder for every kind (writes, key sets, node lists, proposals, votes, version events, checkpoints, roots and forks), each from a party, a key and its dependencies, encoded and signed as the design says; and for what is none: bytes that @@ -115,7 +117,8 @@ Vectors for: an event and its ID; an event whose value holds names JCS sorts by UTF-16 units otherwise than by their bytes (one from U+E000 to U+FFFF beside one beyond U+FFFF); events at federation 1's sizes and just past them; a signature, a version and its hash, a checkpoint and its ID, the genesis change of a federation's root and of a -fork's, and a snapshot after a checkpoint. A vector that changes is a change of the +fork's, a snapshot after a checkpoint, and a version naming an ECDSA key, with a write +and a key set `ssh-keygen` signed with it. A vector that changes is a change of the federation, which takes its next number ([`federation.md`](federation.md), Changing the federation). diff --git a/docs/federation.md b/docs/federation.md index 7b453af..5faa478 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -46,7 +46,8 @@ What an adversary can do: * delay or drop messages between any nodes, short of forever between honest ones; * steal another party's key. -What it can't: forge an Ed25519 signature, or find two byte strings with one SHA-256. +What it can't: forge an Ed25519 or ECDSA signature, or find two byte strings with one +SHA-256. Out of scope: keeping anything from being read (every party reads all of it), hiding who talks to whom, and a party's own machine taken over whole (then the adversary is that @@ -125,11 +126,12 @@ Spread out: * **`deps`**: the IDs of its dependencies, as 64 lower-case hex digits, one at least, ascending, none twice; a client gives the heads it read. -* **`party`** and **`key`**: the party that signs it, and the key it signs with: - `ssh-ed25519`, one space, and the key's base64, padded and canonical, with no comment, - its 32 bytes an Ed25519 public key. Keys in a version and a key set are spelled so - too, and node IDs as continuum spells them: `continuum:` and the 64 lower-case hex - digits of the node's Ed25519 public key. +* **`party`** and **`key`**: the party that signs it, and the key it signs with: its + type, one space, and the base64 of its SSH encoding, padded and canonical, with no + comment. Two types: `ssh-ed25519`, its 32 bytes an Ed25519 public key, and + `ecdsa-sha2-nistp256`, its point on NIST P-256 uncompressed. Keys in a version and a + key set are spelled so too, and node IDs as continuum spells them: `continuum:` and + the 64 lower-case hex digits of the node's Ed25519 public key. * **What it does**, one field of: * `write`, `{"path": "<path>", "value": <value>}`: a value at a place (The policy); * `keys`, `["<key>", …]`: the party's key set (Keys); @@ -141,9 +143,14 @@ Spread out: * **`sig`**: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`) over the event's bytes without `sig`: the SSHSIG blob of version 1, hashed with `sha512`, its key the event's `key`, its reserved field empty, as `ssh-keygen` writes - it, in base64, padded and canonical, unarmored. It is checked as continuum checks a - user's signature, strictly *(checked: `access::sshsig::verify_blob`)*, which takes - `sha256` too, and any reserved field: the federation asks `sha512` and an empty one. + it, in base64, padded and canonical, unarmored. An Ed25519 signature is checked as + continuum checks a user's signature, strictly *(checked: + `access::sshsig::verify_blob`)*, which takes `sha256` too, and any reserved field: the + federation asks `sha512` and an empty one. An ECDSA signature is over the SHA-256 of + what it signs, as SSH signs with such a key. Its `s` and the curve's order less `s` + both check, so the federation takes the low one alone, at most half the order, and `r` + and `s` each as SSH's shortest mpint *(checked: `federation::keys`)*. `ssh-keygen` + makes either; a party's client makes `s` low. Three things no party signs, as their bytes need no signer, each without `party`, `key` and `sig`: a version event (Changing the policy), and a federation's root and a fork's, @@ -193,12 +200,13 @@ current at its heads, Forks). Spread out: * **The federation** it follows, and its **number**, one more than that of the version it changes. * **The parties and their keys** (`keys`): one party at least, each by name, as - continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -`, with one `ssh-ed25519` key - or more, none twice in the version. With them the party signs its votes and proposals - on this version, its key set and its node list (Keys, Nodes). Its `since` is the - number of the version that named them anew: this one's where it does (a party new in - it, keys the parties replace, or the same keys named anew), else the `since` the - version it changes gives the party, whose keys it then names unchanged. + continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -`, with one key or more + (`ssh-ed25519` or `ecdsa-sha2-nistp256`, Events), none twice in the version. With them + the party signs its votes and proposals on this version, its key set and its node list + (Keys, Nodes). Its `since` is the number of the version that named them anew: this + one's where it does (a party new in it, keys the parties replace, or the same keys + named anew), else the `since` the version it changes gives the party, whose keys it + then names unchanged. * **The node lists** (`nodes`): every party's, a list of node IDs, none twice, with its `since` as keys have one. The version that lets a party in names its list anew, empty where it gives it no nodes, so that a list it wrote before it was taken out counts no @@ -691,7 +699,7 @@ crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | 59 | Two checkpoints proposed at once, by nodes voting by themselves | The votes split; nays from the nodes backing one make the other dead, and its backers are free | sim | | 60 | Two nodes of one party, each voting by itself | They can vote twice, answered as any party voting twice: a party has one node vote by itself | — | | 61 | A key a version names, kept on a node that votes by itself, stolen with it | As 23: it counts while that version is current | unit | -| 62 | A party's event spelled anew by another: its `sig` or `key` encoded otherwise, its signature's S not canonical, its blob naming another key | None: `key` and `sig` read back to themselves, the signature is checked strictly, and the blob's key is `key` | unit | +| 62 | A party's event spelled anew by another: its `sig` or `key` encoded otherwise, its signature's S not canonical (of ECDSA, the order less `s`, or `r` or `s` with zeros more in front), its blob naming another key | None: `key` and `sig` read back to themselves, the signature is checked strictly (of ECDSA, `s` low and `r` and `s` each its shortest), and the blob's key is `key` | unit | | 63 | A node joining from the root is shown a chain old keys grew, beside the one the others took | It takes neither, and reports; once a checkpoint passed, it joins from a pinned one, where that chain is refused | unit | | 64 | Checkpoint heads before the current checkpoint, or at which it isn't current, or one in another's history | No version: a version event naming it is refused | unit | | 65 | After a checkpoint, a party that backed a second proposal once its first was dead, the nays that freed it withheld by those who cast them | Not named: its client keeps those nays with its `true` | unit | @@ -786,6 +794,13 @@ moves to it by a version of its policy that names it (`"federation": 2`), which parties pass once their nodes run a continuum that knows it. A node that doesn't know the federation, or a version, its swarm has stops taking events and says so. +A change that only has the federation take what it refused, and reads nothing it took +otherwise, keeps the number: the keys of type `ecdsa-sha2-nistp256` taken beside Ed25519 +ones are such a change. It is rolled out first and used after: every node runs a +continuum that takes it before any party uses it. A node that doesn't refuses what uses +it, a version naming such a key among them, and reads otherwise than the others until +it does. + ## The registry on it The krebs registry today: users, their hosts, the hosts' names, addresses and keys, as diff --git a/docs/guides/federation/building-on-the-api.md b/docs/guides/federation/building-on-the-api.md index 9f144be..4f37b91 100644 --- a/docs/guides/federation/building-on-the-api.md +++ b/docs/guides/federation/building-on-the-api.md @@ -41,11 +41,13 @@ sorts them: * `deps`: the heads it read (`heads` in `GET /events`), each as 64 lower-case hex digits, ascending, one at least. -* `key`: the key it signs with, `ssh-ed25519`, a space, the base64 of its blob, no - comment; one of the party's keys. +* `key`: the key it signs with, its type (`ssh-ed25519` or `ecdsa-sha2-nistp256`), a + space, the base64 of its blob, no comment; one of the party's keys. * `sig`: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`, hashed with `sha512`) over the JCS bytes of the object without `sig`: the SSHSIG blob, its - reserved field empty, in base64, unarmored. + reserved field empty, in base64, unarmored. Of an ECDSA key, its `s` low, at most half + the curve's order: `ssh-keygen` makes a high one half the time, which no node takes; + sign again, or put the order less `s` in its place. * The value is any JSON with integers only, from −2⁵³ to 2⁵³; the event up to 256 KiB. Put its bytes as they are: diff --git a/docs/guides/federation/getting-started.md b/docs/guides/federation/getting-started.md index ce2b614..3570ee3 100644 --- a/docs/guides/federation/getting-started.md +++ b/docs/guides/federation/getting-started.md @@ -17,8 +17,10 @@ That builds the node, `continuum`, and the party's client, `continuum-party`, in ## A key for each party -The version names each party's keys, and the party signs with them. The client reads an -OpenSSH Ed25519 key without a passphrase: +The version names each party's keys, and the party signs with them. A key is +`ssh-ed25519` or `ecdsa-sha2-nistp256`. The client reads an OpenSSH private key file +without a passphrase, of an Ed25519 key, or signs through an ssh-agent holding the key +([`keys.md`](keys.md), Keys in an ssh-agent): ```sh ssh-keygen -t ed25519 -N '' -f tv.key diff --git a/docs/guides/federation/keys.md b/docs/guides/federation/keys.md index 48018a3..3dd2834 100644 --- a/docs/guides/federation/keys.md +++ b/docs/guides/federation/keys.md @@ -25,12 +25,41 @@ continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \ 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. +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 diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index 945088d..95dab12 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -32,3 +32,10 @@ naming another is taken as a proposal, and a party's client backs none. A change to any of that is a federation of its own, with the next number, and its own design. A swarm moves to it by a version naming it, which the parties pass once their nodes run a continuum that knows it. + +A change that only has the federation take what it refused, and reads nothing it took +otherwise, keeps the number: `ecdsa-sha2-nistp256` keys beside Ed25519 ones. Roll it out +first, then use it: every party's operators upgrade their nodes, and only then does a +party name such a key in a version or a key set, or sign with one. A node not upgraded +refuses what uses it and reads otherwise than the others: a version naming such a key is +none to it, and it stays on the version before. |
