Docs: multi-party architecture, netdemo, honest scope limits

README: add pkg/transport + pkg/party to the component table and project tree,
document `evote netdemo` alongside `demo`, point to ARCHITECTURE.md.

ARCHITECTURE: document the implemented message flow per phase; the design
decision (ciphertexts cross the signed transport, proofs go to the bulletin-board
transcript); which due-diligence findings were folded in (M4/F6/F7/F8/F12); and
honest scope limits (F5 not reimplemented; return codes derived, not homomorphic
over the ciphertext, per F16 — but with the F1 derivation mismatch fixed).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
saymrwulf 2026-07-06 15:26:44 +02:00
parent b1f56065ed
commit 68aa702452
2 changed files with 78 additions and 16 deletions

View file

@ -60,19 +60,65 @@ signatures, X25519 for key agreement — with **no RSA anywhere**, including the
X.509 CA. This is a design choice for the PoC, not a claim about the production
system.
## Message inventory (implemented incrementally)
## Message flow (implemented)
Setup: CC key shares + Schnorr proofs → setup; setup → voter (card), → server
(mapping table), → all (signed election config). Voting: voter → server (ballot);
server → CCj (proof check); server ↔ CCj (return-code shares). Tally: server →
CC0 (ballot box); CCj → CCj+1 (shuffle + partial decryption + proofs); CC3 → EB;
EB → bulletin board (result + final proof). Audit: bulletin board → verifier
(public transcript).
Run it with `evote netdemo --verbose` to watch every signed envelope.
## Deferred trust-boundary hardening folded in here
- **Setup** — `setup → CCj: gen-cc-keys`; `CCj → setup: cc-keys` (PK + Schnorr
proofs, verified on receipt); `setup → EB: gen-eb-key`; `EB → setup: eb-key`.
Setup combines the keys and publishes them to the transcript.
- **Cards** — for each voter, `setup → CCj: long-code-share-req`; `CCj → setup:
long-code-share-resp` (return-code shares from the CC's private secret). Setup
assembles cards and delivers them **confidentially**: `setup → voter:
voting-card` and `setup → server: mapping-table` (both X25519-encrypted).
- **Voting** — `voter → server: cast-ballot`; `server → CCj: verify-ballot`;
`CCj → server: ballot-verdict`. Stored on unanimous acceptance (vcPK persisted).
- **Tally** — `→ server: start-tally` (server pads the ballot box); then
`→ CCj: shuffle` / `CCj →: shuffled` chained through all CCs; `→ EB: final-mix`
/ `EB →: final-done`. Each party posts its shuffle + decryption proofs to the
transcript.
- **Audit** — the verifier re-checks the whole transcript (`RunVerify`): every CC
Schnorr proof and the full shuffle chain, from public data alone.
Findings from the due-diligence pass that only matter once inputs are remote are
addressed as parties are split: verifiers return errors instead of panicking on
malformed peer input, group elements/proofs are re-validated on receipt, and the
artifacts a remote verifier needs (padded mix input, per-stage decryption proofs,
`vcPK`) are persisted into a serializable public transcript.
### Design decision: proofs on the bulletin board, ciphertexts on the wire
Fully serializing the Bayer-Groth argument tree (product / Hadamard / zero / SVP
/ multi-exponentiation sub-arguments, each with nested vectors) as JSON for every
CC→CC hop would be enormous. Instead — matching the real system, where control
components publish to a public bulletin board — the **ciphertext handoffs** between
parties cross the signed transport (and are re-validated as G_q members on
decode), while the **zero-knowledge proofs** are posted to the public transcript
that the verifier independently re-checks. The vote data itself always crosses
the authenticated channel; the proofs live on the board, exactly where an auditor
reads them.
## Trust-boundary hardening folded in here
Findings from the due-diligence pass that only bite once inputs are remote are
addressed in the party layer:
- **M4** (unvalidated deserialization): every crypto object is decoded through
`NewGqElement`/`NewZqElement` at the wire boundary (`pkg/party/wire.go`), so a
peer cannot inject a non-residue or out-of-range value.
- **F6** (`vcPK` not persisted): the ballot carries `vcPK`, stored in the ballot
box, so the exponentiation-proof statement is reconstructible by any party.
- **F7 / F8** (padding / partial decryptions not persisted): the padded mix input
and every per-stage partial decryption are published to the transcript, and the
verifier checks the shuffle chain against exactly those.
- **F12** (panic on malformed plaintext): tally uses `DecodeVoteChecked`, so a
ballot that does not decode is spoiled, not fatal; handlers reject malformed
messages cleanly rather than panicking.
### Honest scope limits
- **F5** (the unsound plaintext-equality proof) is *not* reimplemented. The
multi-party ballot uses only the **sound exponentiation proof** binding the
ballot to `vcPK`; the return-code path that encrypts partial choice codes under
the return-codes key (E2 / plaintext-equality) is omitted.
- Consistent with the original system (finding F16), the **cast-as-intended**
return codes are derived deterministically from CC shares rather than
homomorphically over the submitted ciphertext. The return-code *mechanism*
(per-CC shares combined into a mapping-table lookup) is real and consistent
across card generation and would-be extraction (fixing the old derivation
mismatch, F1); the property that the shown code is computed *from the actual
ballot* remains simulated.

View file

@ -36,9 +36,11 @@ Verify Public audit: all proofs are independently checkable
| `pkg/kdf` | HKDF key derivation for return code generation |
| `pkg/symmetric` | AES-GCM authenticated encryption |
| `pkg/returncodes` | Vote encoding as small primes, return code mapping tables |
| `pkg/protocol` | Full election orchestration (setup, vote, confirm, tally) |
| `pkg/protocol` | Single-process election orchestration (setup, vote, confirm, tally) |
| `pkg/verify` | Independent verification of all proofs |
| `pkg/transportsec` | Transport-layer security (Ed25519 signatures, X25519 ECDH) — **implemented in Rust**, linked via cgo (see below) |
| `pkg/transport` | Authenticated message bus: Ed25519 X.509 PKI, signed envelopes, X25519 secure channels |
| `pkg/party` | **Multi-party ceremony**: each endpoint (setup, 4 CCs, electoral board, voting server, voters, verifier) as a separate party communicating only over the signed transport |
## Transport Security in Rust
@ -59,9 +61,13 @@ addition to Go. The Makefile builds the Rust library first, then the Go binary:
make build # cargo build --release, then go build -o evote ./cmd/evote
make test # runs cargo test + go test ./...
# Run a complete election ceremony (10 voters, 3 candidates)
# Run a complete election ceremony, single process (10 voters, 3 candidates)
./evote demo --voters 10 --options 3
# Run the SAME election as separate parties over Rust-signed transport
./evote netdemo --voters 10 --options 3
./evote netdemo --voters 3 --options 2 --verbose # log every signed message
# Serve presentations on local network (for iPad viewing)
./evote serve --port 8080
@ -69,6 +75,12 @@ make test # runs cargo test + go test ./...
./evote present
```
The `demo` command runs the whole protocol in one process. `netdemo` runs the
**multi-party** architecture: every party is a separate endpoint holding only its
own private state, and every message between them is Ed25519-signed (and, for
card/mapping-table delivery, X25519-encrypted) — all transport cryptography in
Rust. See [ARCHITECTURE.md](ARCHITECTURE.md).
If you build Go directly (`go build ./...`), run `make rust` first so the static library
at `rust/transportsec/target/release/libtransportsec.a` exists for cgo to link.
@ -144,8 +156,12 @@ pkg/
kdf/ HKDF key derivation
symmetric/ AES-GCM
returncodes/ Vote encoding, return code mapping
protocol/ Election orchestration
protocol/ Single-process election orchestration
verify/ Independent proof verification
transportsec/ Rust FFI: Ed25519 sign/verify, X25519 ECDH
transport/ PKI, signed envelopes, secure channels, message bus
party/ Multi-party ceremony (one object per endpoint)
rust/transportsec/ Rust crate: ed25519-dalek + x25519-dalek, C ABI
```
## Security Hardening (Due-Diligence Pass)