tordam

A library for peer discovery inside the Tor network
git clone https://git.parazyd.org/tordam
Log | Files | Refs | README | LICENSE

commit ec8c054d5887498c14d66caa2f01e454e3ba61bb
parent 6de85d612c0f0f7bca2642690771dbaf81415fb1
Author: parazyd <parazyd@dyne.org>
Date:   Fri,  8 Dec 2017 03:33:58 +0100

Update documentation

Diffstat:
MREADME.md | 114++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------
1 file changed, 84 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md @@ -1,34 +1,72 @@ -Tor-DECODE announce mechanism (Tor-DAM) +Tor-DECODE Announce Mechanism (Tor-DAM) ======================================= -Short PoC of finding DECODE nodes in the Tor network. +Protocol and tooling for finding DECODE nodes in the Tor network. + + +Installation +------------ + +``` +go get -u github.com/parazyd/tor-dam +``` + +From the source, install python/dirauth.py to your `$PATH`. + +### Dependencies + +#### Go + +``` +golang.org/x/net/proxy +github.com/go-redis/redis +``` + +#### Python 3 +``` +https://stem.torproject.org/ +``` Abstract -------- * Every DECODE node can be an opt-in directory. - * This implies running the directory API daemon on the node. -* Every directory would have a RESTful/HTTP API allowing to list other - nodes and announce new ones. -* They keep propagating to all the nodes they know. + * This implies running the directory daemon on the node. +* Every directory has a HTTP API allowing to list other nodes and + announce new ones. +* They keep propagating to all valid nodes/directories they know. * Announcing implies the need of knowledge of at least one or two nodes. - It is possible to make this random enough once there are at least 6 - nodes. -* A node announces itself to the directory by sending a JSON-formatted - POST request to one or more active DECODE nodes. + * It is possible to make this random enough once there are at least 6 + nodes in the network. +* A node announces itself to directories by sending a JSON-formatted + HTTP POST request to one or more active DECODE nodes/directories. + * Once the POST request is received, the directory will validate the + request and return a secret encrypted with the requester's private + key. + * The requester will try to decrypt this secret, and return it plain + back to the directory, so the directory can confirm the requester is + in actual possession of the private key. +* Tor-DAM **does not validate** if a node is malicious or not. This is + a layer that has to be established on top. Tor-DAM is just the entry + point into the network. Protocol -------- -A node announcing itself has to do a JSON-formatted POST request to a -known and active DECODE directory with the format explained below. +A node announcing itself has to do a JSON-formatted HTTP POST request +to one or more active DECODE directories with the format explained +below. N.B. The strings shown in this document might not be valid, but +they represent a correct example. + * `type` reflects the type of the node (currently just a placeholder) -* `address` should hold the address of the Tor hidden service. +* `address` holds the address of the Tor hidden service * `message` is the message that has to be signed using the private key of this same hidden service. * `signature` is the base64 encoded signature of the above message. +* `secret` is a string that is used for exchanging messages between + the client and server. ``` @@ -36,7 +74,8 @@ known and active DECODE directory with the format explained below. "type": "node", "address": "qzhpi3jsbuvndnaw.onion", "message": "I am a DECODE node!", - "signature": "ACkwtGGedX1ibHnlwtHlgJYndEMu0HhJaK3DLnH1B+r8/xx7jNDerOU7zrZVuzvf5mH9aZyHAOSHleaD52CsbT3lZrsrVWh4sVsJCD9VbEKuuPV/hx+T8f385V5dv2nDvBtJP32eQhwAxKz8YQvBjQOX8Y/o13vq+bxnxLd1j7g=" + "signature": "ACkwtGGedX1ibHnlwtHlgJYndEMu0HhJaK3DLnH1B+r8/xx7jNDerOU7zrZVuzvf5mH9aZyHAOSHleaD52CsbT3lZrsrVWh4sVsJCD9VbEKuuPV/hx+T8f385V5dv2nDvBtJP32eQhwAxKz8YQvBjQOX8Y/o13vq+bxnxLd1j7g=", + "secret": "" } ``` @@ -46,8 +85,20 @@ network. It will retrieve the public key and try to validate the signature that was made. Validating this, we assume that the requester is in possession of the private key. -Once validated, the directory will append to the JSON struct, which will -result in the following: +Following up, the directory will generate a cryptographically secure +random string and encrypt it using the before acquired private key. It +will then be encoded using base64 and sent back to the client: + + +``` +{ + "secret": "NzN1amZoeTUvc3V1OTE5KDkzOTQ4NTc2Z3VyanNrbnZtbTU0NyY3eWR1ZWtqdmJza2sxOSg5NzNAOTg0Mgo=" +} +``` + +The client will try to decode and decrypt this secret, and send it back +to the directory to complete its part of the handshake. The POST request +will again contained the data that was sent the first time as well: ``` @@ -56,24 +107,27 @@ result in the following: "address": "qzhpi3jsbuvndnaw.onion", "message": "I am a DECODE node!", "signature": "ACkwtGGedX1ibHnlwtHlgJYndEMu0HhJaK3DLnH1B+r8/xx7jNDerOU7zrZVuzvf5mH9aZyHAOSHleaD52CsbT3lZrsrVWh4sVsJCD9VbEKuuPV/hx+T8f385V5dv2nDvBtJP32eQhwAxKz8YQvBjQOX8Y/o13vq+bxnxLd1j7g=", - "firstseen": 1511577084, - "lastseen": 1511577084, - "publickey": "-----BEGIN RSA PUBLIC KEY-----\nMIGJAoGBALrCIYHP38IEJXJAKhbVz/G6Q/OKTkKOfWXg1IlSRUtUKr+6pVMIRXni\ndeluaVRyCPkHA1g2o/MTHxVAgZspbUkTMYGrUYV0TOdcsbD29tPTXCmy5ZxyjsvO\nd7b3dxadT+9621q2H8/XYvHGWYZnnvyZgndjFsI/vBx9GYW8ial9AgMBAAE=\n-----END RSA PUBLIC KEY-----" + "secret": "NzN1amZoeTUvc3V1OTE5KDkzOTQ4NTc2Z3Vyaj8/Pz9tbTU0NyY3eWR1ZWtqdmJza2sxOSg5NzNAOTg0Mgo=" } ``` +The directory will verify the received plain secret against what it has +encrypted to validate. If the comparison yields no errors, we assume that +the requester is actually in possession of the private key. We will now +complete the handshake by welcoming the client into the network: -The directory will then save this locally on the machine, and propagate -it through the network of nodes/directories further on. +``` +{ + "secret": "Welcome to the DECODE network!" +} +``` -Questions and concerns ----------------------- +Further on, the directory will append useful metadata to the struct. +We will add the encoded public key, timestamps of when the client was +first seen and last seen, and a field to indicate if the node is valid. +The latter is not to be handled by Tor-DAM, but rather the upper layer, +which actually has consensus handling. -* Handling consensus? -* Validating nodes further on? -* How to keep track of node status? -* Could the DECODE website could host a list of ultimately-trusted - nodes/directories? -* A node should be verified once it announces itself. -* Do we POST back all the nodes we know back to the announcer? +Once a node is considered not malicious by a defined number of nodes, the +directories can then keep propagating addresses of other nodes to it.