diff options
Diffstat (limited to 'docs/access.md')
| -rw-r--r-- | docs/access.md | 160 |
1 files changed, 82 insertions, 78 deletions
diff --git a/docs/access.md b/docs/access.md index 71725e2..7c6c7e6 100644 --- a/docs/access.md +++ b/docs/access.md @@ -33,16 +33,16 @@ password hashes: every member reads the document). doesn't read is left out, and anything but `false` disables. * **`keys`**: the user's SSH keys, each by a name of its choosing, as an `authorized_keys` line has it (`"laptop": "ssh-ed25519 AAAA… alice@laptop"`; Ed25519 - only; the comment, 256 bytes at most, is kept and checks nothing): what it signs values with (Values signed by their users, below) and logs in with. A user - manages its own, whatever else it may do: `GET /auth/keys`, `PUT /auth/keys/<name>` - with the line, `DELETE /auth/keys/<name>` (not with a token that has a `limit`); under a - strict policy, by signing its - entry with only its keys changed (`continuum-signed key-add laptop - ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a key it holds already. Every - node takes that from the user itself, as from one who may manage users. Its last key - it removes only on a node where it has a password (`--htpasswd`), which it logs in - by then (`409` elsewhere); under a strict policy, never (it signs its entry with - one). + only; the comment, 256 bytes at most, is kept and checks nothing): what it signs values + with ([Values signed by their users](#values-signed-by-their-users), below) and logs in + with. A user manages its own, whatever else it may do: `GET /auth/keys`, + `PUT /auth/keys/<name>` with the line, `DELETE /auth/keys/<name>` (not with a token that + has a `limit`); under a strict policy, by signing its entry with only its keys changed + (`continuum-signed key-add laptop ~/.ssh/id_ed25519.pub`, `key-remove laptop`), with a + key it holds already. Every node takes that from the user itself, as from one who may + manage users. Its last key it removes only on a node where it has a password + (`--htpasswd`), which it logs in by then (`409` elsewhere); under a strict policy, never + (it signs its entry with one). ## A new swarm @@ -52,16 +52,17 @@ everything (`[]` and `["_continuum"]`). Other users, of its `--htpasswd` or any may do nothing until added (the genesis node warns of those of its `--htpasswd`). With `--bootstrap-keys alice=ssh-ed25519\ AAAA…\ laptop` it records their keys too, so they log in by key and sign values from the start, and with -`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy (Values signed by -their users, below) in the same change: the swarm is strict from its start, and no -change of it is from before the policy. So it starts empty: content (`--genesis ---remake`) would be a change of its own before that one, and is refused with a strict -policy; a swarm started from content turns strict through a strict remake (Turning a -swarm strict, below). -Without it, the swarm has no registry: its users are all alike (A swarm without a -registry, below), until someone gives it one. `--protocol-writers` counts in -both: without a registry, as who may write protocol data; with one, to set it right -should nobody be left who may manage users (Keeping the swarm manageable, below). +`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy +([Values signed by their users](#values-signed-by-their-users), below) in the same change: +the swarm is strict from its start, and no change of it is from before the policy. So it +starts empty: content (`--genesis --remake`) would be a change of its own before that one, +and is refused with a strict policy; a swarm started from content turns strict through a +strict remake ([Turning a swarm strict](#turning-a-swarm-strict), below). Without it, the +swarm has no registry: its users are all alike +([A swarm without a registry](#a-swarm-without-a-registry), below), until someone gives it +one. `--protocol-writers` counts in both: without a registry, as who may write protocol +data; with one, to set it right should nobody be left who may manage users +([Keeping the swarm manageable](#keeping-the-swarm-manageable), below). ## At the HTTP API @@ -70,17 +71,17 @@ change to it counts on a node as soon as it has reached it. * **The store** (`/store`, `/stream`): writing a path (`PUT`, `POST`, `DELETE`) takes `write` on it, or, inside a list or text, on the list, as every node judges the - change (a list's items have no paths of their own, Changes judged on every node, - below); `?prune=true` deletes maps left empty only up to the highest one the - user may write. Reading takes `read`: of a place the user may read only partly, it - sees the keys on the way to what it may read, as a directory one may pass through - but not list (a capability on `servers/eu` shows `servers` with `eu` alone in it), - and nothing else; a list on the way is left out whole, as its items have no paths of - their own. A shallow read (`?shallow=true`) shows such a map as a map and no more (no - size), and nothing beside the way: a scalar at a `*` no capability covers stays - hidden. Native forms (`text/plain` of a map, a counter as its own type) only of - what it may read whole. What a write answers with is what was written. A stream - shows what the user could read when it opened. + change (a list's items have no paths of their own, + [Changes judged on every node](#changes-judged-on-every-node), below); `?prune=true` + deletes maps left empty only up to the highest one the user may write. Reading takes + `read`: of a place the user may read only partly, it sees the keys on the way to what it + may read, as a directory one may pass through but not list (a capability on `servers/eu` + shows `servers` with `eu` alone in it), and nothing else; a list on the way is left out + whole, as its items have no paths of their own. A shallow read (`?shallow=true`) shows + such a map as a map and no more (no size), and nothing beside the way: a scalar at a `*` + no capability covers stays hidden. Native forms (`text/plain` of a map, a counter as its + own type) only of what it may read whole. What a write answers with is what was written. + A stream shows what the user could read when it opened. * **Protocol data** is in the store too, under `_continuum`: `read` and `write` on it as on any path. * **Looking at the node** (`/admin/stats`, `GET /peers`, the dashboard): any user with @@ -154,9 +155,9 @@ curl -H "Authorization: Bearer ct1.…" http://other-node:3000/store write anything as anyone ([`trust.md`](trust.md)). A token is a bearer's: whoever holds it is the user until it ends, so it goes over TLS only, as passwords do. -A user with keys in its entry (`keys`, The registry, above) logs in on any node without -a password: it asks for a challenge, signs it with one of its keys, and gets the same -token (`login: "key"`). +A user with keys in its entry (`keys`, [The registry](#the-registry), above) logs in on +any node without a password: it asks for a challenge, signs it with one of its keys, and +gets the same token (`login: "key"`). ```sh c=$(curl -s -X POST localhost:3000/auth/challenge | jq -r .challenge) @@ -292,9 +293,10 @@ stays as it is, wherever it comes from later (a joining node catching up, say). * Everything else, protocol data or not, by a user the registry lets write there. * A map made on the way to what a change writes, where there was none (`servers`, for a first write at `servers/eu/0`), as what it writes within it. -* A node that isn't a member may only register itself; a banned node nothing (Banning - a node, below). So a node registers before anything else it writes, through the API - or its own: a change refused stays out with every change built on it. +* A node that isn't a member may only register itself; a banned node nothing + ([Banning a node](#banning-a-node), below). So a node registers before anything else it + writes, through the API or its own: a change refused stays out with every change built + on it. A node judges each change it makes the same way before it leaves, its own writes and those through the API alike: one every node would refuse is rolled back, never @@ -422,7 +424,7 @@ A member's node signs its changes, but the user a change names is its node's wor member could write as any user. A swarm can have its users sign the values that matter themselves, with their SSH keys, so no member can write them but as a user signed them: the policy's `"values": "signed"` (strict; it requires signatures too), -given to its genesis node (A new swarm, above): +given to its genesis node ([A new swarm](#a-new-swarm), above): ```sh continuum --genesis --bootstrap-users alice \ @@ -448,10 +450,10 @@ it logs in by key, writes and deletes signed values (`put config '{"mode": "fast and checks one against its user's keys (`verify config`). What a client reads to check a signature, the signer's keys, is in the registry, and -whom to seal for (Values sealed for their readers, below) in `_continuum/access`: both -protocol data, which a user's capabilities cover only if given so. Neither holds -secrets (every member holds the document), so give the users who check or seal reading -them: +whom to seal for ([Values sealed for their readers](#values-sealed-for-their-readers), +below) in `_continuum/access`: both protocol data, which a user's capabilities cover only +if given so. Neither holds secrets (every member holds the document), so give the users +who check or seal reading them: ```sh curl -u alice -X POST -H 'Content-Type: application/json' \ @@ -468,40 +470,40 @@ _continuum/users/bob '{…}'`). A node takes one only from that user, for that path, replacing what is there, by one of the user's keys, and if the user may write there ([`api.md`](api.md), Signed values); it writes nothing else there, nor within or above such a value (`409`), and the users API -changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`, A -new swarm, above) or through a remake (Turning a swarm strict, below), which keeps only -what an operator looked over: each is its epoch's first change, so no change of a strict -epoch is from before its policy. A change writing a strict policy where the policy isn't -strict is refused; and a policy reads strict only where its `values` is a string, as -continuum writes it: one that would read strict only through an Automerge text is one no -node knows, never what its characters spell. A strict swarm stays strict: its policy is written again only -as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a node -that doesn't know a policy reads it as none it can judge by); to leave it, start a new -swarm from its content (A new swarm, above). A value there that isn't an envelope starts -its chain anew: any envelope its user once signed for that path replacing nothing -(`prev` empty) can be put there again. Without the policy, signed values may be written -all the same, and plain ones too. +changes nothing (`409`). A swarm turns strict only at its start (`--bootstrap-policy`, +[A new swarm](#a-new-swarm), above) or through a remake +([Turning a swarm strict](#turning-a-swarm-strict), below), which keeps only what an +operator looked over: each is its epoch's first change, so no change of a strict epoch is +from before its policy. A change writing a strict policy where the policy isn't strict is +refused; and a policy reads strict only where its `values` is a string, as continuum +writes it: one that would read strict only through an Automerge text is one no node knows, +never what its characters spell. A strict swarm stays strict: its policy is written again +only as strict, never relaxed nor deleted, nor moved to a policy its nodes don't know (a +node that doesn't know a policy reads it as none it can judge by); to leave it, start a +new swarm from its content ([A new swarm](#a-new-swarm), above). A value there that isn't +an envelope starts its chain anew: any envelope its user once signed for that path +replacing nothing (`prev` empty) can be put there again. Without the policy, signed values +may be written all the same, and plain ones too. Keep two users who may manage users, or two keys each: under a strict policy, a registry whose only manager lost its keys changes no more (the protocol writers do everything there again only while nobody may manage users). -Every node judges the changes it receives alike (Changes judged on every node, above), -as their writer saw the registry: at such a place, only a string that is an envelope -that checks, replacing the one there then; nothing within one; and above one, nothing -replacing or deleting what holds one (a map made where there is none yet is fine). So -a member writing to its document directly gets nothing there past the others: the -registry, the policy and the bans change only as a user who may change them signed. -But "may" is read where a change was written, which its writer chooses: a capability -revoked, a user disabled or a key removed holds against members that weren't members -before it, not against one that was, with a user that could sign then. That member can -commit, at a history from before, an envelope the user signed then, numbered after what -was there then, and the next after it, as far as it likes; the place's value is then -the one with the highest `seq`. A remake ends it: nothing is written at a history from -before the new epoch. -A remake is outside this: its snapshot is the quorum's, so a `replace` or `import` -remake a majority of members commits writes at signed places whatever its content -holds, plain values too. +Every node judges the changes it receives alike +([Changes judged on every node](#changes-judged-on-every-node), above), as their writer +saw the registry: at such a place, only a string that is an envelope that checks, +replacing the one there then; nothing within one; and above one, nothing replacing or +deleting what holds one (a map made where there is none yet is fine). So a member writing +to its document directly gets nothing there past the others: the registry, the policy and +the bans change only as a user who may change them signed. But "may" is read where a +change was written, which its writer chooses: a capability revoked, a user disabled or a +key removed holds against members that weren't members before it, not against one that +was, with a user that could sign then. That member can commit, at a history from before, +an envelope the user signed then, numbered after what was there then, and the next after +it, as far as it likes; the place's value is then the one with the highest `seq`. A remake +ends it: nothing is written at a history from before the new epoch. A remake is outside +this: its snapshot is the quorum's, so a `replace` or `import` remake a majority of +members commits writes at signed places whatever its content holds, plain values too. ### Turning a swarm strict @@ -546,9 +548,10 @@ writing `_continuum/remakes`. ## Values sealed for their readers Anyone may read the whole document: every member holds it. A value only some may read -is sealed for them: encrypted with age to their SSH keys (`keys`, The registry, -above), so only they open it. Every node syncs, stores and remakes it as the string it -is, and none decrypts it: `cs1.<the age file, base64url>` (binary, not armored). +is sealed for them: encrypted with age to their SSH keys (`keys`, +[The registry](#the-registry), above), so only they open it. Every node syncs, stores and +remakes it as the string it is, and none decrypts it: `cs1.<the age file, base64url>` +(binary, not armored). ```sh jq -r '.keys[]' <(curl -s -u alice localhost:3000/store/_continuum/users/bob) > readers @@ -570,10 +573,11 @@ exactly their keys, as the registry has them when it is written. A node tells wi decrypting: an age file names each `ssh-ed25519` recipient by a tag, the first four bytes of the SHA-256 of its key. A write leaving a value there plain, or sealed for a reader's key too few or a stranger's too many, is refused (`409`), and with the policy -every node refuses such a change on receipt (Changes judged on every node, above). A -value signed by its user (Values signed by their users) holds the sealed value; the -signature is over the ciphertext, so every node checks who wrote it without reading -it. +every node refuses such a change on receipt +([Changes judged on every node](#changes-judged-on-every-node), above). A value signed by +its user ([Values signed by their users](#values-signed-by-their-users)) holds the sealed +value; the signature is over the ciphertext, so every node checks who wrote it without +reading it. `scripts/continuum-signed` seals and opens them too, with age: `seal secrets/db '{"password": "…"}'` seals for the readers declared there (or `CONTINUUM_READERS`), |
