DOCSEARCHbyAlgolia
Submit Docs

ElectionGuard Python SDK

repository·main·Indexed 41 days ago

https://github.com/election-tech-initiative/electionguard-python

A reference implementation of the ElectionGuard specification (v0.95.0) providing tools for end-to-end (E2E) verifiable elections and privacy-enhanced risk-limiting audits (RLAs) using homomorphic encryption. The SDK includes APIs for election configuration via ElectionBuilder, managing key ceremonies with Guardian and KeyCeremonyMediator, and encrypting ballots using EncryptionMediator.

Tokens
23K
Snippets
66
Records
105
Agent score
46%

What's inside ElectionGuard

  1. Overview of ElectionGuard Python components

    main

    The ElectionGuard Python repository contains several key packages and directories for conducting verifiable elections:

    • electionguard: The core ElectionGuard library.
    • electionguard_tools: Tools for testing and providing sample data.
    • electionguard_verifier: A verifier used to validate the validity of a ballot.
    • data: Contains sample election data for development and testing.
    • stubs: Type annotations for external libraries to support type checking.

  2. Overview of ElectionGuard Python capabilities

    main

    ElectionGuard Python is a reference implementation of the ElectionGuard specification (currently version 0.95.0). It is an SDK designed to make voting more secure and transparent using homomorphic encryption.

    Key capabilities include:

    • End-to-End (E2E) Verifiable Elections: Generating encrypted elections where votes remain secret but results can be verified by third parties.
    • Privacy-Enhanced Risk-Limiting Audits (RLAs): Using the SDK to conduct audits without compromising voter secrecy.
    • Verification: Using components like src/electionguard_verifier to validate the validity of ballots.

  3. Understand the ElectionGuard Python development workflow

    main

    The project follows an iteration-based workflow managed through GitHub Milestones. Each milestone represents a collection of issues and work that, once completed, triggers a formal release process.

    Key components of the workflow include:

    • Milestones: Used to track iterations and group work.
    • Issues: Used to define work and track progress on the project board.
    • Pull Requests: The mechanism for contributing code, which must be linked to an issue and pass automated validation.
    • Releases: Automated processes triggered by closing a milestone to distribute packages via PyPi and update documentation.

  4. Model Geographic Jurisdictions and Ballot Styles

    main

    To handle complex elections where different contests apply to different geographic areas (e.g., a single election containing Congress, State Assembly, and School District contests), the Election Manifest uses a hierarchy of Geographic Jurisdictions and Ballot Styles.

    Mental Model

    1. Geographic Jurisdictions: Define the areas (e.g., precinct, ward, or district) where the election takes place. These jurisdictions overlap in complex ways (e.g., a school district boundary might span multiple towns).
    2. Ballot Styles: Because different people in different jurisdictions see different contests, the manifest defines unique ballot styles. A ballot style is a specific subset of contests presented to a voter based on their location.
    3. Contests and Selections: A contest is a collection of available selections (choices).
      • Every selection in a contest must be associated with a candidate (including write-in candidates and referendum options).
      • Candidates may optionally be associated with parties.

  5. The ElectionGuard end-to-end process

    main

    The standard workflow for conducting an ElectionGuard election follows these five steps:

    1. Configure Election: Set up the election parameters.
    2. Key Ceremony: Generate the necessary cryptographic keys.
    3. Encrypt Ballots: Encrypt votes using the generated keys.
    4. Cast and Spoil: Manage the casting of ballots and the spoiling of invalid ones.
    5. Decrypt Tally: Decrypt the results to produce a verifiable tally.
    6. Publish and Verify: Make the results public and allow third-party verification.

  6. Note on Math Library and Performance

    main

    For high-performance encryption, the library uses gmpy2 (version 2.0.8) instead of Python's built-in types. When working with the library, be aware that it maps standard Python operations to gmpy2 equivalents for speed:

    • Integers: Uses mpz instead of int.
    • Exponents: Uses powmod instead of pow.

    This dependency is critical for the performance required by cryptographic operations.

  7. Understand the Election Manifest concept

    main

    An Election Manifest is a data structure that codifies the necessary information to conduct an election into a format ElectionGuard can use. It is based on the NIST SP-1500-101 Election Event Logging Common Data Format Specification.

    Key functions of the Election Manifest include:

    • Associating Ballots with Ballot Styles: It allows ElectionGuard to know which contests and selections are valid for a specific voter's ballot.
    • Data Verification: It is used to verify the accuracy of election data at various stages.
    • Validation: A well-defined manifest ensures that improperly formatted ballot encryption requests fail with error messages at the moment of initial encryption.

    Note: ElectionGuard does not handle the logic to prevent overvoting or malformed submissions; that responsibility lies with the encrypting device. The manifest's primary role is to define the valid structure so that invalid requests can be rejected.

  8. Configure Contests and Electoral Districts

    main

    A contest represents a specific election event (e.g., a referendum or a race for office). To ensure a contest is applied to the correct geographic area, it must be linked to a Geopolitical Unit.

    Key requirements for a contest:

    • electoralDistrictId: This field must be populated with the objectId of exactly ONE associated Geopolitical Unit.
    • sequenceOrder: An internal indexing mechanism used for processing. Note: This is not the display order shown to voters; the implementing application controls the user-facing display order.

    Example Mapping: If a contest is for 'Congressional District 7', its electoralDistrictId should match the objectId of the 'Congressional District 7' geopolitical unit.

  9. Understand the ElectionGuard Key Ceremony process

    main

    The Key Ceremony is the process used by Election Officials to share encryption keys for an election. It ensures that a set of Guardians (trusted authorities) hold the private keys necessary to decrypt election results without any single individual having full control.

    Core Concepts

    • Guardian: An official who holds the ability to partially decrypt election results.
    • Quorum (k): The minimum number of guardians required to decrypt the election results. This is typically less than the total number of guardians (n).
    • Election Key Pair: A public/secret key pair used for encryption and decryption.
    • Election Partial Key Backup: A point on a secret polynomial shared with other guardians to allow the derivation of the private key via a quorum.
    • Joint Key: The combined public key derived from all individual guardian public keys, used to encrypt ballots.

    High-Level Workflow

    1. Attendance: Guardians exchange public keys to ensure everyone is present.
    2. Key Sharing: Guardians generate and share election partial key backups with each other. These are mathematically verified using Non-Interactive Zero Knowledge Proofs.
    3. Joint Key Generation: Once all keys and backups are verified, the joint public key is published for use in the election.

  11. Handle API failures and errors

    main

    The library does not raise exceptions across the API boundary to ensure compatibility with other programming languages. Instead, functions indicate failures by returning None.

    Important: When calling API methods, you must check if the returned result is None before proceeding with any further processing. A None return value indicates a functional failure, whereas actual exceptions are reserved for indicating bugs in the implementation.

  12. Glossary of ballot encryption terms

    main

    Understanding the core abstractions used during the encryption process:

    • Plaintext Ballot: The plaintext representation of a voter's selections.
    • Ciphertext Ballot: The encrypted representation of a voter's selections.
    • Master Nonce: A random number used to derive encryptions in a CiphertextBallot.
    • Verification Code (or Ballot Code): A unique hash value generated by an EncryptionDevice to anonymously identify a ballot.
    • Encryption Device: The device performing the encryption.