You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository is a "reference implementation" of ElectionGuard written in Python3. This implementation can be used to conduct End-to-End Verifiable Elections as well as privacy-enhanced risk-limiting audits. Components of this library can also be used to construct "Verifiers" to validate the results of an ElectionGuard election.
7
+
This repository is a "reference implementation" of ElectionGuard written in Python 3. This implementation can be used to conduct End-to-End Verifiable Elections as well as privacy-enhanced risk-limiting audits. Components of this library can also be used to construct "Verifiers" to validate the results of an ElectionGuard election.
8
8
9
9
## 📁 In This Repository
10
10
@@ -40,7 +40,7 @@ has its own [installation requirements (native C libraries)](https://gmpy2.readt
40
40
41
41
## 🚀 Quick Start
42
42
43
-
Using [**make**](https://www.gnu.org/software/make/manual/make.html), the entire [Github Action workflow](.github/workflows/pull_request.yml) can be run with one command:
43
+
Using [**make**](https://www.gnu.org/software/make/manual/make.html), the entire [GitHub Action workflow](.github/workflows/pull_request.yml) can be run with one command:
44
44
45
45
```
46
46
make
@@ -64,7 +64,7 @@ For more detailed build and run options, see the [documentation](docs/Build_and_
-[Read the Docs](https://electionguard-python.readthedocs.io/)
69
69
70
70
Sections:
@@ -91,11 +91,11 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
91
91
92
92
### Reporting Issues
93
93
94
-
Please report any bugs, feature requests, or enhancements using the [Github Issue Tracker](https://github.com/microsoft/electionguard-python/issues). Please do not report any secirity vulnerabilities using the Issue Tracker. Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). See the [Security Documentation](SECURITY.md) for more information.
94
+
Please report any bugs, feature requests, or enhancements using the [GitHub Issue Tracker](https://github.com/microsoft/electionguard-python/issues). Please do not report any security vulnerabilities using the Issue Tracker. Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). See the [Security Documentation](SECURITY.md) for more information.
95
95
96
96
### Have Questions?
97
97
98
-
Electionguard would love for you to ask questions out in the open using Github Issues. If you really want to email the ElectionGuard team, reach out at electionguard@microsoft.com.
98
+
Electionguard would love for you to ask questions out in the open using GitHub Issues. If you really want to email the ElectionGuard team, reach out at electionguard@microsoft.com.
99
99
100
100
## License
101
101
This repository is licensed under the [MIT License](LICENSE)
Copy file name to clipboardExpand all lines: docs/0_Configure_Election.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
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](https://www.nist.gov/itl/voting/interoperability) but includes some modifications to support the end-to-end cryptography of ElectionGuard.
4
4
5
-
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 componets 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 gerating a hash representation of the `Election Description`.
5
+
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 `Election Description`.
6
6
7
7
From an `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](/1_Key_Ceremony.md) that includes the cryptographic artifacts necessary for encrypting ballots.
Copy file name to clipboardExpand all lines: docs/1_Key_Ceremony.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,15 @@
1
1
# Key Ceremony
2
2
3
-
The ElectionGuard Key Ceremony is the process used by Election Officials to share encryption keys for an election. Before an election, a fixed number of Guardians are selection to hold the private keys nedded to decrypt the election results. A Quorum count of Guardians can also be specified to compensate for guardians who may be missing at the time of Decryption. For instance, 5 Guardians may be selected to hold the keys, but only 3 of them are required to decrypt the election results.
3
+
The ElectionGuard Key Ceremony is the process used by Election Officials to share encryption keys for an election. Before an election, a fixed number of Guardians are selection to hold the private keys needed to decrypt the election results. A Quorum count of Guardians can also be specified to compensate for guardians who may be missing at the time of Decryption. For instance, 5 Guardians may be selected to hold the keys, but only 3 of them are required to decrypt the election results.
4
4
5
-
Guardians are typically Election Officials, Trustees Canvass Board Members, Government Officials or other trusted aruthorities who are responsible and accountable for conducting the election.
5
+
Guardians are typically Election Officials, Trustees Canvass Board Members, Government Officials or other trusted authorities who are responsible and accountable for conducting the election.
6
6
7
7
## Summary
8
8
9
9
The Key Ceremony is broken into several high-level steps. Each Guardian must _announce_ their _attendance_ in the key ceremony, generate their own public-private key pairs, and then _share_ those key pairs with the Quorum. Then the data that is shared is mathematically verified using Non-Interactive Zero Knowledge Proofs, and finally a _joint public key_ is created to encrypt ballots in the election.
10
10
11
11
### Attendance
12
-
Guardians exchange all public keys and ensure each fellow gaurdian has received an election and auxiliary public key ensuring at all guardians are in attendance.
12
+
Guardians exchange all public keys and ensure each fellow guardian has received an election and auxiliary public key ensuring at all guardians are in attendance.
13
13
14
14
### Key Sharing
15
15
Guardians generate a partial key backup for each guardian and share with that designated key with that guardian. Then each designated guardian sends a verification back to the sender. The sender then publishes to the group when all verifications are received.
Copy file name to clipboardExpand all lines: docs/3_Cast_and_Spoil.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,8 +31,8 @@ Once all of the ballots are marked as _cast_ or _spoiled_, all of the encryption
31
31
-**Ballot Store** A repository for retaining cast and spoiled ballots.
32
32
-**Cast Ballot** A ballot which a voter has accepted as valid to be included in the official election tally.
33
33
-**Spoiled Ballot** A ballot which a voter did not accept as valid and is not included in the tally.
34
-
-**Unknown Ballot** A ballot which may not yet be determiend as cast or spoiled, or that may have been spoiled but is otherwise not published in the election results.
35
-
-**Homomorphic Tally** An encrypted representation of every selection on every ballt that was cast. This representation is stored in a `CiphertextTally` object.
34
+
-**Unknown Ballot** A ballot which may not yet be determined as cast or spoiled, or that may have been spoiled but is otherwise not published in the election results.
35
+
-**Homomorphic Tally** An encrypted representation of every selection on every ballot that was cast. This representation is stored in a `CiphertextTally` object.
36
36
37
37
## Process
38
38
@@ -46,7 +46,7 @@ Once all of the ballots are marked as _cast_ or _spoiled_, all of the encryption
46
46
47
47
The ballot box can be interacted with via a stateful class that caches the election context, or via stateless functions. The following examples demonstrate some ways to interact with the ballot box.
48
48
49
-
Depending on the specific election workflow, the `BallotBox`class may not be used for a given election. For instance, in one case a ballot can be **accepted** directly on an electionic device, in which case there is no `BallotBox`. In a different workflow, a ballot may be explicitly cast or spoiled in a later step, such as after printing for voter review.
49
+
Depending on the specific election workflow, the `BallotBox`class may not be used for a given election. For instance, in one case a ballot can be **accepted** directly on an electronic device, in which case there is no `BallotBox`. In a different workflow, a ballot may be explicitly cast or spoiled in a later step, such as after printing for voter review.
50
50
51
51
In all cases, a ballot must be marked as either `cast` or `spoiled` to be included in a tally result.
Copy file name to clipboardExpand all lines: docs/4_Decrypt_Tally.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,14 +10,14 @@ During the [Key Ceremony](1_Key_Ceremony.md) a `Quorum of Guardians` is defined
10
10
11
11
It is important to note that mathematically not every present guardian has to compute a `Partial Decryption Share` for every `Missing Guardian`. Only the `Quorum Count` of guardians are necessary to construct `Partial Decryption Shares` in order to compensate for any Missing Guardian.
12
12
13
-
In this implementation, we take an approach that utilizes all Available Guardians to compensate for Missing Guardians. When it is determined that guardians are missing, all available guardians each calculate a `Partial Decryption Share` for the missing guardian and publish the result. A `Quorum of Guardians` count of available `Partial Decryption Shares` is randomly selected from the pool of availalbe partial decryption shares for a given` Missing Guardian`. If more than one guardian is missing, we randomly choose to ignore the `Partial Decryption Share` provided by one of the Available Guardians whose partial decrypotion share was chosen for the previous Missing Guardian, and randomly select again from the pool of available Partial Decryption Shares. This ensures that all available guardians have the opportunity to participate in compensating for Missing Guardians.
13
+
In this implementation, we take an approach that utilizes all Available Guardians to compensate for Missing Guardians. When it is determined that guardians are missing, all available guardians each calculate a `Partial Decryption Share` for the missing guardian and publish the result. A `Quorum of Guardians` count of available `Partial Decryption Shares` is randomly selected from the pool of available partial decryption shares for a given` Missing Guardian`. If more than one guardian is missing, we randomly choose to ignore the `Partial Decryption Share` provided by one of the Available Guardians whose partial decryption share was chosen for the previous Missing Guardian, and randomly select again from the pool of available Partial Decryption Shares. This ensures that all available guardians have the opportunity to participate in compensating for Missing Guardians.
14
14
15
15
## Glossary
16
16
-**Guardian** A guardian of the election who holds the ability to partially decrypt the election results
17
17
-**Decryption Share** A guardian's partial share of a decryption
18
18
-**Encrypted Tally** The homomorphically-combined and encrypted representation of all selections made for each option on every contest in the election. See [Ballot Box]() for more information.
19
19
-**Key Ceremony** The process conducted at the beginning of the election to create the joint encryption context for encrypting ballots during the election. See [Key Ceremony](1_Key_Ceremony.md) for more information.
20
-
-**Quorum of Guardians** The mininimum count (_threshold_) of guardians that must be present in order to successfully decrypt the election results.
20
+
-**Quorum of Guardians** The minimum count (_threshold_) of guardians that must be present in order to successfully decrypt the election results.
21
21
-**Available Guardian** A guardian that has announced as _present_ for the decryption phase
22
22
-**Missing Guardian** A guardian who was configured during the `Key Ceremony` but who is not present for the decryption of the election results.
23
23
-**Compensated Decryption Share** - a partial decryption share value computed by an available guardian to compensate for a missing guardian so that the missing guardian's share can be generated and the election results can be successfully decrypted.
@@ -30,13 +30,13 @@ In this implementation, we take an approach that utilizes all Available Guardian
30
30
31
31
### Decryption when All Guardians are Present
32
32
33
-
3. If all guardians are present, the Decrypion Shares are combined to generate a tally for each option on every contest
33
+
3. If all guardians are present, the Decryption Shares are combined to generate a tally for each option on every contest
34
34
35
35
### Decryption when some Guardians are Missing
36
36
37
37
_warning: The functionality described in this segment is still a 🚧 Work In Progress_
38
38
39
-
When one or more of the Guardians are missing, any subset of the Guardians that are present can use the information they have about the other guardian's prviate keys to reconstruct the partial decryption shares for the missing guardians.
39
+
When one or more of the Guardians are missing, any subset of the Guardians that are present can use the information they have about the other guardian's private keys to reconstruct the partial decryption shares for the missing guardians.
40
40
41
41
4. Each `Available Guardian` computes a `Partial Decryption Share` for each `Missing Guardian`
42
42
5. at least a `Quorum` count of `Partial Decryption Shares` are chosen from the values generated in the previous step for a specific `Missing guardian`
@@ -47,7 +47,7 @@ When one or more of the Guardians are missing, any subset of the Guardians that
47
47
48
48
## Challenged/Spoiled Ballots
49
49
50
-
If a ballot is not to be included in the vote count, it is considered challenged, or [Spoiled](https://en.wikipedia.org/wiki/Spoilt_vote). Every ballot spoiled in an election is invidually verifiably decrypted in exactly the same way that the aggregate ballot of tallies is decrypted. Since spoiled ballots are not included as part of the vote count, they are included in the Election Record with their plaintext values included along with the encrypted representations.
50
+
If a ballot is not to be included in the vote count, it is considered challenged, or [Spoiled](https://en.wikipedia.org/wiki/Spoilt_vote). Every ballot spoiled in an election is individually verifiably decrypted in exactly the same way that the aggregate ballot of tallies is decrypted. Since spoiled ballots are not included as part of the vote count, they are included in the Election Record with their plaintext values included along with the encrypted representations.
51
51
52
52
Spoiling ballots is an important part of the ElectionGuard process as it allows voters to explicitly generate challenge ballots that are verifiable as part of the Election Record.
Copy file name to clipboardExpand all lines: docs/Design_and_Architecture.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,7 +40,7 @@ For both naming purposes and usability, union classes are generally preferred. T
40
40
41
41
### 🚫 Exceptions
42
42
43
-
To allow for easier transliteration, the library will not raise exception across the API boundary since this is not available in all languages. Instead, the library will have a variety of functions that indicate failures by returning `None`; the caller is expected to check if the result is `None` before any further processing. Python3`typing` calls this sort of result `Optional`.This tactic also indicates all exceptions raised are expected to be from bugs.
43
+
To allow for easier transliteration, the library will not raise exception across the API boundary since this is not available in all languages. Instead, the library will have a variety of functions that indicate failures by returning `None`; the caller is expected to check if the result is `None` before any further processing. Python 3`typing` calls this sort of result `Optional`.This tactic also indicates all exceptions raised are expected to be from bugs.
44
44
45
45
### 🚫 Multiple Inheritance
46
46
@@ -58,7 +58,7 @@ The library contains a `Pipfile` that can be used with `pipenv`to ensure the cor
58
58
59
59
#### Folder Structure
60
60
61
-
The folder structure is kept to a bare minimum. The ElectionGuard library is located in `src/electionguard` and tests are in `tests`. Standalone applications or other pieces should be in seperate subdirectories. For example, the `bench` directory contains a simple Chaum-Pedersen proof computation benchmark.
61
+
The folder structure is kept to a bare minimum. The ElectionGuard library is located in `src/electionguard` and tests are in `tests`. Standalone applications or other pieces should be in separate subdirectories. For example, the `bench` directory contains a simple Chaum-Pedersen proof computation benchmark.
62
62
63
63
#### Commands
64
64
@@ -70,7 +70,7 @@ The library uses several tools to assist developers in maintaining clean code. V
70
70
71
71
#### Typing
72
72
73
-
The library uses Python3's**type hints** throughout and ensures return types are defined. **[Mypy](https://mypy.readthedocs.io/en/stable/)** is used to statically check the typing.
73
+
The library uses Python 3**type hints** throughout and ensures return types are defined. **[Mypy](https://mypy.readthedocs.io/en/stable/)** is used to statically check the typing.
74
74
75
75
#### Linting
76
76
@@ -88,7 +88,7 @@ The goal of the project is 100% code coverage with an understanding that there a
88
88
89
89
Property testing is helpful for [testing certain properties](https://fsharpforfunandprofit.com/posts/property-based-testing-2/). The library uses [Hypothesis](https://hypothesis.readthedocs.io/en/stable/) property-based testing to vigorously exercise the library. The library includes generator functions for all the core datatypes, making them easy to randomly generate.
90
90
91
-
### 🚀 Continous Integration
91
+
### 🚀 Continuous Integration
92
92
93
93
GitHub Actions are being used for continuous integration. Cross-platform is a primary goal and the workflows provided demonstrate how a developer can build in Linux, MacOS, and Windows.
0 commit comments