aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:38:19 +0100
committertv <tv@krebsco.de>2026-11-18 12:38:19 +0100
commit257ad0391ff8eba437108e1885c45314e9fd5833 (patch)
tree3098609e38125c0afb326efeb41a08d0045da3d4 /docs/guides
parentcfe3dbaff24b5ae433b3203d69c7e9bceb4e1ccc (diff)
parent55f36a960a90aedcb6e899ea963cc642fd630a82 (diff)
Merge branch 'ecdsa'
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/building-on-the-api.md8
-rw-r--r--docs/guides/federation/getting-started.md6
-rw-r--r--docs/guides/federation/keys.md31
-rw-r--r--docs/guides/federation/upgrades.md7
4 files changed, 46 insertions, 6 deletions
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.