An election in ElectionGuard is defined as a set of metadata and cryptographic artifacts necessary to encrypt, conduct, tally, decrypt, and verify an election. The Data format used for election metadata is based on the NIST Election Common Standard Data Specification but includes some modifications to support the end-to-end cryptography of ElectionGuard.
Election metadata is described in a specific format parseable into an
ElectionDescription and it's validity is checked to ensure that it is of an appropriate structure to conduct an End-to-End Verified ElectionGuard Election. ElectionGuard only verifies the components of the election metadata that are necessary to encrypt and decrypt the election. Some components of the election metadata are not checked for structural validity, but are used when generating a hash representation of the
ElectionDescription we derive an
InternalElectionDescription that includes a subset of the elements from the
ElectionDescription required to verify ballots are correct. Additionally a
CiphertextElectionContext is created during the Key Ceremony that includes the cryptographic artifacts necessary for encrypting ballots.
- Election Manifest The election metadata in json format that is parsed into an Election Description
- Election Description The election metadata that describes the structure and type of the election, including geopolitical units, contests, candidates, and ballot styles, etc.
- Internal Election Description The subset of the
ElectionDescriptionrequired by ElectionGuard to validate ballots are correctly associated with an election. This component mutates the state of the Election Description.
- Ciphertext Election Context The cryptographic context of an election that is configured during the
- Description Hash a Hash representation of the original ElectionDescription.
- Define an election according to the
- Use the NIST Common Standard Data Specification as a guide, but note the differences in election.py and the provided sample manifest.
- Parse the
ElectionDescriptioninto the application.
- Define the encryption parameters necessary for conducting an election (see
- Create the Pubic Key either from a single secret, or from the Key Ceremony.
- Build the
import os from electionguard.election import ElectionDescription, InternalElectionDescription, CiphertextElectionContext from electionguard.election_builder import ElectionBuilder from electionguard.elgamal import ElGamalKeyPair, elgamal_keypair_from_secret # Open an election manifest file with open(os.path.join(some_path, "election-manifest.json"), "r") as manifest: string_representation = manifest.read() election_description = ElectionDescription.from_json(string_representation) # Create an election builder instance, and configure it for a single public-private keypair. # in a real election, you would configure this for a group of guardians. See Key Ceremony for more information. builder = ElectionBuilder( number_of_guardians=1, # since we will generate a single public-private keypair, we set this to 1 quorum=1, # since we will generate a single public-private keypair, we set this to 1 description=election_description ) # Generate an ElGamal Keypair from a secret. In a real election you would use the Key Ceremony instead. some_secret_value: int = 12345 keypair: ElGamalKeyPair = elgamal_keypair_from_secret(some_secret_value) builder.set_public_key(keypair.public_key) # get an `InternalElectionDescription` and `CiphertextElectionContext` # that are used for the remainder of the election. (internal_metadata, context) = builder.build()