Guard

Guard is a secure routing protocol for skip-graphs. It makes use of digital signature schemes and supervisor nodes called guards to assert the correctness of lookup operations. This particular implementation makes use of GuardCrypto for the digital signature scheme and a heavily modified version of the open-source SkipGraph implementation provided here.

Layers

This implementation makes use of a layered architecture. From bottom to top, the layers of an authenticated node are as following:

1. Communication layer: Handles node-to-node communication.
2. Authentication layer: Implements the phases of Guard. Inserts & verifies the authentication meta-data related to authenticated search queries.
3. Skip node layer: Implements a skip-graph DHT node. Supports search and join operations.
4. User interface: Coordinates the authenticated/unauthenticated search, join operations. Per-node experiments are also handled by this layer.

Guard makes use of a trusted third party (TTP) during the registration, construction and guard assignment phases. TTP also acts as the experiment controller. It is implemented as a separate application, and its layers are as following:

1. Communication layer: Handles TTP-to-node and node-to-TTP communication.
2. TTP layer: Contains the trusted third party protocols (e.g. registration) specific to Guard.
3. TTP user interface: Used to coordinate the experiment from a central point.

Each layer is implemented by extending the Layer abstract class. The specific layer implementations reside in their own packages.

System parameters

The system parameters are defined under the ttp package, in SystemParameters.java file. System parameters are initialized at the TTP, and at the registration phase, they are sent to the nodes. Here are the explanations of the parameters:

1. SYSTEM_CAPACITY: The number of nodes that the skip-graph contains. This implementation does not handle churn. In other words, SYSTEM_CAPACITY many nodes needs to register with the TTP before the lookups can be performed, and once joined, the nodes cannot depart from the system.
2. IDENTITY_LENGTH: Identity length for the digital signature scheme. This value should be larger than 256, as the messages are signed by two identities: name ID of a node, and the SHA-256 output of the numerical ID of a node.
3. MESSAGE_LENGTH: Message length for the digital signature scheme. This value denotes the length (in bytes) of the routing transcripts.
4. NONCE_LENGTH: Each lookup operation is assigned with a nonce -- a random bit string. This denotes the length of the bit string.
5. VERIFY_AT_INITIATOR: Once this is set to true, the set of routing proofs received at the end of an authenticated search all are verified at the initiator of the search.
6. VERIFY_AT_ROUTER: Once this is set to true, each node in the search path verifies the routing proof generated by the previous node in the search path.

Experiment parameters

We define an experiment in terms of rounds. An experiment is complete when each node successfully performs a pre-defined amount of rounds. A round is defined as following

1. The node chooses a random numerical ID.
2. The node performs an unauthenticated search over the skip-graph for the chosen numerical ID.
3. The node performs an authenticated search over the skip-graph for the chosen numerical ID.

The parameters related to the experiment are also defined in the SystemParameters.java file:

1. ROUND_COUNT: Denotes how many rounds a single node needs to complete.
2. WAIT_TIME: In order to avoid congestion, the nodes wait before proceeding to the next round. The waiting time (in seconds) is chosen uniformly from [1, WAIT_TIME].

Running

This implementation of Guard requires Java 11 to run. Please install the appropriate JRE before running.

To run Guard, go to the out/artifacts/Guard_jar directory where the Guard.jar can be found. This executable can run in two different modes: (1) TTP mode, and (2) node mode. Each system needs to have one TTP and SYSTEM_CAPACITY many nodes. To run as TTP, do the following:

$ java -jar Guard.jar ttp <port>

where <port> corresponds to the port number that the TTP should listen to.

To run as a node, do the following:

$ java -jar Guard.jar node <port> <TTP address>

where <port> corresponds to the port number that the node should listen to, and <TTP address> corresponds to the address of the TTP. Making use of this address, the node registers itself with the TTP (at the registration phase) and acquires its guards (at the guard assignment phase.)

Node operations

Once you run the application in node mode, the node will automatically register with the TTP and insert itself into the skip graph. The introducer is acquired from the TTP during registration. After these are complete, you will have the following options:

1. Info: Reports the information about the node (e.g. numerical ID) that was acquired from the TTP.
2. Initialize: Runs the construction phase (constructs the table proof) and guard assignment phase (acquires the guards) for this node.
3. Search: Initiates a search from this node.
4. Start experiments: Starts running the experiments only from this node. In other words, this node will perform ROUND_COUNT many rounds.

TTP operations

1. Show registered nodes: Shows the list of registered nodes.
2. Broadcast initialize requests: Initializes every registered node (i.e. runs the construction and guard assignment phases) and makes the skip-graph ready for authenticated searches.
3. Start experiments: Runs the experiments. Each node will perform ROUND_COUNT many rounds to complete the experiment.
4. Collect logs: Downloads the log files stored at every registered node in the system and merges them into a single .csv file.
5. Terminate the skip-graph: Terminates the TTP and remotely terminates every registered node in the skip-graph.

After all the nodes are registered with the TTP, the whole experiment can be controlled through TTP. In order to take measurements, the operations need to be performed with respect to their numerical order (i.e. first 2, then 3, and finally 4.)

Logs

During the operations of Guard, we log every event that has happened at a node. The logs are saved as a csv file with the address of the node as the name of the file. A single log has the following fields:

1. msg_id: The unique ID of the transmitted message or the unique ID of the local event.
2. event: Can be sent, received (for message transmission events) or process for local events.
3. address: The address of the node that the log was emitted from.
4. phase: The phase in which the event has occurred. Can be registration, construction, guard_assignment or search. For events that do not particularly belong to a phase, this is set to unknown.
5. type: This denotes the type of the event, i.e. an explanation on what the event actually is about. For example, for a sent event, this field contains the name of the request/response that was sent.
6. msg_size: The size of the transmitted message (in bytes). Only applicable for the sent or received events.
7. time: The local time of the machine (in milliseconds) when the log was emitted.

Taking measurements

The logs emitted by every node are located at the out/logs directory in .csv format. If the nodes are executed in different machines, the files need to be collected from every machine to a central location. For the sake of simplicity, we have provided this functionality through TTP. Choosing the 4th option on the TTP interface will download the logs from every node registered in the system and merge them into a single file (sorted by the time field.) Then, the downloaded logs and the merged version can be located at the received_logs directory.

Since the log files are in .csv format, performing queries on them is relatively easy. We have provided an example Python script (i.e. experiment.py) located at experiment_scripts folder. This script will perform the following measurements:

1. Avg. authenticated delay: Average time it takes (in ms) for an authenticated search to be resolved.
2. Avg. unauthenticated delay: Average time it takes (in ms) for an unauthenticated search to be resolved.
3. Factor of increase: Gives us a metric of how performant authenticated search is compared to the unauthenticated search. Calculated by x/y where x is the avg. authenticated delay and y is the avg. unauthenticated delay.
4. Avg. route delay: Average time it takes for the authentication layer to route a search request to the next hop.