abstimm-idD/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)
```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.