Problem
The protocol repo exists as the source of truth for AnonVote's
privacy model but specs/crypto.md is empty. This means there
is currently no formal specification for the five cryptographic
primitives that the entire system is built on. Contributors
implementing functions in AnonVote/js have no reference to
verify their implementation is correct. Auditors evaluating
AnonVote's privacy guarantees have nothing to audit. The
protocol repo cross-references specs/crypto.md from every
other spec file — those links all resolve to a blank page.
Without this spec, the privacy model exists only as informal
descriptions scattered across READMEs. That is not auditable,
not citable, and not sufficient for an open source project
making strong cryptographic claims.
Solution
Write a complete formal specification for all five AnonVote
cryptographic primitives covering algorithm choices, input
and output formats, security properties, and the rationale
behind each decision.
Content Requirements
- hashIdentifier — specify SHA-256 as the algorithm, hex
output format, the normalization requirement (trim +
lowercase) and why it exists, the security property
being enforced (preimage resistance), and what breaks
if this function is implemented incorrectly
- generateToken — specify CSPRNG requirement, 32-byte
length, hex encoding, uniqueness guarantee, and why
Math.random() or any non-CSPRNG source is unacceptable
- hashToken — specify why token hashing is a separate
step from token generation, the two-step design rationale,
and what the stored hash protects against if the database
is compromised
- encryptVote — specify AES-256-GCM, 12-byte IV generated
fresh per call, the three output components (ciphertext,
iv, authTag), why GCM was chosen over CBC, and what the
auth tag protects against
- decryptVote — specify auth tag verification requirement,
what a failed verification means in the context of a
vote, and why silent failure is worse than a thrown error
For each primitive include:
- Algorithm and parameters
- Input format and constraints
- Output format and guarantees
- Security property being enforced
- Failure modes and what they mean for the system
- Reference to the implementing function in AnonVote/js
Additional Sections
- Dependency diagram showing how the five primitives
compose into the full vote lifecycle
- Key management section — how per-ballot encryption
keys are generated, stored, and used — this is not
implemented in AnonVote/js but must be specified here
so core implements it correctly
- A note on what AnonVote's crypto layer does not protect
against — traffic analysis, coercion, admin key
compromise — so the threat model is honest
Acceptance Criteria
Note for contributors
This is a specification document, not a tutorial. Write
for an auditor or a security researcher, not a beginner.
Be precise about algorithm parameters, output formats,
and failure modes. Vague language like "secure hashing
is used" is not acceptable — name the algorithm, the
parameters, and the exact security property it provides.
Problem
The protocol repo exists as the source of truth for AnonVote's
privacy model but specs/crypto.md is empty. This means there
is currently no formal specification for the five cryptographic
primitives that the entire system is built on. Contributors
implementing functions in AnonVote/js have no reference to
verify their implementation is correct. Auditors evaluating
AnonVote's privacy guarantees have nothing to audit. The
protocol repo cross-references specs/crypto.md from every
other spec file — those links all resolve to a blank page.
Without this spec, the privacy model exists only as informal
descriptions scattered across READMEs. That is not auditable,
not citable, and not sufficient for an open source project
making strong cryptographic claims.
Solution
Write a complete formal specification for all five AnonVote
cryptographic primitives covering algorithm choices, input
and output formats, security properties, and the rationale
behind each decision.
Content Requirements
output format, the normalization requirement (trim +
lowercase) and why it exists, the security property
being enforced (preimage resistance), and what breaks
if this function is implemented incorrectly
length, hex encoding, uniqueness guarantee, and why
Math.random() or any non-CSPRNG source is unacceptable
step from token generation, the two-step design rationale,
and what the stored hash protects against if the database
is compromised
fresh per call, the three output components (ciphertext,
iv, authTag), why GCM was chosen over CBC, and what the
auth tag protects against
what a failed verification means in the context of a
vote, and why silent failure is worse than a thrown error
For each primitive include:
Additional Sections
compose into the full vote lifecycle
keys are generated, stored, and used — this is not
implemented in AnonVote/js but must be specified here
so core implements it correctly
against — traffic analysis, coercion, admin key
compromise — so the threat model is honest
Acceptance Criteria
algorithm, input/output format, security property,
and failure modes
protected
accurate
AnonVote repo can understand the full crypto layer
from this document alone
Note for contributors
This is a specification document, not a tutorial. Write
for an auditor or a security researcher, not a beginner.
Be precise about algorithm parameters, output formats,
and failure modes. Vague language like "secure hashing
is used" is not acceptable — name the algorithm, the
parameters, and the exact security property it provides.