ElectionGuard Verify

An ElectionGuard Verifier, in Python

This repository contains an independent verifier for elections conducted using Microsoft's ElectionGuard system.

Overview

ElectionGuard Verify is a Python package and corresponding command line utility which cryptographically verifies the results of election's conducted using Microsoft's ElectionGuard system. This package takes as input the artifacts published as the results of an ElectionGuard election.

This code can be consumed as a Python package used within other applications or as a standalone command line utility.

Installation

ElectionGuard Verify can be installed via pip:

pip install electionguard-verify

Alternatively, it can be installed from source:

git clone https://github.com/nickboucher/electionguard-verify.git
pip install ./electionguard-verify

The installation requires Python 3.8+. This requirement is, unfortunately, set by the official electionguard Microsoft package which is consumed for useful data structure definitions.

The installation depends on the gmpy2 Python package, which is a high-performance library for general multi-precision arithmetic commonly used in cryptographic applications. Many OSs do not ship with the binaries required for this package to work. For example, if you experience installation issues with this dependency on MacOS, you can use the brew package manager to install the missing system dependencies via brew install libmpc mpfr. For other platforms, you can find various tutorials on installing this package's dependencies through your search engine of choice.

Usage

ElectionGuard Verify can be consumed as either a command line utility or a standard Python package.

Command Line Utility

The command line utility egverify is automatically installed and added to the PATH of your current Python environment during installation. This command line utility is the easiest way to use this verifier, as no additional code is required.

To begin verification of an election, simply run the following command:

egverify RESULTS_DIR

where RESULTS_DIR is the directory containing the artifacts published as the result of any ElectionGuard election. If no value is provided, the tool will run against the current working directory.

There are a variety of other options that can be specified, although most won't be necessary for standard elections. The key options are:

• -v, --verbose: This flag configures the verifier to output information about the verification steps while running.
• -n, --no-warn: This flag will silence all warnings that the verifier outputs. You probably don't want to specify this flag.

Additional options exist to override the default naming conventions of the files in RESULTS_DIR. It is very unlikely that these options will need to be specified. To view a full list of options, run egverify --help.

Python

ElectionGuard Verify can also be consumed as a standard Python package, thus allowing ElectionGuard elections to be verified programmatically as part of a larger software pipeline.

There is a single function called verify which will perform all steps required to cryptographically verify an ElectionGuard election. It can be imported as:

from electionguard_verify import verify

In order to invoke this function, though, you will need to supply it with a deserialized version of the election results. You will likely want to use the official Microsoft electionguard package to import the correct data structures and deserialization functions. An example of this can be found in electionguard_verify/command_line.py.

The typed function signature of verify is:

def verify(
    description: ElectionDescription,
    context: CiphertextElectionContext,
    constants: ElectionConstants,
    devices: Iterable[EncryptionDevice],
    ciphertext_ballots: Iterable[CiphertextAcceptedBallot],
    spoiled_ballots: Iterable[CiphertextAcceptedBallot],
    ciphertext_tally: PublishedCiphertextTally,
    plaintext_tally: PlaintextTally,
    coefficient_validation_sets: Iterable[CoefficientValidationSet] = None
) -> bool

The function returns True for a valid election and False for an invalid election. Logging verbosity level can be set using the Python standard library logging package.

Feedback

The author of this package invites anyone to review the code for implementation errors. Such a pursuit is likely performed most fruitfully in consultation with the ElectionGuard formal specification, which can be downloaded as human-readable document from the releases section of the primary Microsoft ElectionGuard repository. Knowledge of modular arithmetic and zero-knowledge proofs will also be helpful. Please open issues on GitHub for any discovered bugs.

Disclaimers

This codebase was developed independently of Microsoft. The original author, however, has a Microsoft affiliation as a full-time employee in a non-ElectionGuard organization within Microsoft.