Abstimm-ID Daemon - Dienst zum Erstellen von Abstimm-IDs (https://git.netzbegruenung.de/NB-Public/abstimm-id)
Go to file
Sven Seeberg bf98be6f5b
Fix PDF sigining path
2020-11-20 13:40:06 +01:00
php-public add documentation to functions and: 2020-11-04 20:12:50 +01:00
.gitignore fix shell linebreaks, ignore empty names 2020-11-03 22:56:50 +01:00
LICENSE Initial commit 2020-10-20 13:33:03 +02:00
README.md update readme, fix txt header date 2020-11-05 11:51:33 +01:00
config-template.ini cut memory in half to lower computing time on mobile 2020-11-05 12:48:00 +01:00
create-table.sql be more specific on table creation 2020-11-03 22:41:40 +01:00
functions.php Fix PDF sigining path 2020-11-20 13:40:06 +01:00
generate_hashes.sh Add hash generating bash script 2020-10-23 18:35:08 +02:00

README.md

Abstimm-ID Daemon

Abstimm-ID Daemon - Dienst zum Erstellen und Abfragen von Abstimm-IDs (https://git.netzbegruenung.de/NB-Public/abstimm-id).

Daemon for retrieving Argon2 hashes for user vote result lists. The program also comes with a result list sigining and publication function.

API definition

Register event

Creates an event for which hashes can be generated and retrieved. The event token should be regarded a secret. We use a UUID for the token.

Request Headers (endpoint requires SSL client certificate)

POST /register_event HTTP/1.1
Host: abstimmidd.netzbegruenung.de
Content-Type: application/json

Request Body

{
  "event_token": String   // Secret event token to identify event
}

Response

{
  "success": Boolean      // If the registration of the event was successful
}

Get vote ID

Retrieve hashes / vote IDs for a list of user names and a known event. If the hashes don't exist yet, they will be generated on-the-fly.

Request Headers (endpoint requires SSL client certificate)

POST /get_ids HTTP/1.1
Host: abstimmidd.netzbegruenung.de
Content-Type: application/json

Request Body

{
  "event_token": String,  // Secret event token to identify event
  "round": Number,        // nth vote round
  "user_names": [         // User names for which the hash should be retrieved
    String,
    [...]                 // Repeated for all users for which the hash is needed
  ]
}

Response

[
  {
    "round": Number,      // nth vote round
    "user_name": String,  // Name of a user
    "hash": String        // Argon2 hash of user with round in the salt 
  },
  [...]                   // Repeated for all users listed in request
]

Create result export

Create vote result files to allow for validation the results. The files can be synchronized to a remote location for publication. Currently implemented are TXT and PDF files. The SHA256 hashes of the files and the signing key ID are returned.

Request Headers (endpoint requires SSL client certificate)

POST /export_result HTTP/1.1
Host: abstimmidd.netzbegruenung.de
Content-Type: application/json

Request Body

{
  "event_token": String,          // Secret event token to identify event
  "event_title": String,          // Used in export file name
  "vote_round": Number,           // nth vote round
  "votes": [
    {
      "hash": String,
      "vote": [
        String,                   // Description of vote (against, for, abstinence, name of nominee, etc)
        [...]                     // Repeated if multiple votes are possible
      ]
    },
    [...]                         // Repeated for each voter
  ]
}

Response

{
  "success": Boolean,     // Registration of event was successful
  "hash_txt": String,     // SHA256 hash of generated TXT file
  "hash_pdf": String,     // SHA256 hash of generated PDF file
  "signing_key": String   // ID of key used to sign result file
}

Pre-generate vote IDs

For large events with many votes, generating the vote IDs takes a long time. generate_hashes.sh helps to generate a large amount of hashes in advance, chunked in many smaller requests. The script uses the following parameters:

./generate_hashes.sh FILE_USERNAMES EVENT_ID VOTING_ROUNDS.

  • FILE_USERNAMES is the path to a text file containing the names of voters, one name per line.
  • EVENT_ID is the already existing token of an event.
  • VOTING_ROUNDS is the maximum number of expected voting rounds. To be sure, generate IDs for more rounds than expected.

The script expects the client key and certificate to be located in the same directory and to be named client.key and client.crt. Edit the script, if you need to change this. Also, the host URL is set in a variable within the script. If there are huge amounts of hashes that need to be generated, split the files with user names into smaller files, and run the script in parallel.