120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# 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)
|
|
```http
|
|
POST /register_event HTTP/1.1
|
|
Host: abstimmidd.netzbegruenung.de
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### Request Body
|
|
```javascript
|
|
{
|
|
"event_token": String // Secret event token to identify event
|
|
}
|
|
```
|
|
|
|
### Response
|
|
```javascript
|
|
{
|
|
"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)
|
|
```http
|
|
POST /get_ids HTTP/1.1
|
|
Host: abstimmidd.netzbegruenung.de
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### Request Body
|
|
```javascript
|
|
{
|
|
"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
|
|
```javascript
|
|
[
|
|
{
|
|
"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)
|
|
```http
|
|
POST /export_result HTTP/1.1
|
|
Host: abstimmidd.netzbegruenung.de
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### Request Body
|
|
```javascript
|
|
{
|
|
"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
|
|
```javascript
|
|
{
|
|
"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.
|