Support external_ballot_identifer as a string

.github/workflows/pr-workflow.yml

@@ -22,14 +22,14 @@ jobs:
         cmake --version
         cmake -S . -B build
         cmake --build build
-    - name: 'Build Simple Election'
+    - name: 'Build API Sample Election'
       run: | 
-        ElectionGuard_DIR="$PWD/build/ElectionGuard" cmake -S examples/simple -B simple_build
-        cmake --build simple_build --target simple
-    - name: 'Test Simple Election'
+        ElectionGuard_DIR="$PWD/build/ElectionGuard" cmake -S examples/api -B api_build
+        cmake --build api_build --target api
+    - name: 'Test API Sample Election'
       run: | 
-        cd simple_build
-        ./simple
+        cd api_build
+        ./api
   windows_build:
     name: 'Windows Build'
     runs-on: 'windows-latest'
@@ -55,15 +55,15 @@ jobs:
         cmake --version
         cmake -S . -B build -G "MSYS Makefiles"
         cmake --build build
-    - name: 'Build Simple Election'
+    - name: 'Build API Sample Election'
       run: |
         $env:CMAKE_PREFIX_PATH="./build/ElectionGuard"
-        cmake -S examples/simple -B simple_build -G "MSYS Makefiles"
-        cmake --build simple_build --target simple
-    - name: 'Test Simple Election'
+        cmake -S examples/api -B api_build -G "MSYS Makefiles"
+        cmake --build api_build --target api
+    - name: 'Test API Sample Election'
       run: | 
-        cd simple_build
-        $outcome = Invoke-Expression ".\simple.exe"
+        $env:Path+=";.\build\"
+        $outcome = Invoke-Expression ".\api_build\api.exe"
         echo $outcome
   macos_build:
     name: 'MacOS Build'
@@ -82,11 +82,11 @@ jobs:
         cmake --version
         cmake -S . -B build
         cmake --build build
-    - name: 'Build Simple Election'
+    - name: 'Build API Sample Election'
       run: | 
-        ElectionGuard_DIR="$PWD/build/ElectionGuard" cmake -S examples/simple -B simple_build
-        cmake --build simple_build --target simple
-    - name: 'Test Simple Election'
+        ElectionGuard_DIR="$PWD/build/ElectionGuard" cmake -S examples/api -B api_build
+        cmake --build api_build --target api
+    - name: 'Test API Sample Election'
       run: | 
-        cd simple_build
-        ./simple
+        cd api_build
+        ./api

.gitignore

@@ -34,3 +34,7 @@ _deps
 ElectionGuardConfig.cmake
 *_build/
 ballots/
+
+ballots_encrypter/
+
+tallies/

CMakeLists.txt

@@ -12,8 +12,8 @@ set(CMAKE_C_EXTENSIONS OFF)
 message("Generated with config types: ${CMAKE_CONFIGURATION_TYPES}")
 
 IF(CMAKE_BUILD_TYPE MATCHES Debug)
-    message("setting DEBUG_PRINT")
-    add_compile_definitions(DEBUG_PRINT)
+    message("setting DEBUG during compile")
+    add_compile_definitions(DEBUG)
 ENDIF()
 
 
@@ -22,11 +22,13 @@ add_library(electionguard
     ${PROJECT_SOURCE_DIR}/src/electionguard/api/filename.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/api/create_election.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/api/encrypt_ballot.c
+    ${PROJECT_SOURCE_DIR}/src/electionguard/api/load_ballots.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/api/record_ballots.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/api/tally_votes.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/crypto_reps.h
+    ${PROJECT_SOURCE_DIR}/src/electionguard/voting/ballot_collection.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/voting/coordinator.c
-    ${PROJECT_SOURCE_DIR}/src/electionguard/voting/num_ballots.h
+    ${PROJECT_SOURCE_DIR}/src/electionguard/voting/messages.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/voting/message_reps.h
     ${PROJECT_SOURCE_DIR}/src/electionguard/voting/nouns.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/voting/tracker.c
@@ -54,6 +56,7 @@ add_library(electionguard
     ${PROJECT_SOURCE_DIR}/src/electionguard/keyceremony/trustee.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/uint4096.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/bignum.c
+    ${PROJECT_SOURCE_DIR}/src/electionguard/log.h
     ${PROJECT_SOURCE_DIR}/src/electionguard/sha2-openbsd.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/sha2-openbsd.h
     ${PROJECT_SOURCE_DIR}/src/electionguard/crypto.c
@@ -62,15 +65,15 @@ add_library(electionguard
     ${PROJECT_SOURCE_DIR}/src/electionguard/random_source.h
     ${PROJECT_SOURCE_DIR}/src/electionguard/random_source.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/trustee_state_rep.h
-    ${PROJECT_SOURCE_DIR}/src/electionguard/file.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/directory.c
     ${PROJECT_SOURCE_DIR}/src/electionguard/directory.h
+    ${PROJECT_SOURCE_DIR}/src/electionguard/uthash.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/api/config.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/api/create_election.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/api/encrypt_ballot.h
+    ${PROJECT_SOURCE_DIR}/include/electionguard/api/load_ballots.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/api/record_ballots.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/api/tally_votes.h
-    ${PROJECT_SOURCE_DIR}/include/electionguard/file.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/max_values.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/trustee_state.h
     ${PROJECT_SOURCE_DIR}/include/electionguard/voting/messages.h
@@ -109,8 +112,8 @@ if (MINGW)
     set_target_properties(electionguard PROPERTIES PREFIX "")
 endif()
 
-# Set the public include directory depending on if the target is being exported
-# or installed
+# Set the public include directory depending on 
+# if the target is being exported or installed
 target_include_directories(electionguard
     SYSTEM PUBLIC
         $<INSTALL_INTERFACE:include>
@@ -148,18 +151,9 @@ install(
 
 add_subdirectory(docs)
 
-file(MAKE_DIRECTORY  "${CMAKE_CURRENT_BINARY_DIR}/simple_build")
+file(MAKE_DIRECTORY  "${CMAKE_CURRENT_BINARY_DIR}/api_build")
 set(CMAKE_CONFIGURATION_TYPES "Debug" CACHE STRING "" FORCE)
 
-add_test(NAME build_simple
-   COMMAND "${CMAKE_COMMAND}"
-      -E env ElectionGuard_DIR=${CMAKE_CURRENT_BINARY_DIR}/ElectionGuard
-      "${CMAKE_CTEST_COMMAND}"
-        --build-and-test "${PROJECT_SOURCE_DIR}/examples/simple" "${CMAKE_CURRENT_BINARY_DIR}/simple_build"
-        --build-generator ${CMAKE_GENERATOR}
-        --test-command simple
-)
-
 add_test(NAME build_api
    COMMAND "${CMAKE_COMMAND}"
       -E env ElectionGuard_DIR=${CMAKE_CURRENT_BINARY_DIR}/ElectionGuard

CONTRIBUTING.md

@@ -14,7 +14,7 @@ If new to the project,
 2. Install according to [ReadMe](./README.rst)
 OR
 refer to [Documentation](https://electionguard.github.io/ElectionGuard-SDK-C-Documentation/)
-3. Once you're up and running, be sure to run the simple election test
+3. Once you're up and running, be sure to run the API sample election test
 
 ⚠ Note: If you get stuck, take a look at our [GitHub Action](./.github/workflows/pr-workflow.yml)
 

Makefile.mk

@@ -0,0 +1,67 @@
+.PHONY: add-dependencies build build-debug clean run-api test
+
+BUILD_DEBUG?=true
+
+.EXPORT_ALL_VARIABLES:
+ELECTIONGUARD_DIR="$(realpath .)/build/ElectionGuard"
+
+# Detect operating system
+ifeq ($(OS),Windows_NT)
+    OPERATING_SYSTEM := Windows
+else
+    OPERATING_SYSTEM := $(shell uname 2>/dev/null || echo Unknown)
+endif
+
+add-dependencies:
+ifeq ($(OPERATING_SYSTEM),Darwin)
+
+endif
+ifeq ($(OPERATING_SYSTEM),Linux)
+
+endif
+ifeq ($(OPERATING_SYSTEM),Windows)
+
+endif
+
+ifeq ($(BUILD_DEBUG),true)
+build: build-debug
+else
+build: build-release
+endif
+
+build-debug: clean
+	if [ ! -d "build" ]; then mkdir build; fi
+ifeq ($(OPERATING_SYSTEM),Windows)
+	cmake -S . -B build -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Debug
+else
+	cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
+endif
+	cmake --build build
+
+build-release: clean
+	if [ ! -d "build" ]; then mkdir build; fi
+ifeq ($(OPERATING_SYSTEM),Windows)
+	cmake -S . -B build -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
+else
+	cmake -S . -B build -DBUILD_SHARED_LIBS=ON
+endif
+	cmake --build build
+
+clean:
+	rm -rf ./build/* ./api_build/*
+
+run-api: build
+	if [ ! -d "api_build" ]; then mkdir api_build; fi
+ifeq ($(OPERATING_SYSTEM),Windows)
+	CMAKE_PREFIX_PATH="./build/ElectionGuard" cmake -S examples/api -B api_build -G "MSYS Makefiles"
+	cmake --build api_build --target api
+	PATH=$(PWD)/build:$$PATH; ./api_build/api
+else
+	ElectionGuard_DIR=$(ELECTIONGUARD_DIR) cmake -S examples/api -B api_build
+	cmake --build api_build --target api
+	./api_build/api
+endif
+
+test: build
+	cmake --build build --target test
+

README-windows.md

@@ -23,13 +23,13 @@
             cmake --build build
 
     3. You should now have a `electionguard.a` or `electionguard.dll` (depending on the how cmake was configured).
-3. (Optional) Build the simple example election driver.
+3. (Optional) Build the api example election driver.
     1. Open a command prompt and navigate to the directory with the ElectionGuard-SDK-C-Implementation repo.
     2. Run the following commands:
 
             set PATH=%PATH%;C:\path\to\ElectionGuard-SDK-C-Implementation\build\
             set CMAKE_PREFIX_PATH=C:\path\to\ElectionGuard-SDK-C-Implementation\build\ElectionGuard
-            cmake -S examples/simple -B simple_build -G "MSYS Makefiles"
-            cmake --build simple_build --target simple
+            cmake -S examples/api -B api_build -G "MSYS Makefiles"
+            cmake --build api_build --target api
 
-    3. You should now have a `simple.exe` that simulates some random voters and generates election record artifacts.
+    3. You should now have a `api.exe` that simulates some random voters and generates election record artifacts.

README.rst

@@ -53,11 +53,17 @@ To build the SDK static library ``libelectionguard.a``, run
 
    cmake --build build
 
+Alternatively there is a `Makefile` to wrap the cmake commands:
+
+.. code:: sh
+
+    make build
+
 Testing
 --------
 
-Currently you can exercise the SDK by running the :doc:`example client
-<examples/simple>`. We include a cmake test to do so automatically. You can
+Currently you can exercise the SDK by running the :doc:`api client
+<examples/api>`. We include a cmake test to do so automatically. You can
 also execute the client directly to better examine the output it produces.
 
 .. warning::
@@ -95,11 +101,17 @@ to refer to the built library, and build the client.
 
 .. code:: sh
 
-   mkdir simple_build
-   ElectionGuard_DIR="$PWD/build/ElectionGuard" cmake -S examples/simple -B simple_build
-   cmake --build simple_build --target simple
+   mkdir api_build
+   ElectionGuard_DIR="$PWD/build/ElectionGuard" cmake -S examples/api -B api_build
+   cmake --build api_build --target api
+
+The built binary should be located at :file:`api_build/api`.
+
+alternatively, you can use the convenience Makefile
+
+.. code:: sh
 
-The built binary should be located at :file:`simple_build/simple`.
+    make run-api
 
 
 Debugging

default.nix

@@ -6,5 +6,5 @@ let
   };
 in with import nixpkgs {}; rec {
   electionguard = callPackages ./derivation.nix { };
-  simple = callPackages ./examples/simple { inherit electionguard; };
+  api = callPackages ./examples/api { inherit electionguard; };
 }

docs/CMakeLists.txt

@@ -41,10 +41,16 @@ IF(BUILD_DOCUMENTATION)
       ${CMAKE_CURRENT_SOURCE_DIR}/examples.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/voting.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/keyceremony.rst
-      ${CMAKE_CURRENT_SOURCE_DIR}/examples/simple.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/examples/api.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/api/index.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/api/crypto.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/api/trustee_state.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/api/api/config.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/api/api/create_election.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/api/api/encrypt_ballot.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/api/api/load_ballots.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/api/api/record_ballots.rst
+      ${CMAKE_CURRENT_SOURCE_DIR}/api/api/tally_votes.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/api/voting/coordinator.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/api/voting/encrypter.rst
       ${CMAKE_CURRENT_SOURCE_DIR}/api/voting/messages.rst

docs/api/api/config.rst

@@ -0,0 +1,2 @@
+Config
+======

docs/api/api/create_election.rst

@@ -0,0 +1,2 @@
+Create Election
+===============

docs/api/api/encrypt_ballot.rst

@@ -0,0 +1,2 @@
+Encrypt Ballot
+==============

docs/api/api/load_ballots.rst

@@ -0,0 +1,2 @@
+Load Ballots
+============

docs/api/api/record_ballots.rst

@@ -0,0 +1,2 @@
+Record Ballots
+==============

docs/api/api/tally_votes.rst

@@ -0,0 +1,2 @@
+Tally Votes
+===========

docs/examples/api.rst

@@ -0,0 +1,19 @@
+API Example Client
+===============
+
+This simple client is designed to showcase the API by demonstrating
+the correct sequence of function calls used in an elecition.
+
+.. warning::
+
+   This example client **does not** do any sort of error handling in
+   order to more clearly highlight the "happy path" of an election.
+   Please do not use this code in a real system.
+
+:file:`main.c`
+--------------
+
+.. literalinclude:: /../examples/api/main.c
+   :language: c
+   :linenos:
+   :caption: main.c