diff options
| -rw-r--r-- | docs/access.md | 6 | ||||
| -rw-r--r-- | docs/api.md | 39 |
2 files changed, 31 insertions, 14 deletions
diff --git a/docs/access.md b/docs/access.md index 4c41e3d..2df7270 100644 --- a/docs/access.md +++ b/docs/access.md @@ -276,9 +276,9 @@ through (they look at the path asked for, the rules at everything the change doe can't cut its node off. With `"signatures": "required"`, a change also needs a signature by the node it names -([`api.md`](api.md), Signed changes): every node then signs every change it makes, and -one no signature vouches for yet waits, with whatever builds on it, until one does -(they come with the changes, or within a second on their own). A signature vouches for +([`api.md`](api.md), Signed changes): every node then signs what it sends, so every +change leaves vouched for, and one no signature vouches for yet waits, with whatever builds on it, until one does +(they come with the changes, in the same sync messages). A signature vouches for its change and the node's changes it builds on, no others: a change made under another node's actor is forged, refused, and logged as its sender's (`A peer brought changes forged`). A member can then no longer write as another member; the user a change names is still its node's word. diff --git a/docs/api.md b/docs/api.md index 681eb60..0d96dde 100644 --- a/docs/api.md +++ b/docs/api.md @@ -260,17 +260,34 @@ not the node's. So not every change is signed, only those that * or were written with `?signed=true`. A change left unsigned, such as a metric written many times a second, is vouched for -by the node's next signed one: with `--sign-every 1s` (the default), the node signs its -latest change at most a second after it if nothing signed it before, so every change is vouched -for within a second, at one signature a second at most; `--sign-every all` signs every -change as it is made, and `--sign-every none` signs only those above. A swarm whose policy requires -signatures ([`access.md`](access.md), Changes judged on every node) has every change -signed as it is made, whatever `--sign-every` says. -Signatures travel with sync messages: a node passes on, for each node's writes, the -latest signature it checked, and checks one it receives once it holds the change (a -signature costs about 30 µs to check, and one per node and run vouches for the rest). -Those no sync message took, as one made after its change went, go on their own within -a second (SIGNATURES), to each peer that wasn't sent them yet. +by the node's next signed one. Which that is, `--sign-every` says: + +* `sent` (the default): the node signs its latest change, if nothing signed it yet, as + a sync message takes it. The signature leaves in the same message as the changes it + vouches for, so every change arrives vouched for. A node writing now and then signs + each change; one writing many a second signs once per message, however many changes + it carries: as many signatures as messages, not as changes. +* `all`: every change, as it is made. Each change has its own signature, also one + never sent (a change made and kept while the node is cut off); the cost is a + signature per change, made, kept and checked on every node. +* `none`: only those above. A change left unsigned waits for the node's next signed + one: until then nobody can tell it is the node's. + +Which to choose: `sent` for nearly every swarm, slow or fast, since it signs what +leaves and nothing more. `all` where each change should carry its own proof, as when +changes are read with their signatures one by one later, at a signature per change +(about 25 µs to make, 30 µs to check on every node, 96 bytes kept). `none` where who +wrote a change matters only for what protocol data and the listed paths hold, to save +the signatures entirely. A swarm whose policy requires signatures +([`access.md`](access.md), Changes judged on every node) signs what is sent with +`none` too: every change must arrive vouched for. + +Signatures travel with the changes, in the sync messages that carry them, along the +same paths: a node passes on, for each node's writes, the latest signature it checked, +and checks one it receives once it holds the change (a signature costs about 30 µs to +check, and one vouches for its node's changes before it). A message carrying no +changes carries no signatures. A node that stopped with changes it never sent, nor +signed, signs them as it starts, before anything leaves. The signatures a node has are kept in its document file (`--document-file`) with the document. |