update readme, fix txt header date
This commit is contained in:
Christian Staudte
parent
e9a86d3dec
commit
0ad65d9b88
GPG Key ID:
88ED5070FE0D5F23
133
README.md
133
README.md
|
|
@ -3,100 +3,117 @@ Abstimm-ID Daemon - Dienst zum Erstellen und Abfragen von Abstimm-IDs (https://g
|
|||
|
||||
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
|
||||
```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,
|
||||
[...] // repeat 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 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
|
||||
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
|
||||
|
||||
### Request Body
|
||||
```javascript
|
||||
{
|
||||
"event_token": String // Secret event token to identify event
|
||||
"event_token": String // Secret event token to identify event
|
||||
}
|
||||
```
|
||||
### RESPONSE
|
||||
|
||||
### Response
|
||||
```javascript
|
||||
{
|
||||
"success": Bool // Registration of event was successful
|
||||
"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 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
|
||||
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
|
||||
|
||||
### Request Body
|
||||
```javascript
|
||||
{
|
||||
"event_token": String, // Secret event token to identify event
|
||||
"event_title": String, // used in export file name
|
||||
"vote_round": int, // nth vote round
|
||||
"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": VOTE_ID, "vote":
|
||||
[
|
||||
String, // Description of vote (against, for, abstinence, name of nominee, etc)
|
||||
[...] // repeat if multiple votes are possible
|
||||
{
|
||||
"hash": String,
|
||||
"vote": [
|
||||
String, // Description of vote (against, for, abstinence, name of nominee, etc)
|
||||
[...] // Repeated if multiple votes are possible
|
||||
]
|
||||
},
|
||||
[...] // repeat for each voter
|
||||
[...] // Repeated for each voter
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
### RESPONSE
|
||||
|
||||
### Response
|
||||
```javascript
|
||||
{
|
||||
"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
|
||||
"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 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 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.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ length = 16
|
|||
; %t - Title
|
||||
; %d - Date
|
||||
; %r - Vote Round
|
||||
header = Ergebnis der Abstimmung %r am %t - %t
|
||||
header = Ergebnis der Abstimmung %r am %d - %t
|
||||
pgpkey = ID
|
||||
|
||||
; if rawpath is set, the raw JSON will be saved into the directory
|
||||
|
|
|
|||
|
|
@ -157,8 +157,8 @@ class AbstimmIDd {
|
|||
|
||||
return [
|
||||
'success' => true,
|
||||
'sha256_txt' => $sha256_txt,
|
||||
'sha256_pdf' => $sha256_pdf,
|
||||
'hash_txt' => $sha256_txt,
|
||||
'hash_pdf' => $sha256_pdf,
|
||||
'signing_key' => $this->cfg['export']['pgpkey']];
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue