Test code and other utilities related to electionguard-rust

other/spec-todo/.gitignore

@@ -0,0 +1 @@
+*.bak.txt

other/spec-todo/EG-v2.1-Spec-Priorities.txt

@@ -0,0 +1,68 @@
+
+
+S3.1 Parameter Requirements
+S3.2 Key Generation eq. 6 - 30
+S3.3.1 Selection Encryption, eq. 31..
+S3.3.2 Selection Encryption Identifiers and Identifier Hash
+S3.3.3 Generation of the Ballot Nonce and Encryption Nonces
+S3.3.4 Encryption of Ballot Nonces
+S3.3.5 Ballot Well-Formedness
+S3.3.6 Outline for Proofs of Ballot Correctness
+S3.3.7 Details for Proofs of Ballot Correctness
+S3.3.8 Proof of Satisfying the Contest Selection Limit, eq. ..62
+S3.4.1 Contest Hash eq. 70
+S3.4.2 Confirmation Code eq. 71
+    "Critical"
+
+S3.5, S3.6.1 - S3.6.5 eq. 79 - 95
+    "Essential"
+
+S3.6.7 Decryption of Challenged Ballots, eq. 107 - 111
+S5 Hash Computation
+    "Critical"
+
+S4 Pre-Encrypted Ballots, eq. 112 - 121
+    "Secondary",
+    "NOT a priority",
+    "above S3.3.9 - S3.3.10 Supplemental and contest data"
+    "above S3.4.3 - S3.4.4 ballot chaining"
+
+S3.4.3 Voting Device Information Hash, eq. 72
+S3.4.4 Ballot Chaining, eq. 73 - 78
+    "Not critical may be deferred"
+
+S3.3.9 Supplemental Verifiable Fields
+S3.3.10 Contest Data
+    "Optional"
+
+S3.6.6 Decryption of Contest Data
+    "Not top priority"
+    "Only necessary if S3.3.9 - S3.3.10 Supplemental and contest data"
+
+S3.7 Election Record
+    "Just a recapitulation"
+
+ [This section generates no unique or specific requirements]
+
+% xreq S3.1.4.b.verif1 TODO: Verification 1
+
+
+% xreq S3.a.f.d (Ref: S2.b) Key Ceremony
+
+
+% xreq S3.2.c (Ref: S3.a.f.c) "EGRI enables a Guardian to compute a verifiable partial decryption of the tally of every Contest Option Field and additional Contest Data Field."
+
+% xreq S3.2.c (Ref: S3.a.f.c) "EGRI enables a quorum of `k` distinct Guardian (Vote|Ballot Data) Encryption Secret Keys to form full verifiable decryptions of the election tallies by combining the verifiable partial decryptions of the tallies of every Contest Option Field and additional Contest Data Field."
+
+% xreq S3.2.c (Ref: S3.a.f.d) "Fewer than `k` distinct Guardian (Vote|Ballot Data) Encryption Secret Keys can not produce a full decryption of any tally"
+
+% xreq S3.a.g EGRI encrypts other (non-vote) Ballot Data to the Joint Ballot Data Encryption Public Key
+
+
+Joint (Vote|Ballot Data) Encryption Public Keys
+
+Contest (Option or Additional) Data Field
+
+
+% xreq S3.2.3.j EGRI computes H_E from H_B and the Joint (Vote|Ballot Data) Encryption Public Keys as specified in EG DS v2.1.0 eq. 30.
+

other/spec-todo/TODO-2.1.txt.db.other_items.csv

@@ -0,0 +1,152 @@
+section,status,xtext
+S0,todo,"Fix references to EGDS in the source code to always include section and page number"
+S0,todo,"Fix references to EGDS in the source docs to always include section and page number"
+S0,todo,"Set panic behavior to abort. See https://gitlab.torproject.org/legacy/trac/-/issues/27199"
+S0,todo,"Remove eg/src/example*.rs files, migrate to resource_producer"
+S0,todo,"Migrate away from 'anyhow' in library code"
+S0,todo,"Q|UG left pad as necessary to ensure length is correct"
+S0,todo,"MAYB|serialize format wrapped in version"
+S0,todo,"crate feature for guardian secret operations."
+S0,todo,"ensure SecretCoefficient is serialized in a fixed-length format"
+S0,todo,"rewrite build-docs script in sh"
+S0,todo,"Build on Linux32"
+S0,todo,"Test on Linux32"
+S0,todo,"Build on Linux64"
+S0,todo,"Test on Linux64"
+S0,todo,"Build on Win64"
+S0,todo,"Test on Win64"
+S0,todo,"Test library components for Wasm32"
+S0,todo,"docs/general: style sheet for markdown, ideally match API docs"
+S0,todo,"If an overvote occurs, the overvote must be captured, encrypted, and never decrypted."
+S0,todo,"docs/specs/serialization: data formats section"
+S0,todo,"docs/specs/serialization: standards and references section"
+S0,todo,"docs/specs/serialization: election manifest section"
+S0,todo,"docs/specs/serialization: election record section"
+S0,todo,"docs/specs/serialization: vendor data section"
+S0,todo,"docs/api: reference NIST CDF where types clearly correspond. E.g., BallotStyle https://github.com/usnistgov/ElectionResultsReporting/blob/nist-pages/index.md#17_0_2_4_78e0236_1389366224561_797289_2360"
+S0,todo,"docs/implementation guide/Requirements for election systems vendors: complete"
+S0,todo,"docs/implementation guide/Requirements for verifier app authors: complete"
+S0,todo,"docs/implementation guide/roles: consider splitting into separate pages: complete"
+S0,todo,"docs/implementation guide/roles/Election Administrator: complete"
+S0,todo,"docs/implementation guide/roles/Election Guardians: complete"
+S0,todo,"docs/implementation guide/roles/Voters: complete"
+S0,todo,"docs/implementation guide/roles/Political parties and voter-interest organizations: complete"
+S0,todo,"docs/implementation guide/roles/Journalists and other media: complete"
+S0,todo,"docs/implementation guide/Hardware requirements/Gurardian secret key storage: complete"
+S0,todo,"docs/implementation guide/Hardware requirements/Gurardian secret key operations: complete"
+S0,todo,"docs/implementation guide/step-by-step/Advance preparation: complete"
+S0,todo,"docs/implementation guide/step-by-step/Key ceremony: complete"
+S0,todo,"docs/implementation guide/step-by-step/Tally ceremony: complete"
+S0,todo,"docs/implementation guide/step-by-step/Publishing: complete"
+S0,todo,"docs/implementation guide/step-by-step/Verification: complete"
+S0,todo,"docs/implementation guide/step-by-step/Reporting: complete"
+S0,todo,"docs/api: use correct logo"
+S0,todo,"docs/api: complete"
+S0,todo,"docs: complete, #![warn(missing_docs)]"
+S0,todo,"docs: upload docs to github pages (see compliance notes)"
+S0,todo,"security review: ensure that no file leaks info through filesize"
+S0,todo,"distinguish between PartySelection, BallotMeasureSelection, CandidateSelection"
+S0,todo,"BallotDefinition doc for write-in option"
+S0,todo,"would be nice to support a PartySelection type vote, rather than rely on the vendor to give us the correct selections explicitly"
+S0,todo,"a trait for types that have pub fn validate(&Self, &ElectionParameters)"
+S0,todo,"docs: more investigation into using rust modules to build documentation along with api, observe how cargo_crev does it with the include_str! macro: https://github.com/crev-dev/cargo-crev/blob/master/cargo-crev/src/doc/mod.rs"
+S0,todo,"docs: more investigation into using mdbook for all project documentation https://github.com/rust-lang/rust/issues/66249"
+S0,todo,"docs: cargo-external-doc is nice but doesn't support virtual manifests https://github.com/Geal/cargo-external-doc"
+S0,todo,"VaryingParameters (n, k) This isn't really an 'index' (ordinal), it's a cardinal number. Maybe we need a general purpose ranged number type."
+S0,todo,"exe: common parameter: election filesystem directory to look for files (%ELECTIONGUARD_ARTIFACTS_DIR%)"
+S0,todo,"exe: common parameter: manifest file"
+S0,todo,"exe: common parameter: others"
+S0,todo,"persist/file: create artifact directories if they don't exist. q: what about permissions on guardian secret directories?"
+S0,todo,"perisist: encryption or password protection for guaridan secret key files"
+S0,todo,"util: read guardian secret key, print info, suppressing secrets"
+S0,todo,"util: read guardian public key, print info"
+S0,todo,"persist: define standard election directory layout - look at other implementers and users"
+S0,todo,"design: key file represents its kind: guardian, ..., ?"
+S0,todo,"Consider structures defined in JSON schema https://github.com/usnistgov/ElectionResultsReporting/blob/version2/NIST_V2_election_results_reporting.json"
+S0,todo,"if electionguard.exe fails to read or write a file, check the path to see if it has a leading ~. If so, print a good error message."
+S0,todo,"test on 32-bit target such as x86 or wasm32"
+S0,todo,"test on big-endian target such as powerpc64-unknown-linux-gnu, s390x-unknown-linux-gnu, riscv64gc-unknown-linux-gnu, or loongarch64-unknown-linux-gnu"
+S0,todo,"electionguard-test script: incorporate ballots"
+S0,todo,"electionguard-test script: incorporate tally"
+S0,done,"move types for numbers mod p and mod q back into 'eg' lib so they can be known at compile time"
+S0,done,"change obtain_resource_production_result_from_cache_downcast"
+S0,done,"electionguard.exe: common parameter: election filesystem directory to look for files (%ELECTIONGUARD_ARTIFACTS_DIR%)"
+S0,done,"electionguard.exe: seed: write random seed to artifact file"
+S0,done,"electionguard.exe manifest: write ElectionManifest to pretty json file"
+S0,done,"electionguard.exe manifest: write ElectionManifest to canonical bytes file"
+S0,done,"electionguard.exe parameters: write ElectionParameters to json file"
+S0,done,"H_V, H_P, H_M, and H_B updated for 2.0 calculation"
+S0,done,"Generate joint election public key"
+S0,done,"Extended base hash H_E"
+S0,done,"electionguard-test script: implementation in cmd started"
+S0,done,"electionguard-test script: implementation in cmd exercises all (current) functionality"
+S0,done,"BigUint values (mod p or q) now left-padded as necessary to avoid leaking value via serialized file size"
+S0,done,"Hash values now serialized with 'H(upper hex)' format to match spec"
+S0,done,"exe: Csprng now seeded with more entropy from the operating system RNG"
+S0,done,"Election-varying parameters (n and k) now checked for validity"
+S0,done,"Serialization of BigUints now uses base64 encoding"
+S0,done,"Rename guardian private key to secret key"
+S0,done,"electionguard.exe: generate guardian secret key"
+S0,done,"electionguard.exe: write guardian secret key"
+S0,done,"electionguard.exe: derive guardian public key from secret key"
+S0,done,"electionguard.exe: write guardian public key"
+S0,done,"Guardian i uses 1-based indexing"
+S0,done,"compute H_E extended base hash"
+S0,done,"compute joint election public key"
+S0,done,"electionguard.exe: write joint election public key to json file"
+S0,done,"standardize on 'validate' instead of 'verify' when checking deserialized structures"
+S0,done,"instead of from_json and to_json implement from_stdioread and to_stdiowrite"
+S0,done,"every struct that has Self::from_stdioread*() should prefer Self::from_stdioread_validated() and have a self.validate()"
+S0,done,"electionguard.exe: write H_E extended base hash to json file"
+S0,done,"convert many uses of if !() { bail!() } to ensure!()"
+S0,done,"Generate data structure docs from the Reference Implementation in Rust"
+S0,done,"eg: New constrained numeric type for indices. Convert n, k, and other indices to this type."
+S0,done,"build-docs script: initial implementation in cmd"
+S0,done,"evaluate scripting language 'nu' https://www.nushell.sh/"
+S0,done,"electionguard-test script: begin rewrite in nu"
+S0,done,"doc/LICENSE: checked"
+S0,done,"doc/SECURITY.md: complete"
+S0,done,"docs/general: begin writing"
+S0,done,"docs/api: begin writing"
+S0,done,"Remove link to internal site"
+S0,done,"VaryingParameters: enum BallotChaining { Prohibited, Allowed, Required, }"
+S0,done,"remove old EG 1.54 constants"
+S0,done,"exe: Under artifacts dir, first level dirs are specific to secrecy requirements"
+S0,done,"Ballot define data type"
+S0,done,"get fixeduint stuff out of bunna branch"
+S0,done,"Merge code from Anunay"
+S0,done,"doc/SUPPORT.md: complete"
+S0,done,"doc/README.md: complete"
+S0,done,"doc/CODE_OF_CONDUCT.md: complete"
+S0,done,"doc/BUILDING.md: complete"
+S0,done,"Complete all planned code reorganization/renaming"
+S0,done,"docs/implementation guide/References: complete"
+S0,done,"a trait for fn to_canonical_json()"
+S0,done,"many to_stdiowrite() methods have common code that could be factored into a common function"
+S0,done,"a trait for types that have to_stdiowrite()"
+S0,done,"a trait for types that have to_stdiowrite() and perhaps _pretty() and _canonical() variants"
+S0,done,"serialize bignums only all as uppercase hex"
+S0,todo,"What is a Preencrypted Ballot called after Voter Selections have been applied?"
+S3.a.g,todo,"TODO: Do we need separate Administrative (Public|Secret) Key pairs for encryption and signing operations?"
+S3.a.g,todo,"TODO: How is it configured which specific other data is to be encrypted with which of the Joint Ballot Data Encryption Public Key and/or Administrative Public Key?"
+S3.1.3n,todo,"If the effective Contest Selection Limit is > 1, could someone evade the Option Selection Limit by both selecting and writing-in the same candidate? Similarly if multiple write-in fields are allowed, couldn't they write-in the same choice multiple times?"
+S3.2.c,todo,"(Ref: S3.a.a.b) ""EGRI enables the same set of Guardians to re-use their keys from previous elections (TODO: Don't n, k, p, q, g, etc have to remain the same?)"""
+S3.2.2.a,todo,"eq8 pg22 refers to ""the secret key for guardian $G_i$"" ""the public key for guardian $G_i$"" Are these keys ever really used as such in v2.1.0 ?"
+S3.2.2.o,todo,"EGRI supports a Guardian `l` in complaining to the Election Administrator and all other Guardians. TODO: In practice this likely implies providing a set of data TBD."
+S3.5.b.verif9,todo,"TODO: Verification 9"
+S3.6.1,todo,"TODO: Presumably this (""enables a Guardian to review the set of Ciphertexts marked for decryption"") requirement applies to any use of the Guardian Ballot Data Encryption Secret Key as well? -> xreq S3.6.1 EGRS enables a Guardian to review the set of Ciphertexts marked for decryption prior to use of their Guardian Ballot Data Encryption Secret Key."
+S3.6.1,todo,"Does EGRI need to determine whether write-in fields may actually be relevant to an outcome, or just always decrypt all write-in fields with every Tally?"
+S3.6.1,todo,"Presumably, many Ballots will not have any write-in fields actually written-in. Does each Ballot record whether it has a write-in field written-in in a way that avoids the need to decrypt the ballot nonce during the Tally if write-in values are needed?"
+S3.6.6.a,todo,"""[write-in] data may need to be decrypted if the tallies record a significant number"
+S3.7,todo,"The Election Record records for every Ballot Decryption Operation: for every participating Guardian: for every Ballot in the `Challenged` state: the partial decryption of the Ballot Nonce"
+S3.7,todo,"The Election Record records for every Ballot Decryption Operation: for every participating Guardian: for every Ballot in the `Challenged` state: for every Contest, for every Option Field, the partial decryption"
+S3.7The,todo,"Election Record records for every Tally: for every Contest: for every (Option or Additional) homomorphically-tallied Data Field: the partial decryption from each available Guardian?"
+S4.1,todo,"pg. 58 ""in a contest where a voter is allowed to make multiple selections, multiple pre-encryption vectors can be combined to form a single contest encryption vector with multiple encryptions of one that precisely matches the standard \EG format."""
+S4.1,todo,"pg. 58 QUESTION: How are they ""combined""? E.g., are these multiple encryptions combined such that there is still a single vector `Psi_{i,m}` for Option `i`, or are there additional Option vectors? Note: [S4.1.4 pg. 63] says ""For contests with selection limit greater than 1, the selection vectors published in the election record match the product of the pre-encryptions associated with the short codes listed as selected"", which seems to imply they are multiplied."
+S4.1,todo,"pg. 58 QUESTION: What about when the effective Option Selection Limit is greater than `1`? Do all possible assignments within the effective (Option and Contest) Selection Limits require distinct Selection Vectors and Selection Hashes? E.g. say a Contest has two options and the Contest and Option Selection Limits are all `5`. How is the selection vector constructed which allows the voter to apply a value of `3` to Option 1 and `2` to Option 2?"
+S4.1,todo,"pg. 58 QUESTION:  How to these ""multiple pre-encryption vectors"" map to ""the j-th selection vector"" and ""the k-th encryption"" referred to in [S4.2.1 eq. 121 pg. 61] to derive xi_{i,j,k}?"
+S4.1.1,todo,"pg. 58 QUESTION: S4.1 pg. 57 designates the ""null form"" explicitly as `Psi_{0,m}`, but (eq. 114 pg. 58) refers to them as `psi_{m+l}` where `1 <= l <= L`. How to these multiple pre-encryption vectors map to ""the j-th selection vector"" and ""the k-th encryption"" referred to in [S4.2.1 eq. 121 pg. 61] to derive xi_{i,j,k}?"
+S4.1.4,todo,"pg. 59 EGRS says ""A pre-encrypted ballot’s hash will typically be printed directly on the ballot. Ideally, two copies of the ballot hash will be included on each ballot with one remaining permanently with the ballot and the other in an immediately adjacent location on a removable tab. These removable ballot codes are intended to be retained by voters and can be used as an identifier to allow voters to look up their (encrypted) ballots in the election record and confirm that they include the proper short codes as described below."""
+S4.4,todo,"pg. 62 refers to ""every pre-encrypted ballot listed in the election record as uncast"". QUESTION: Does this imply that every `PreencryptedBallot` generated is recorded in the Election Record?"
+S4.4,todo,"pg. 63 states that ""For each uncast ballot, the ballot nonce for that ballot is published in the encryption record."" and [S4.5 pg. 64] refers to ""every pre-encrypted ballot listed in the election record as uncast"". QUESTION: Does this imply that there is a point during the tally process at which generated-but-not-cast `PreencryptedBallots` are no longer accepted? If there are multiple Tallys taken, then it seems really important that this only happen at the final Tally. Someone who submitted a PreencryptedBallot that was somehow delayed in the mail probably does not want their Voter Selections made public."
+S7,todo,"TODO: Consider any special features which may be needed for RLAs"

other/spec-todo/TODO-2.1.txt.db.pages.csv

@@ -0,0 +1,6 @@
+line_n,page_n
+6803,60
+7342,69
+7425,70
+7525,71
+7628,72