🗳 ElectionGuard C++

This repository is a "reference implementation" of an ElectionGuard ballot encryption library written in c++ and includes a C-compatible API for referencing the library from pure-c application. This core SDK performs ballot encryption and verification functions and is suitable for execution on voting system hardware and low powered devices. It is designed to be integrated into existing (or new) voting system software.

This repository is pre-release software to showcase the ElectionGuard API implemented in a native language. It is not feature complete and should not be used for production applications.

📁 In This Repository

File/folder	Description
`.github`	Github workflows and issue templates
`.vscode`	VS Code configurations
`/bindings`	Binding interfaces for different languages
`/cmake`	`CMake` dependencies`
`/include`	Public include headers
`/src`	ElectionGuard source code
`/test`	Unit tests
`.clang-format`	Style guidelines
`.gitignore`	Define what to ignore at commit time.
`CmakeLists.txt`	Root CMake file
`CHANGELOG.md`	List of changes to the sample.
`CONTRIBUTING.md`	Guidelines for contributing to the sample.
`README.md`	This README file.
`LICENSE`	The license for the sample.

❓ What Is ElectionGuard?

ElectionGuard is an open source software development kit (SDK) that makes voting more secure, transparent and accessible. The ElectionGuard SDK leverages homomorphic encryption to ensure that votes recorded by electronic systems of any type remain encrypted, secure, and secret. Meanwhile, ElectionGuard also allows verifiable and accurate tallying of ballots by any 3rd party organization without compromising secrecy or security.

Learn More in the ElectionGuard Repository

🦸 How Can I use ElectionGuard?

ElectionGuard supports a variety of use cases. The Primary use case is to generate verifiable end-to-end (E2E) encrypted elections. The ElectionGuard process can also be used for other use cases such as privacy enhanced risk-limiting audits (RLAs). This implementation only includes encryption functions and cannot be used to generate election keys and it cannot decrypt tally results.

This c++ implementation also includes a C API that can be consumed from anywhere that can call C code directly. A .Net Standard package is also provided.

💻 Requirements

All Platforms

A C++17 standard compliant compiler is required to build the core library. While any modern compiler should work, the library is tested on a subset. Check out the GitHub actions to see what is officially supported.
GNU Make is used to simplify the commands and GitHub Actions. This approach is recommended to simplify the command line experience. This is built in for MacOS and Linux. For Windows, setup is simpler with Chocolatey and installing the provided make package. The other Windows option is manually installing make.
CMake is used to simplify the build experience.

🤖 Android

To build for android, you need the Android SDK and platforms 21 and 26. The easiest way is to download android studio. Alternatively, you can use the SDK installation that ships with the Xamarin Tooling in Visual Studio. WE also require the use of the Android NDK. Android builds can be compiled on Linux, Mac, or Windows

🌐 .NET

A .NET Standard binding library is provided so that this package can be consumed from C# applications. At this time, only Android and iOS binaries are included and they can be consumed from a Xamarin application. Building for Xamarin currently requires a Mac

Other dependencies for Android and iOS
Visual Studio for Mac
NuGet Command Line (CLI)

🍏 iOS

To build for iOS you need XCode installed

XCode and the Command Line Tools for XCode
CMake 3.19 may be necessary, along with changes to the Makefile. See ISSUE #138

🖥️ Windows (using MSYS2)

Building on windows is currently supported using the MSYS2 toolchain. MSVC support will be included in a future release.

Install Chocolatey
Install Powershell Core
Install MSYS2
Open the MSYS2 prompt by running the newly-created "MSYS2 MSYS" shortcut in your start menu.
Inside the prompt, run pacman -Syu, then close the window when it prompts you to.

Reopen the MSYS2 prompt and run:

pacman -Syu
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake make

Modify your %Path% to include the newly-installed software. You should include these two paths:
```
C:\msys64\mingw64\bin
C:\msys64\usr\bin
```

🚧 The Procedure Entry Point Could not be Located

When compiling with shared libraries, you may encounter an error running the unit tests project. This is likely due to windows resolving the incorrect implementation of libstdc++-6.dll. Solving this depends on your use case, but you can either ensure that the path modifications made above appear before any other paths which include this library (e.g. c\Windows\System32), or you can include a copy of the correct DLL in the output folder. See this StackOverflow post for more information

Build

Using make,

To Download Dependencies

make environment

Build the Library for the current host (Release)

make build

Build the Library for the current host (Debug)

export TARGET=Debug && make build

Build for android

The Android Build currently Targets API Level 26 but can be configured by modifying the Makefile

Set the path to the NDK, replacing the version with your own

export NDK_PATH=/Users/$USER/Library/Android/sdk/ndk/21.3.6528147 && make build-android

Build for iOS

The iOS build currently targets iPhone OS 12 but can be configured by modifying the Makefile

Creates a fat binary for the simulator and targets a recent version of iOS

make build-ios

Build for Windows

make build

Build for Xamarin

Wraps the android and iOS build artifacts in a NuGet package to be consumed from a Xamarin application (classic or forms)

Must be executed on OS X to successfully built the iOS project.

make build-netstandard

Test

Running the C++ and C tests

make test

Running the netstandard tests

You can run the .Net Standard tests using the Xamarin Test runner on the iOS simulator.

# ensure the iOS and Android binaries are built
make build-netstandard

Then, open Visual studio for Mac and run the ElectionGuard.Tests.iOS project.

📄 Documentation

Contributing

This project encourages community contributions for development, testing, documentation, code review, and performance analysis, etc. For more information on how to contribute, see the contribution guidelines

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Reporting Issues

Please report any bugs, feature requests, or enhancements using the GitHub Issue Tracker. 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. See the Security Documentation for more information.

Have Questions?

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.