protocol.md (3946B)
1 Tor DAM Protocol 2 ================ 3 4 Abstract 5 -------- 6 7 * Every node has a HTTP API allowing to list other nodes and announce 8 new ones. 9 * They keep propagating to all valid nodes they know. 10 * Announcing implies the need of knowledge of at least one node. 11 * It is possible to make this random enough once there are at least 6 12 nodes in the network. 13 * A node announces itself to others by sending a JSON-formatted HTTP 14 POST request to one or more active node. 15 * Once the POST request is received, the node will validate the 16 request and return a random string (nonce) back to the requester for 17 them to sign with their cryptographic key. 18 * The requester will try to sign this nonce and return it back to the 19 node it's announcing to, so the node can confirm the requester is in 20 actual posession of the private key. 21 * Tor DAM **does not validate** if a node is malicious or not. This is a 22 layer that has to be established with external software. 23 24 25 Protocol 26 -------- 27 28 A node announcing itself has to do a JSON-formatted HTTP POST request to 29 one or more active nodes with the format explained below. **N.B.** The 30 strings shown in this document might not be valid, but they represent a 31 correct example. 32 33 * `address` holds the address of the Tor hidden service. 34 * `pubkey` is the base64 encoded ed25519 public key of the Tor hidden 35 service. 36 * `message` is the message that has to be signed using the private key 37 of this same hidden service. 38 * `signature` is the base64 encoded signature of the above message. 39 * `secret` is a string that is used for exchanging messages between the 40 client and server. 41 42 43 ``` 44 { 45 "address": "gphjf5g3d5ywehwrd7cv3czymtdc6ha67bqplxwbspx7tioxt7gxqiid.onion", 46 "pubkey": "M86S9NsfcWIe0R/FXYs4ZMYvHB74YPXewZPv+aHXn80=", 47 "message" "I am a DAM node!", 48 "signature": "CWqptO9ZRIvYMIHd3XHXaVny+W23P8FGkfbn5lvUqeJbDcY3G8+B4G8iCCIQiZkxkMofe6RbstHn3L1x88c3AA==", 49 "secret": "" 50 } 51 ``` 52 53 Sending this as a POST request to a node will make it verify the 54 signature, and following that, the node will generate a 55 cryptographically secure random string, encode it using base64 and 56 return it back to the client for them to sign: 57 58 59 ``` 60 { 61 "secret": "NmtDOEsrLGI8eCk1TyxOfXcwRV5lI0Y5fnhbXlAhV1dGfTl8K2JAYEQrU2lAJ2UuJ2kjQF15Q30+SWVXTkFnXw==" 62 } 63 ``` 64 65 The client will try to decode and sign this secret. Then it will be 66 reencoded using base64 and sent back for verification to complete its 67 part of the handshake. The POST request this time will contain the 68 following data: 69 70 71 ``` 72 { 73 "address": "gphjf5g3d5ywehwrd7cv3czymtdc6ha67bqplxwbspx7tioxt7gxqiid.onion", 74 "pubkey": "M86S9NsfcWIe0R/FXYs4ZMYvHB74YPXewZPv+aHXn80=", 75 "message": "NFU5PXU4LT4xVy5NW303IWo1SD0odSohOHEvPThoemM3LHdcW3NVcm1TU3RAPGM8Pi1UUXpKIipWWnlTUk5kIg==", 76 "signature": "1cocZey3KpuRDfRrKcI3tc4hhJpwfXU3BC3o3VE8wkkCpCFJ5Xl3wl58GLSVS4BdbDAFrf+KFpjtDLhOuSMYAw==", 77 "secret": "NFU5PXU4LT4xVy5NW303IWo1SD0odSohOHEvPThoemM3LHdcW3NVcm1TU3RAPGM8Pi1UUXpKIipWWnlTUk5kIg==" 78 } 79 ``` 80 81 82 The node will verify the received secret against the public key it has 83 archived already. If the verification yields no errors, we assume that 84 the requester is actually in possession of the private key. If the node 85 is not valid in our database, we will complete the handshake by 86 welcoming the client into the network: 87 88 ``` 89 { 90 "secret": "Welcome to the DAM network!" 91 } 92 ``` 93 94 95 Further on, the node will append useful metadata to the struct. We will 96 add the encoded public key, timestamps of when the client was first seen 97 and last seen, and a field to indicate if the node is valid. The latter 98 is not to be handled by Tor DAM, but rather an upper layer, which 99 actually has consensus handling. 100 101 If a requesting/announcing node is valid in another node's database, the 102 remote node will then propagate back all the valid nodes it knows back 103 to the client in a gzipped and base64 encoded JSON struct. The client 104 will then process this and update its own database accordingly.