diff --git a/README.md b/README.md index 0cbbf3a..192e97b 100644 --- a/README.md +++ b/README.md @@ -30,11 +30,9 @@ VSP will add the ticket to a pool of always-online voting wallets. stats. An admin page enables searching for tickets and downloading database backups. -- **Two-way accountability** - All vspd requests must be signed with a private - key corresponding to the relevant ticket, and all vspd responses are signed - by with a private key known only by the server. This enables both the client - and the server to prove to outside observers if their counterparty is - misbehaving. For more detail, and examples, read +- **Two-way accountability** - All vspd requests and responses are signed by + their sender, which enables both the client and the server to hold each other + accountable in the case of misbehaviour. For more detail, and examples, read [two-way-accountability.md](./docs/two-way-accountability.md). - **Dynamic fees** - Clients must request a new fee address and amount for every diff --git a/docs/deployment.md b/docs/deployment.md index eacb74d..a52f98d 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -11,6 +11,11 @@ familiarity with Decred software and a level of sysadmin experience. Compiled binaries are not provided for vspd - VSP operators are expected to build vspd from source. +When deploying vspd to production, always build all binaries from release +branches. +Neither vspd nor its dependencies (dcrd/dcrwallet) should be built from master +when handling mainnet tickets. + ### Fee wallet A wallet should be created to collect VSP fees. Ideally this would be a cold diff --git a/docs/two-way-accountability.md b/docs/two-way-accountability.md index 8dd3c5c..53e5dff 100644 --- a/docs/two-way-accountability.md +++ b/docs/two-way-accountability.md @@ -1,19 +1,43 @@ # Two-way Accountability -- When vspd is started for the first time, it generates a ed25519 keypair and - stores it in the database. This key is used to sign all API responses, and the - signature is included in the response header `VSP-Server-Signature`. +In order to support two-way accountability, all vspd requests must be signed +with a private key corresponding to the relevant ticket, and all vspd responses +are signed by with a private key known only by the server. -- Every client request which references a ticket should include a HTTP header - `VSP-Client-Signature`. The value of this header must be a signature of the - request body, signed with the commitment address of the referenced ticket. +## Client -## Examples +### Client Request Signatures -### Server does not vote ticket +Every client request which references a ticket should include a HTTP header +`VSP-Client-Signature`. The value of this header must be a signature of the +request body, signed with the commitment address of the referenced ticket. -TODO +### Client Accountability Example -### Client denies changing their voting preferences +A misbehaving user may attempt to discredit a VSP operator by falsely claiming +that the VSP did not vote a ticket according to the voting preferences selected +by the user. -TODO +In this case, the VSP operator can reveal the request signed by the user which +set the voting preferences, and demonstrate that this matches the voting +preferences which were recorded on the blockchain. It would then be incumbent on +the user to provide a signed request/response pair with a later timestamp to +demonstrate that the operator is being dishonest. + +## Server + +### Server Response Signatures + +When vspd is started for the first time, it generates a ed25519 keypair and +stores it in the database. This key is used to sign all API responses, and the +signature is included in the response header `VSP-Server-Signature`. + +### Server Accountability Example + +A misbehaving server may fail to vote several tickets for which a user has paid +valid fees. + +In this case, the user can reveal responses signed by the server which +demonstrate that the server has acknowledged receipt of the fees, and all +information necessary to have voted the ticket. It would then be incumbent on +the server to explain why these tickets were not voted.