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

Get vote ID

Retrieve hashes / vote IDs for a list of user names and a known event.

REQUEST

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,
    [...]                 // repeat 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 Salt 
  },
  [...]                   // repeats for all users listed in request
]

Register event

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

REQUEST

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": Bool           // Registration of event was successful
}

Create result export

Create a signed file that is publicly accessible to validate the result. The SHA256 hash of the result file and the signing key ID are returned.

REQUEST

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": int,                    // nth vote round
  "votes": [
    { "hash": VOTE_ID, "vote": 
      [
        String,                         // Description of vote (against, for, abstinence, name of nominee, etc)
        [...]                           // repeat if multiple votes are possible
      ]
    },
    [...]                               // repeat for each voter
  ]
}

RESPONSE

{
  "success": Bool,          // Registration of event was successful
  "file_hash": Str,         // SHA256 hash of generated result file
  "signing_key": Str     // 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 relative path to a text file containing the names of voters, one name per line. EVENT_ID should be 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.