Generic Issue

• Ensure this issue is not a bug report or feature request

Description
The [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin) link at the top of CONTRIBUTING.MD is broken.

Possible Solution
It should be [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11) instead.

Additional context/Screenshots

The icon does not show up alongside the text in a very discernible way. This icon could either be changed or enlarged or perhaps removed to provide a cleaner look.

Squidfunk reference material
https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/

Feature Request

Is your feature request related to a problem? Please describe.
We'd like the Discussions page to be more evident to new users so they know that's the place to discuss questions regarding the specification.

Describe the solution you'd like

• Add a link in the Contributing section of the Readme.md
• Add a link in the Contributing section of the index.md
• Friendly wording to encourage people to asks questions and make suggestions

This would be the link: https://github.com/microsoft/electionguard/discussions

• Create mkdocs setup including theme and deploy with CI
• Disable Wiki and move content within new mkdocs setup
• Setup Hacktoberfest information

Understanding what electionguard includes and specifically what certain implementations include is important. The expectation is some sort of table including different information for the mandatory pieces included in certain types of implementations and a descriptive list of features and how they work, perhaps with some links to the specifications.

This should be added to this page
www.electionguard.vote/overview/Features/

Feature Request

Create a JSON schema for each of the models in the electionguard-python repository. Use this mkdocs plugin to display the schema in documentation for easy consumption.

Tasks

• Create folder schema of JSON Schema

  • Election
    • Manifest
    • CiphertextElectionContext
    • ElectionConstants
    • EncryptionDevice
  • Ceremony
    • GuardianRecord
    • LagrangeCoefficientsRecord
  • Ballot
    • SubmittedBallot
    • CiphertextBallot
    • PlaintextBallot
  • Tally
    • PlaintextTally
    • CiphertextTally
    • PublishedCiphertextTally (Until adjustments made)

• Document

  • Under a Data Format section, add brief description and then link to pages for each of the previous schemas as individual pages with a brief description and using the mkdocs plugin to display schema file. It should target https://www.electionguard.vote/spec/Data_Format/

There were many news articles and a blog post about the February 18, 2020 ElectionGuard test in Fulton, Wisconsin, but nothing since. I've searched for a followup post about those results, or if ElectionGuard will make its way into any future election technology?

Feature Request

Using shields, create a page within the Specification that displays ElectionGuard Badges.

Navigation:

• Specification
  • Current
  • Badges <--
  • Other Versions

Under Badges.md,

Badges

For your convenience, these are some badges to add to your repository indicating the specification your code supports.

Then list the badges with their shown image and a code line with a line that can be copy pasted.

[![ElectionGuard Specification 0.85.0](https://img.shields.io/badge/🗳%20ElectionGuard%20Specification-0.85.0-green)](https://www.electionguard.vote)

[![ElectionGuard Specification 0.95.0](https://img.shields.io/badge/🗳%20ElectionGuard%20Specification-0.95.0-green)](https://www.electionguard.vote)

[![ElectionGuard Specification 1.0.0](https://img.shields.io/badge/🗳%20ElectionGuard%20Specification-1.0.0-yellow)](https://www.electionguard.vote)

There should be a badge for all versions. 1.0.0 should be shown in yellow.
These badges should replace the badges on each of the specification pages.

Description

The Compact Ballot is a unique use case that is implemented in the python repository. Explain the use of the compact ballot and the way sequence order is handled.

Feature Request

There are five electionguard repositories. These labels can change from time to time. Create a way to sync these and ensure they are the same.

Starter glossary in markdown that can be used to explain terms and consolidate terms

Acceptance Criteria:

• Plain English language that a non technical user can understand.

Writing a Verifier

To write a basic verifier there are two main parts:
1. Ballot Verifier
2. Decryption Verifier

To build a complete verifier consists of verifying the integrity of every ballot cast in an election and verifying that the aggregate ballot (formed by combining each of he individual cast ballots) and that all of the spoiled ballots have been correctly decrypted.

The steps provided by Dr. Josh Benaloh himself are listed here:
📝 Building a Verifier
📝 Verifier Construction

This example verifier was completed by a set of Josh Benaloh's students at University of Washington:
📝 Example Verifier by Rainbow Huang

The Ask

We'd love to see any part of a verifier.

1. Grab our sample data
2. Code your verifier
   Note: Any language and any verifier counts. Verify just a single step or write a Ballot Verifier, Decryption Verifier, or complete Election Verifier.
3. Push it to GitHub
4. Create a PR to add your name and repo to the verifier list.

Ballot Verifier

Note: All steps reference Verifier Construction Document

Ballot verification consists of steps 3 and 4.

• Step 3 serves to verify that each encryption (corresponding to a selection made by a voter) is either an encryption of one (indicating that the voter selected this option) or an encryption of zero (indicating that the voter did not select this option). When the ballots are aggregated, each component will consist of an encryption of the number of times that option was selected – i.e., the tally. A malicious voting device could – possibly in collusion with a willing voter – encrypt a value other than one or zero and thereby compromise the integrity of the tally. Successful verification of the step 3 equations ensures that ballots are correctly formed.
• Step 4 serves to verify that the number of options selected for a contest to not exceed a pre-assigned limit (usually one). For instance, in most elections, a ballot should not be allowed to cast a vote for more than one option. This step can be omitted for yes/no referenda (voting both yes and no is equivalent to voting for neither) and for approval votes in which voters are permitted to vote for as many options s they wish.

Decryption Verifier

Note: All steps reference Verifier Construction Document

A decryption verifier serves to verify the correct decryption of a ballot and is normally applied to either an individual spoiled ballot (consisting entirely of encryptions of ones and zeros) or an aggregate ballot (consisting of encryptions of the election tallies). The decryption verification consists of steps 6 through 9 – although steps 7 and 8 can be omitted when all guardians have completed their election tasks.

• Step 6 begins with two equations that confirm that all individual cast ballots have been correctly aggregated. (This is omitted when applied to a single spoil ballot.) The remaining equations verify that the partial decryptions done by each guardian are correct.
• Steps 7 and 8 (Optional) confirm that any decryption data which one or more guardians has failed to provide have been correctly substituted for by a quorum of other guardians.
• Step 9 confirms that the partial decryptions provided by the guardians have been correctly combined to form a full decryption.

Above and Beyond

Note: All steps reference Verifier Construction Document

If you want more verification goodness, there are a few remaining steps to full verification of an election that are described here for completeness.

• Step 1 serves to verify the suitability of the parameters used in an election.
• Step 2 serves to verify the integrity of the public keys published by the election guardians. Although public verification of this step is desirable, it would suffice to have the guardians simply take responsibility for checking each other.
• Step 5 serves to verify that the ballots in an election have been correctly linked. This makes it more difficult for an election administrator to simply discard ballots in hopes that no one will notice.
• Step 10 is implicitly included within the description of the decryption verifier.

Stuck?

Post questions here or send them to [email protected]

Generic Issue

• Ensure this issue is not a bug report or feature request

Description
On "Code" page of this github repository there's a misspelling in the project description. I don't believe this is part of the source tree.

ElectionGuard is a set of open source software components that can be used to create and publish end to end veriable elections as well create a publishable artifact for ballot comparison audits.

Possible Solution

ElectionGuard is a set of open source software components that can be used to create and publish end to end verifiable elections as well create a publishable artifact for ballot comparison audits.

Additional context/Screenshots
None.

In your documentation for Election Manifest, it states "The election terms and structure are based whenever possible on the NIST SP-1500-101 Election Event Logging Common Data Format Specification...". The structures you listed actually come from the NIST 1500-100 Election Results Reporting specification https://github.com/usnistgov/ElectionResultsReporting. The sample Google implementation you linked to is also an implementation of 1500-100 (not 101). I suggest you fix the language and the link to the spec. Thanks!

Description

Sample data to represent the spec should be present at the top level to whatever the current spec is. This should assist in others to understand what is required from the spec. This also allows the other repo's to rely on the data in this repo instead of localized data in each repository.

The data should include all items to be imported and all items exported for a basic election. Everything from ballots to the manifest.

Data

The expectation is a data folder at the root of the repo

📂  data
---- 📂  minimal
-------- 📂  ballots
-------- 📂  artifacts
---- 📂  standard
-------- 📂  ballots
-------- 📂  artifacts
---- 📂  small
-------- 📂  ballots
-------- 📂  artifacts

Page

Add a page for the sample data with an appropriate name and link in the mkdocs.yml

The expectation is something like:

# Data

## Election Setup
Election Setup requires the use of an Election Manifest
Sample: standard | small | minimal

## Voting
Plaintext ballots are used during the voting process prior to encryption
Sample: standard | small | minimal

## Election Artifacts
At the end of the election, artifacts are used to verify elections. 
Sample: standard | small | minimal

Coillection of edits and suggestions for 0.95 spec to prepare for 1.0 release

0.95 Specification

Originally posted by @rc-ms in #56

To help describe items more visually, adding some illustrations from undraw with the electionguard color scheme could really help out. This would really help highlight certain sections.

https://undraw.co/illustrations

The slim ballot use case requires the use of proto files and will be the first venture into protobuf. These files should be added to this repository for maintaining clarity.

Generic Issue

• Ensure this issue is not a bug report or feature request

Description
The Verifier section of the README links out to a specifications document, but the link is broken.

Possible Solution
It seems likely that it should link to the Specification wiki

Additional context/Screenshots
N/A

In docs/guide/Implementations.md, everything except "Web-API" is under "Archived". At least the "Verifiers" should not be. I can send PR if I know which others are not archived.

Migrate links to the bottom of the page with reference style links. With the way that mkdocs functions. The plethora of links on each page requires a lot of updating. Switching to reference style links allows frequent linking but reduced effort on finding and fixing links with reorganization. This will essentially allow more flexibility.

https://www.markdownguide.org/basic-syntax/#reference-style-links

• Add reference links to the bottom of all pages (including images)
• Hook up all existing links
• Use easy to understand naming

Users should be encouraged to use non deprecated packages instead of downloading source code to reduce confusion.

In addition, the projects suggested for use should lead with the API and indicate how the project works.

Generic Issue

The project description has a typo.

Description
ElectionGuard is a set of open source software components that can be used to create and publish end to end veriable elections as well create a publishable artifact for ballot comparison audits.

Possible Solution
ElectionGuard is a set of open source software components that can be used to create and publish end to end verifiable elections as well create a publishable artifact for ballot comparison audits.

Generic Issue

License not displaying for readme due to capitalization error

Generic Issue

• Ensure this issue is not a bug report or feature request

Description
The default pull request template contains a checklist item referencing CONTRIBUTING.md. The link points nowhere.

Possible Solution

• Adjust link from ../CONTRIBUTING.md to ../blob/master/CONTRIBUTING.md

Generic Issue

• Ensure this issue is not a bug report or feature request

Description
Within the "Important" callout on the homepage (https://microsoft.github.io/electionguard/) are links to "Getting Started" and "Guide." These links point to the root site (e.g. /Getting_Started and /guide/overview), instead of relative to the ElectionGuard folder within the GitHub pages site (e.g. /electionguard/Getting_Started and /electionguard/guide/overview).

Possible Solution
Remove the leading / from the markdown links.

Generic Issue

• Ensure this issue is not a bug report or feature request

Description
README.md references CONTRIBUTING.md. The file's actual name is CONTRIBUTING.MD. (Note the difference in capitalization.)
As a result, the respective link on the repository's front page leads to a 404 error page.

Possible Solution

• Rename CONTRIBUTING.MD to CONTRIBUTING.md to match the remaining files

Bug Report

Current Behavior
Readme.md now shows that C++ repo is "coming soon"

Expected behavior/code
The readme should proudly state that the C++ repo is now public.

Environment
n/a

Possible Solution
n/a

Additional context/Screenshots
Add any other context about the problem here. If applicable, add screenshots to help explain.

When will the software be available to the public?

Bug Report

Current Behavior
Demo Tacking Site Link is https://demo.electionguard.com

Expected behavior/code
Demo Tacking Site Link should be https://demo.electionguard.vote

Environment
n/a

Possible Solution
Fix

Feature Request

Add Site Analytics to site using mkdocs and an analytics provider

See:
https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#custom-site-analytics

Feature Request

There are some new GitHub features when it comes to handling issues. We should take advantage of these and improve our issue menu and use the new issue forms.

In addition, updating our Contributing.md and PR templates at the same time.

• Change Community section to Contribute
• Create a Contribution page (pulling from the Community page)

This would be a great place to encourage, offer swag, and help point people to things they can do. This can highlight the community contributions and individuals that have participated in ElectionGuard. This slightly exists in the Getting Started Page but could be better off on it's on.

Generic Issue

Description
Issue to collect small edits and updates of specification documents: roadmap, 0.95 formulas and transcription errors, guide pages, glossary

Bug Report

Mermaid diagrams are not rendering properly on site.

Generic Issue

Grammatical and acronym errors on Readme

Bug Report

Current Behavior
Existing nav and theme formatting have insufficient contrast for accessibility; need to remove copyright info

Expected behavior/code
UX should exhibit contrast ratio of 4.5:1 for all text foreground/background display

Environment

• OS: [e.g. OSX 10.13.4, Windows 10]
• Version: [e.g. 1.0.1]

Possible Solution
increase contrast ratio by changing header and default

teal colors

Additional context/Screenshots
Add any other context about the problem here. If applicable, add screenshots to help explain.

Generic Issue

The Hamilton County dataset is missing

Users and contributors of ElectionGuard want to know what's coming next. It's time to make a roadmap so users know what is coming next. This should include what we have already done and what is coming up next.

This should be a page in the electionguard site but also mentioned on the ReadMe.md

Create a workflow to automatically publish sample election data in the Release based on the make sample generate data and a couple manifests.

This will include deleting the sample generator data outside manifests.

Depends on microsoft/electionguard-python#200

Generic Issue

Description
Two typos in docs/spec/1.0.0/3_Baseline_parameters.md

L7:

• Standard parameters for ElectionGuard begin with the largest 256-bit prime $q = 2256 − 189$. The hexadecimal representation of $q$ is as follows.

• Standard parameters for ElectionGuard begin with the largest 256-bit prime $q = 2^{256} − 189$. The hexadecimal representation of $q$ is as follows.

L25:

• The hexadecimal representation of $q$ is as follows:

• The hexadecimal representation of $p$ is as follows:

Possible Solution
See above

Bug Report

Current Behavior
Getting Started page is present but not linked up.

Expected behavior/code
Page should be linked up and in the correct location.

What are the target audiences of the ElectionGuard SDK? From the README, I suppose that the main target audience for the SDK will be election technology experts and election officials, right?

From what I understand of the blog post, the system will be end-to-end verifiable, and that presumes that not only it needs to be implemented by election authorities, but voters are also supposed to use an open source tool to verify, through homomorphic encryption calculations, whether or not their vote has been computed in the election results. It seems thus logical that it would have at least two separate open source tool sets:

• a back-end for election authorities to compute the votes
• a tool for voters to verify that their votes have been computed

Then, will the open source tool for voters also be released on Github, perhaps on another repo?

Generic Issue

• [X ] Ensure this issue is not a bug report or feature request

Description
The following sentence from README.md is missing a word.

“For instance, the ballot marking device could be replaced with an optical-scanner produces verifiable encrypted records, ...”

Possible Solution
Add ‘that’

For instance, the ballot marking device could be replaced with an optical-scanner that produces verifiable encrypted records, ...

Generic Issue

Description
Change master branch to main branch

Possible Solution
These are some quick instructions to follow, but the solution is at the top level to replace the branch name.
https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx

Generic Issue

Description
The key generation spec, and the associated verification, need a bit more clarity, particularly about what should happen when something goes wrong. At the moment, they generally assume reliable broadcast throughout, but the current implementation (and probably most future implementations) only have point-to-point communication.

Possible Solution
Perhaps we could assume a reliable broadcast step at the end, i.e. that the transcript of the key generation protocol is posted on the Bulletin Board (the precise definition/implementation of which can be deferred), and describe what attacker model can be defeated in that communication model.

Hacktoberfest is over and it's time for some cleanup.

1. This page will need deleting.
   https://github.com/microsoft/electionguard/blob/main/docs/Hacktoberfest.md
2. The overrides contain a banner that will need to be cleaned up.
3. The mkdocs file will need to have the links removed.

Feature Request

Add redirect from electionguard.vote/hacktoberfest -> electionguard.vote/contribute

This includes adding the redirects package.
https://github.com/datarobot/mkdocs-redirects
https://squidfunk.github.io/mkdocs-material/deprecations/#redirect

• Install line in make file
  pip install mkdocs-redirects

• Add redirect to mkdocs
  Example: May need changes

plugins:
    - redirects:
        redirect_maps:
            'hacktoberfest.md': 'contribute/index.md'

Feature Request

Is your feature request related to a problem? Please describe.

Convert the most current version of the specification to markdown so that it can be displayed by mkdocs.
https://github.com/microsoft/electionguard/releases/tag/v0.95.0

Describe the solution you'd like
We'd like the specifications to be as accessible and visible as possible. The first steps to this are having a easily a form that can be easily navigated to and traversed.

The material theme we use for mkdocs has some great examples of using arithmatex. The hope would that many of the equations could be displayed with this.
https://squidfunk.github.io/mkdocs-material/reference/mathjax/#arithmatex

This is currently highlighted at the lower level in electionguard-python docs but should get migrated to this repository.

See: https://electionguard-python.readthedocs.io/en/latest/

Pull from the step by step process in the python repository and create a non code version of these steps. This should highlight the basics of setting up and running an election.

There are some temporary pages to help determine where this should be added
All the pages needed to be added to docs/basics