mirror of
https://github.com/saymrwulf/swisspost-evoting-go-poc.git
synced 2026-11-17 08:56:11 +00:00
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:
parent
b1f56065ed
commit
68aa702452
2 changed files with 78 additions and 16 deletions
|
|
@ -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.
|
||||
|
|
|
|||
22
README.md
22
README.md
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue