update readme, fix txt header date
This commit is contained in:
parent
e9a86d3dec
commit
0ad65d9b88
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.
|
Daemon for retrieving Argon2 hashes for user vote result lists. The program also comes with a result list sigining and publication function.
|
||||||
|
|
||||||
|
|
||||||
# API definition
|
# 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
|
## Register event
|
||||||
Creates an event for which hashes can be generated and retrieved. The event token should be regarded a secret.
|
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
|
|
||||||
Request Headers - endpoint requires SSL client certificate
|
### Request Headers (endpoint requires SSL client certificate)
|
||||||
```http
|
```http
|
||||||
POST /register_event HTTP/1.1
|
POST /register_event HTTP/1.1
|
||||||
Host: abstimmidd.netzbegruenung.de
|
Host: abstimmidd.netzbegruenung.de
|
||||||
Content-Type: application/json
|
Content-Type: application/json
|
||||||
```
|
```
|
||||||
Request Body
|
|
||||||
|
### Request Body
|
||||||
```javascript
|
```javascript
|
||||||
{
|
{
|
||||||
"event_token": String // Secret event token to identify event
|
"event_token": String // Secret event token to identify event
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
### RESPONSE
|
|
||||||
|
### Response
|
||||||
```javascript
|
```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 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.
|
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
|
|
||||||
Request Headers - endpoint requires SSL client certificate
|
### Request Headers (endpoint requires SSL client certificate)
|
||||||
```http
|
```http
|
||||||
POST /export_result HTTP/1.1
|
POST /export_result HTTP/1.1
|
||||||
Host: abstimmidd.netzbegruenung.de
|
Host: abstimmidd.netzbegruenung.de
|
||||||
Content-Type: application/json
|
Content-Type: application/json
|
||||||
```
|
```
|
||||||
Request Body
|
|
||||||
|
### Request Body
|
||||||
```javascript
|
```javascript
|
||||||
{
|
{
|
||||||
"event_token": String, // Secret event token to identify event
|
"event_token": String, // Secret event token to identify event
|
||||||
"event_title": String, // used in export file name
|
"event_title": String, // Used in export file name
|
||||||
"vote_round": int, // nth vote round
|
"vote_round": Number, // nth vote round
|
||||||
"votes": [
|
"votes": [
|
||||||
{ "hash": VOTE_ID, "vote":
|
{
|
||||||
[
|
"hash": String,
|
||||||
String, // Description of vote (against, for, abstinence, name of nominee, etc)
|
"vote": [
|
||||||
[...] // repeat if multiple votes are possible
|
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
|
```javascript
|
||||||
{
|
{
|
||||||
"success": Bool, // Registration of event was successful
|
"success": Boolean, // Registration of event was successful
|
||||||
"file_hash": Str, // SHA256 hash of generated result file
|
"hash_txt": String, // SHA256 hash of generated TXT file
|
||||||
"signing_key": Str // ID of key used to sign result 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
|
# 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.
|
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`.
|
The script uses the following parameters:
|
||||||
`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.
|
`./generate_hashes.sh FILE_USERNAMES EVENT_ID VOTING_ROUNDS`.
|
||||||
`VOTING_ROUNDS` is the maximum number of expected voting rounds. To be sure, generate IDs for more rounds than expected.
|
|
||||||
|
- `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.
|
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.
|
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
|
; %t - Title
|
||||||
; %d - Date
|
; %d - Date
|
||||||
; %r - Vote Round
|
; %r - Vote Round
|
||||||
header = Ergebnis der Abstimmung %r am %t - %t
|
header = Ergebnis der Abstimmung %r am %d - %t
|
||||||
pgpkey = ID
|
pgpkey = ID
|
||||||
|
|
||||||
; if rawpath is set, the raw JSON will be saved into the directory
|
; if rawpath is set, the raw JSON will be saved into the directory
|
||||||
|
|
|
@ -157,8 +157,8 @@ class AbstimmIDd {
|
||||||
|
|
||||||
return [
|
return [
|
||||||
'success' => true,
|
'success' => true,
|
||||||
'sha256_txt' => $sha256_txt,
|
'hash_txt' => $sha256_txt,
|
||||||
'sha256_pdf' => $sha256_pdf,
|
'hash_pdf' => $sha256_pdf,
|
||||||
'signing_key' => $this->cfg['export']['pgpkey']];
|
'signing_key' => $this->cfg['export']['pgpkey']];
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue