commit ec8c054d5887498c14d66caa2f01e454e3ba61bb
parent 6de85d612c0f0f7bca2642690771dbaf81415fb1
Author: parazyd <parazyd@dyne.org>
Date: Fri, 8 Dec 2017 03:33:58 +0100
Update documentation
Diffstat:
| M | README.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.
