D4.11/tordam-01-overview.md

Tor DAM

Tor Distributed Announce Mechanism (DAM) is a protocol and tooling for mapping machines in the Tor network running this software.

The Tor DAM network is imagined to be pseudo-distributed inside the Tor network itself. Nodes running Tor DAM can use an existing entrypoint and start announcing themselves to the entry point(s), or they can be their own and let others announce to themselves. Tor DAM will store all of these announcements in a storage backend and utilize it to expand the knowledge of the nodes using this software. Over time the network will keep expanding and the user will be able to see all other nodes in the network either by querying the storage backend, or visualizing it with some kind of software.

Abstract

• Every node has a HTTP API allowing to list other nodes and announce new ones.
• They keep propagating to all valid nodes 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 in the network.
• A node announces itself to others by sending a JSON-formatted HTTP POST request to one or more active node.
  • Once the POST request is received, the node will validate the request and return a secret encrypted with the requester's public key.
  • The requester will try to decrypt this secret, and return the secret in plain text back to the node it's announcing to, along with a cryptographic signature, so the node 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 HTTP POST request to one or more active nodes 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
• 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.

{
  "type": "node",
  "address": "22mobp7vrb7a4gt2.onion",
  "message": "I am a DAM node!",
  "signature": "BuB/Dv8E44CLzUX88K2Ab0lUNS9A0GSkHPtrFNNWZMihPMWN0ORhwMZBRnMJ8woPO3wSONBvEvaCXA2hvsVrUJTa+hnevQNyQXCRhdTVVuVXEpjyFzkMamxb6InrGqbsGGkEUqGMSr9aaQ85N02MMrM6T6JuyqSSssFg2xuO+P4=",
  "secret": ""
}

Sending this as a POST request to a node will make it ask for the public key of the given address from a "hidden service directory" (HSDir) in the Tor 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.

Following up, the node shall generate a cryptographically secure random string and encrypt it using the before acquired public key. It will then be encoded using base64 and sent back to the client:

{
  "secret": "eP07xSZWlDdK4+AL0WUkIA3OnVTc3sEgu4MUqGr43TUXaJLfAILvWxKihPxytumBmdJ4LC45LsrdDuhmUSmZZMJxxiLmB4Gf3zoWa1DmStdc147VsGpexY05jaJUZlbmG0kkTFdPmdcKNbis5xfRn8Duo1e5bOPj41lIopwiil0="
}

The client will try to decode and decrypt this secret, and send it back to the node to complete its part of the handshake. The POST request this time will contain the following data:

• type reflects the type of the node
• address holds the address of the Tor hidden service
• message is the decrypted and base64 encoded secret that the server had just sent us.
• signature is the base64 encoded signature of the above secret.
• secret is a copy of message here.

{
  "type": "node",
  "address": "22mobp7vrb7a4gt2.onion",
  "message": "ZShhYHYsRGNLOTZ6YUwwP3ZXPnxhQiR9UFVWfmk5TG56TEtLb04vMms+OTIrLlQ7aS4rflR3V041RG5Je0tnYw==",
  "signature": "L1N+VEi3T3aZaYksAy1+0UMoYn7B3Gapfk0dJzOUxUtUYVhj84TgfYeDnADNYrt5UK9hN/lCTIhsM6zPO7mSjQI43l3dKvMIikqQDwNey/XaokyPI4/oKrMoGQnu8E8UmHmI1pFvwdO5EQQaKbi90qWNj93KB/NlTwqD9Ir4blY=",
  "secret": "ZShhYHYsRGNLOTZ6YUwwP3ZXPnxhQiR9UFVWfmk5TG56TEtLb04vMms+OTIrLlQ7aS4rflR3V041RG5Je0tnYw=="
}

The node 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. If the node is not valid in our database, we will complete the handshake by welcoming the client into the network:

{
  "secret": "Welcome to the DAM network!"
}

Further on, the node 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.

If the node is valid in another node's database, the remote node will then propagate back all the valid nodes it knows (including itself) back to the client in a gzipped and base64 encoded JSON struct. The client will then handle this and update its own database accordingly.