itUpdate the protocol document and fix some wording. - tordam - A library for peer discovery inside the Tor network Err parazyd.org 70 hgit clone https://git.parazyd.org/tordam URL:https://git.parazyd.org/tordam parazyd.org 70 1Log /git/tordam/log.gph parazyd.org 70 1Files /git/tordam/files.gph parazyd.org 70 1Refs /git/tordam/refs.gph parazyd.org 70 1README /git/tordam/file/README.md.gph parazyd.org 70 1LICENSE /git/tordam/file/LICENSE.gph parazyd.org 70 i--- Err parazyd.org 70 1commit d73ce82c3fb0296feeb7b64dd188d027e30881de /git/tordam/commit/d73ce82c3fb0296feeb7b64dd188d027e30881de.gph parazyd.org 70 1parent 1999ba5caec580c2b873cc0b1afdf6c601564e1f /git/tordam/commit/1999ba5caec580c2b873cc0b1afdf6c601564e1f.gph parazyd.org 70 hAuthor: parazyd URL:mailto:parazyd@dyne.org parazyd.org 70 iDate: Mon, 22 Oct 2018 11:36:16 +0200 Err parazyd.org 70 i Err parazyd.org 70 iUpdate the protocol document and fix some wording. Err parazyd.org 70 i Err parazyd.org 70 iDiffstat: Err parazyd.org 70 i M protocol.md | 77 +++++++++++++++---------------- Err parazyd.org 70 i Err parazyd.org 70 i1 file changed, 37 insertions(+), 40 deletions(-) Err parazyd.org 70 i--- Err parazyd.org 70 1diff --git a/protocol.md b/protocol.md /git/tordam/file/protocol.md.gph parazyd.org 70 it@@ -4,44 +4,41 @@ Tor DAM Protocol Err parazyd.org 70 i Abstract Err parazyd.org 70 i -------- Err parazyd.org 70 i Err parazyd.org 70 i-* Every node can be an opt-in directory. Err parazyd.org 70 i- * This implies running the directory daemon on the node. Err parazyd.org 70 i-* Every directory has a HTTP API allowing to list other nodes and Err parazyd.org 70 i- announce new ones. Err parazyd.org 70 i-* They keep propagating to all valid nodes/directories they know. Err parazyd.org 70 i+* Every node has a HTTP API allowing to list other nodes and announce Err parazyd.org 70 i+ new ones. Err parazyd.org 70 i+* They keep propagating to all valid nodes they know. Err parazyd.org 70 i * Announcing implies the need of knowledge of at least one or two nodes. Err parazyd.org 70 i * It is possible to make this random enough once there are at least 6 Err parazyd.org 70 i nodes in the network. Err parazyd.org 70 i-* A node announces itself to directories by sending a JSON-formatted Err parazyd.org 70 i- HTTP POST request to one or more active nodes/directories. Err parazyd.org 70 i- * Once the POST request is received, the directory will validate the Err parazyd.org 70 i+* A node announces itself to others by sending a JSON-formatted HTTP Err parazyd.org 70 i+ POST request to one or more active node. Err parazyd.org 70 i+ * Once the POST request is received, the node will validate the Err parazyd.org 70 i request and return a secret encrypted with the requester's public Err parazyd.org 70 i- key. Err parazyd.org 70 i+ key. Err parazyd.org 70 i * The requester will try to decrypt this secret, and return it plain Err parazyd.org 70 i- back to the directory, along with a cryptographic signature, so the Err parazyd.org 70 i- directory can confirm the requester is in actual possession of the Err parazyd.org 70 i- private key. Err parazyd.org 70 i-* Tor DAM **does not validate** if a node is malicious or not. This is Err parazyd.org 70 i- a layer that has to be established on top. Tor-DAM is just the entry Err parazyd.org 70 i+ back to the node it's announcing to, along with a cryptographic Err parazyd.org 70 i+ signature, so the node can confirm the requester is in actual Err parazyd.org 70 i+ possession of the private key. Err parazyd.org 70 i+* Tor DAM **does not validate** if a node is malicious or not. This is a Err parazyd.org 70 i+ layer that has to be established on top. Tor DAM is just the entry Err parazyd.org 70 i point into the network. Err parazyd.org 70 i-* A node can become a directory once it is proven valid (not malicious). Err parazyd.org 70 i Err parazyd.org 70 i Err parazyd.org 70 i Protocol Err parazyd.org 70 i -------- Err parazyd.org 70 i Err parazyd.org 70 i-A node announcing itself has to do a JSON-formatted HTTP POST request Err parazyd.org 70 i-to one or more active directories with the format explained below. Err parazyd.org 70 i-N.B. The strings shown in this document might not be valid, but they Err parazyd.org 70 i-represent a correct example. Err parazyd.org 70 i+A node announcing itself has to do a JSON-formatted HTTP POST request to Err parazyd.org 70 i+one or more active nodes with the format explained below. N.B. The Err parazyd.org 70 i+strings shown in this document might not be valid, but they represent a Err parazyd.org 70 i+correct example. Err parazyd.org 70 i Err parazyd.org 70 i-* `type` reflects the type of the node (node/directory) Err parazyd.org 70 i+* `type` reflects the type of the node Err parazyd.org 70 i * `address` holds the address of the Tor hidden service Err parazyd.org 70 i * `message` is the message that has to be signed using the private key Err parazyd.org 70 i of this same hidden service. Err parazyd.org 70 i * `signature` is the base64 encoded signature of the above message. Err parazyd.org 70 i-* `secret` is a string that is used for exchanging messages between Err parazyd.org 70 i- the client and server. Err parazyd.org 70 i+* `secret` is a string that is used for exchanging messages between the Err parazyd.org 70 i+ client and server. Err parazyd.org 70 i Err parazyd.org 70 i Err parazyd.org 70 i ``` Err parazyd.org 70 it@@ -54,15 +51,15 @@ represent a correct example. Err parazyd.org 70 i } Err parazyd.org 70 i ``` Err parazyd.org 70 i Err parazyd.org 70 i-Sending this as a POST request to a directory will make the directory Err parazyd.org 70 i-ask for the public key of the given address from a HSDir in the Tor Err parazyd.org 70 i-network. It will retrieve the public key and try to validate the Err parazyd.org 70 i-signature that was made. Validating this, we assume that the requester Err parazyd.org 70 i-is in possession of the private key. Err parazyd.org 70 i+Sending this as a POST request to a node will make it ask for the public Err parazyd.org 70 i+key of the given address from a HSDir in the Tor network. It will Err parazyd.org 70 i+retrieve the public key and try to validate the signature that was made. Err parazyd.org 70 i+Validating this, we assume that the requester is in possession of the Err parazyd.org 70 i+private key. Err parazyd.org 70 i Err parazyd.org 70 i-Following up, the directory will generate a cryptographically secure Err parazyd.org 70 i-random string and encrypt it using the before acquired public key. It Err parazyd.org 70 i-will then be encoded using base64 and sent back to the client: Err parazyd.org 70 i+Following up, the node shall generate a cryptographically secure random Err parazyd.org 70 i+string and encrypt it using the before acquired public key. It will then Err parazyd.org 70 i+be encoded using base64 and sent back to the client: Err parazyd.org 70 i Err parazyd.org 70 i Err parazyd.org 70 i ``` Err parazyd.org 70 it@@ -72,9 +69,9 @@ will then be encoded using base64 and sent back to the client: Err parazyd.org 70 i ``` Err parazyd.org 70 i Err parazyd.org 70 i The client will try to decode and decrypt this secret, and send it back Err parazyd.org 70 i-to the directory to complete its part of the handshake. The POST request Err parazyd.org 70 i-this time will contain the following data: Err parazyd.org 70 i-* `type` reflects the type of the node (node/directory) Err parazyd.org 70 i+to the node to complete its part of the handshake. The POST request this Err parazyd.org 70 i+time will contain the following data: Err parazyd.org 70 i+* `type` reflects the type of the node Err parazyd.org 70 i * `address` holds the address of the Tor hidden service Err parazyd.org 70 i * `message` is the decrypted and base64 encoded secret that the server Err parazyd.org 70 i had just sent us. Err parazyd.org 70 it@@ -92,7 +89,7 @@ this time will contain the following data: Err parazyd.org 70 i } Err parazyd.org 70 i ``` Err parazyd.org 70 i Err parazyd.org 70 i-The directory will verify the received plain secret against what it has Err parazyd.org 70 i+The node will verify the received plain secret against what it has Err parazyd.org 70 i encrypted to validate. If the comparison yields no errors, we assume Err parazyd.org 70 i that the requester is actually in possession of the private key. If the Err parazyd.org 70 i node is not valid in our database, we will complete the handshake by Err parazyd.org 70 it@@ -105,13 +102,13 @@ welcoming the client into the network: Err parazyd.org 70 i } Err parazyd.org 70 i ``` Err parazyd.org 70 i Err parazyd.org 70 i-Further on, the directory will append useful metadata to the struct. Err parazyd.org 70 i-We will add the encoded public key, timestamps of when the client was Err parazyd.org 70 i-first seen and last seen, and a field to indicate if the node is valid. Err parazyd.org 70 i-The latter is not to be handled by Tor-DAM, but rather the upper layer, Err parazyd.org 70 i-which actually has consensus handling. Err parazyd.org 70 i+Further on, the node will append useful metadata to the struct. We will Err parazyd.org 70 i+add the encoded public key, timestamps of when the client was first seen Err parazyd.org 70 i+and last seen, and a field to indicate if the node is valid. The latter Err parazyd.org 70 i+is not to be handled by Tor DAM, but rather the upper layer, which Err parazyd.org 70 i+actually has consensus handling. Err parazyd.org 70 i Err parazyd.org 70 i-If the node is valid in the directory's database, the directory will Err parazyd.org 70 i+If the node is valid in another node's database, the remote node will Err parazyd.org 70 i then propagate back all the valid nodes it knows (including itself) back Err parazyd.org 70 i to the client in a gzipped and base64 encoded JSON struct. The client Err parazyd.org 70 i will then handle this and update its own database accordingly. Err parazyd.org 70 .