Instrument real crypto ops to emit live LaTeX events

The running cryptography now narrates itself. Each headline operation emits a
trace.Event carrying its LaTeX notation plus the actual runtime values, the
instant it executes:

- Ed25519 signature on every inter-party message (envelope.Seal)
- X25519 ECDH key agreement for confidential card delivery (NewSecureChannel)
- ElGamal ballot encryption E1 = (g^r, pk^r·m) with the real r (castBallot)
- Fiat-Shamir challenge e = H(...) mod q (Schnorr proof)
- Bayer-Groth verifiable shuffle C' = {ReEnc_pk(C_π(i))} with N (mix-net)

Ceremony phases set trace phase/party context so events are attributed to the
acting stakeholder and phase. Instrumentation is behind the enabled-check, so
normal runs pay nothing.

Test: a full traced ceremony captures 184 live events across all five headline
kinds, each with non-empty LaTeX and live values, correctly phase/party-tagged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
saymrwulf 2026-07-07 14:06:08 +02:00
parent a5b9ce8ea3
commit bc43c3d3aa
9 changed files with 185 additions and 1 deletions

View file

@ -1,8 +1,11 @@
package mixnet
import (
"fmt"
"github.com/user/evote/pkg/elgamal"
emath "github.com/user/evote/pkg/math"
"github.com/user/evote/pkg/trace"
)
// VerifiableShuffle holds the result of a verifiable shuffle.
@ -30,6 +33,20 @@ func GenVerifiableShuffle(
// Generate shuffle argument
arg := GenShuffleArgument(C, shuffle.Shuffled, shuffle.Perm, shuffle.Rho, pk, ck, group)
trace.EmitFunc(func() trace.Event {
return trace.Event{
Kind: trace.KindShuffle,
Caption: fmt.Sprintf("Bayer-Groth verifiable shuffle of %d ciphertexts", N),
LaTeX: `\mathbf{C}' = \big\{\, \mathrm{ReEnc}_{pk}\!\big(C_{\pi(i)};\, \rho_i\big) \,\big\}_{i=1}^{\VAL{N}}, \qquad \pi \xleftarrow{\$} S_{\VAL{N}}`,
ASCII: "C' = { ReEnc_pk(C_π(i); ρ_i) } for a secret permutation π",
Values: map[string]string{
"N": fmt.Sprintf("%d", N),
"m": fmt.Sprintf("%d", N/n),
"n": fmt.Sprintf("%d", n),
},
}
})
return VerifiableShuffle{
ShuffledCiphertexts: shuffle.Shuffled,
Argument: arg,

View file

@ -7,6 +7,7 @@ import (
"github.com/user/evote/pkg/elgamal"
"github.com/user/evote/pkg/hash"
emath "github.com/user/evote/pkg/math"
"github.com/user/evote/pkg/trace"
"github.com/user/evote/pkg/transport"
"github.com/user/evote/pkg/zkp"
)
@ -51,6 +52,7 @@ func (c *Ceremony) RunSetup() error {
group := cfg.Group
zq := emath.ZqGroupFromGqGroup(group)
trace.Phase("setup")
c.logf("\n--- SETUP PHASE (multi-party) ---")
// 1. Encoding primes (public, computed by the setup component).

View file

@ -8,6 +8,7 @@ import (
emath "github.com/user/evote/pkg/math"
"github.com/user/evote/pkg/mixnet"
"github.com/user/evote/pkg/returncodes"
"github.com/user/evote/pkg/trace"
"github.com/user/evote/pkg/transport"
"github.com/user/evote/pkg/zkp"
)
@ -46,6 +47,7 @@ type finalResp struct {
// posts its shuffle and decryption proofs to the public transcript (the
// bulletin board), which the verifier re-checks in RunVerify.
func (c *Ceremony) RunTally() error {
trace.Phase("tally")
c.logf("\n--- TALLY PHASE (multi-party) ---")
group := c.Config.Group
@ -136,6 +138,7 @@ func (p *ControlComponent) handleShuffle(env *transport.Envelope) (*transport.En
// Remaining public key = CCs[stage..] + EB, read from the public transcript.
remaining := remainingPK(p.cer.Transcript, req.Stage, cfg.NumCCs)
trace.SetContext(p.id.Name, "tally")
vs := mixnet.GenVerifiableShuffle(in, remaining, group)
// Partial decrypt with this CC's private key; produce decryption proofs.
@ -171,6 +174,7 @@ func (p *ElectoralBoard) handleFinalMix(env *transport.Envelope) (*transport.Env
return nil, fmt.Errorf("eb final input: %w", err)
}
trace.SetContext(p.id.Name, "tally")
vs := mixnet.GenVerifiableShuffle(in, p.st.keyPair.PK, group)
p.cer.Transcript.Shuffles = append(p.cer.Transcript.Shuffles, vs)

87
pkg/party/trace_test.go Normal file
View file

@ -0,0 +1,87 @@
package party
import (
"testing"
"github.com/user/evote/pkg/trace"
)
// TestCeremonyEmitsLiveCryptoEvents runs the full ceremony with a trace sink
// attached and confirms that the real cryptographic operations emit events
// carrying live runtime values — the foundation of the "watch the math execute"
// cockpit. It checks that each headline operation kind appears with non-empty
// values and correct LaTeX.
func TestCeremonyEmitsLiveCryptoEvents(t *testing.T) {
sink := &trace.SliceSink{}
unsub := trace.Subscribe(sink)
defer unsub()
cfg := testConfig(t, 3, 3)
c, err := NewCeremony(cfg, nil)
if err != nil {
t.Fatalf("NewCeremony: %v", err)
}
if err := c.RunSetup(); err != nil {
t.Fatalf("RunSetup: %v", err)
}
if err := c.RunCards(); err != nil {
t.Fatalf("RunCards: %v", err)
}
if err := c.RunVoting([][]int{{0}, {1}, {2}}); err != nil {
t.Fatalf("RunVoting: %v", err)
}
if err := c.RunTally(); err != nil {
t.Fatalf("RunTally: %v", err)
}
if err := c.RunVerify(); err != nil {
t.Fatalf("RunVerify: %v", err)
}
events := sink.Snapshot()
if len(events) == 0 {
t.Fatal("no trace events emitted during a full ceremony")
}
seen := map[trace.Kind]trace.Event{}
for _, e := range events {
seen[e.Kind] = e
}
// Every headline operation must have fired at least once.
for _, k := range []trace.Kind{
trace.KindSign, // Ed25519 transport signatures
trace.KindKeyEx, // X25519 ECDH (card delivery)
trace.KindEncrypt, // ballot encryption
trace.KindChallenge, // Fiat-Shamir challenge
trace.KindShuffle, // Bayer-Groth mix-net
} {
e, ok := seen[k]
if !ok {
t.Errorf("no %q event emitted", k)
continue
}
if e.LaTeX == "" {
t.Errorf("%q event has empty LaTeX", k)
}
if len(e.Values) == 0 {
t.Errorf("%q event carries no live values", k)
}
}
// Spot-check that the shuffle event reports the padded ballot count (N>=3).
if sh, ok := seen[trace.KindShuffle]; ok {
if sh.Values["N"] == "" {
t.Error("shuffle event missing N")
}
}
// Events must be tagged with a phase, and signatures with the acting party.
if seen[trace.KindSign].Party == "" {
t.Error("signature event not attributed to a party")
}
if seen[trace.KindShuffle].Phase != "tally" {
t.Errorf("shuffle phase = %q, want tally", seen[trace.KindShuffle].Phase)
}
t.Logf("captured %d live crypto events across %d kinds", len(events), len(seen))
}

View file

@ -5,6 +5,7 @@ import (
"github.com/user/evote/pkg/elgamal"
"github.com/user/evote/pkg/mixnet"
"github.com/user/evote/pkg/trace"
)
// RunVerify has the verifier party independently re-check the public transcript:
@ -13,6 +14,7 @@ import (
// decryptions). It returns nil only if every check passes. The verifier holds no
// secret — it works purely from the bulletin-board transcript.
func (c *Ceremony) RunVerify() error {
trace.Phase("verify")
c.logf("\n--- VERIFICATION PHASE (multi-party) ---")
tr := c.Transcript
group := c.Config.Group

View file

@ -7,6 +7,7 @@ import (
"github.com/user/evote/pkg/hash"
emath "github.com/user/evote/pkg/math"
"github.com/user/evote/pkg/returncodes"
"github.com/user/evote/pkg/trace"
"github.com/user/evote/pkg/transport"
"github.com/user/evote/pkg/zkp"
)
@ -41,6 +42,7 @@ type wireBallot struct {
// server routes each ballot to all CCs for proof verification and stores the
// accepted ballots. Selections are provided per voter (indexed by voter).
func (c *Ceremony) RunVoting(selections [][]int) error {
trace.Phase("voting")
c.logf("\n--- VOTING PHASE (multi-party) ---")
for v, voter := range c.Voters {
sel := []int{0}
@ -81,6 +83,20 @@ func (p *VoterClient) castBallot(selected []int) (*transport.Envelope, error) {
}
msgRandomness := emath.RandomZqElement(zq)
ct := elgamal.Encrypt(elgamal.NewMessage(emath.GqVectorOf(msgElems...)), msgRandomness, p.st.electionPK)
trace.EmitFunc(func() trace.Event {
return trace.Event{
Party: p.id.Name,
Kind: trace.KindEncrypt,
Caption: fmt.Sprintf("%s encrypts ballot (ElGamal over G_q)", p.id.Name),
LaTeX: `E_1 = (\gamma,\, \boldsymbol{\phi}) = \big(g^{r},\; pk^{r}\cdot m\big), \qquad r \xleftarrow{\$} \mathbb{Z}_q`,
ASCII: "E1 = (g^r, pk^r · m), r ← Z_q",
Values: map[string]string{
"r": msgRandomness.Value().String(),
"gamma": ct.Gamma.Value().String(),
"m0": voteElem.Value().String(),
},
}
})
// 2. Verification-card key pair.
p.st.vcSK = emath.RandomZqElement(zq)

View file

@ -5,6 +5,7 @@ import (
"fmt"
"github.com/user/evote/pkg/symmetric"
"github.com/user/evote/pkg/trace"
"github.com/user/evote/pkg/transportsec"
)
@ -54,11 +55,26 @@ func (id *Identity) NewSecureChannel(peerName string, peerXPub []byte) (*SecureC
if err != nil {
return nil, fmt.Errorf("ECDH %s<->%s: %w", id.Name, peerName, err)
}
sessionKey := deriveSessionKey(shared, id.XPub, peerXPub)
trace.EmitFunc(func() trace.Event {
return trace.Event{
Party: id.Name,
Kind: trace.KindKeyEx,
Caption: fmt.Sprintf("%s ⇄ %s: X25519 key agreement", id.Name, peerName),
LaTeX: `s = a \cdot B = b \cdot A \in \mathbb{X}_{25519}, \qquad k = \mathrm{SHA256}(\text{ctx} \,\Vert\, A \,\Vert\, B \,\Vert\, s)`,
ASCII: "s = a·B = b·A ; k = SHA256(ctx ‖ A ‖ B ‖ s)",
Values: map[string]string{
"peer": peerName,
"shared": hexOf(shared),
"session": hexOf(sessionKey),
},
}
})
return &SecureChannel{
local: id,
peerName: peerName,
peerXPub: peerXPub,
sessionKey: deriveSessionKey(shared, id.XPub, peerXPub),
sessionKey: sessionKey,
}, nil
}

View file

@ -6,6 +6,7 @@ import (
"encoding/json"
"fmt"
"github.com/user/evote/pkg/trace"
"github.com/user/evote/pkg/transportsec"
)
@ -59,9 +60,34 @@ func (e *Envelope) Seal(sender *Identity) error {
return fmt.Errorf("seal %s->%s: %w", e.From, e.To, err)
}
e.Signature = sig
trace.EmitFunc(func() trace.Event {
return trace.Event{
Party: e.From,
Kind: trace.KindSign,
Caption: fmt.Sprintf("%s signs %q → %s", e.From, e.Type, e.To),
LaTeX: `\sigma \gets \mathrm{Ed25519.Sign}_{sk_{\text{\VAL{party}}}}\!\big(\mathrm{SHA256}(\text{envelope})\big),\quad |\sigma| = 64\text{ B}`,
ASCII: "σ ← Ed25519.Sign(sk, H(envelope))",
Values: map[string]string{
"party": e.From,
"to": e.To,
"type": e.Type,
"sigma": hexOf(sig),
},
}
})
return nil
}
func hexOf(b []byte) string {
const hexdigits = "0123456789abcdef"
out := make([]byte, len(b)*2)
for i, c := range b {
out[i*2] = hexdigits[c>>4]
out[i*2+1] = hexdigits[c&0x0f]
}
return string(out)
}
// Verify checks the envelope signature against senderEdPub (via Rust).
func (e *Envelope) Verify(senderEdPub []byte) error {
if err := transportsec.Ed25519Verify(senderEdPub, e.signingBytes(), e.Signature); err != nil {

View file

@ -3,6 +3,7 @@ package zkp
import (
"github.com/user/evote/pkg/hash"
emath "github.com/user/evote/pkg/math"
"github.com/user/evote/pkg/trace"
)
// GenSchnorrProof generates a Schnorr proof of knowledge of discrete log.
@ -67,6 +68,19 @@ func schnorrChallenge(group *emath.GqGroup, y emath.GqElement, c emath.GqElement
hAux,
)
e, _ := emath.NewZqElement(eVal, zqGroup)
trace.EmitFunc(func() trace.Event {
return trace.Event{
Kind: trace.KindChallenge,
Caption: "Fiat-Shamir challenge (Schnorr proof)",
LaTeX: `e = \mathcal{H}\big((p,q,g),\, y,\, c,\, h_{\mathrm{aux}}\big) \bmod q`,
ASCII: "e = H((p,q,g), y, c, h_aux) mod q",
Values: map[string]string{
"e": e.Value().String(),
"y": y.Value().String(),
"c": c.Value().String(),
},
}
})
return e
}