Code used as part of Private Reputation Supporting Ongoing Network Avatars. A privacy-preserving reputation system designed for usage in smaller, community-based settings.

Huehuecóyotl 474e226dbb regenerated plots with TrueType fonts 1 year ago
BGN2 @ 9581a5b195 f00967d23f update to README to clarify funding 2 years ago
civetweb @ 58070cd614 d31afa1ca1 figuring out appropriate underlying library for networking 3 years ago
prsona 474e226dbb regenerated plots with TrueType fonts 1 year ago
.gitignore 53162873b7 plots are now being generated 2 years ago
.gitmodules ebe21eba45 updating gitmodules 2 years ago
README.md 5a5c98e974 updated dependencies 2 years ago

README.md

PRSONA

This repository contains the implementation of PRSONA: Private Reputation Supporting Ongoing Network Avatars. PRSONA is a privacy-preserving reputation system designed for use in tight-knit communities. The three top-level directories refer to different libraries used in PRSONA; the ./prsona directory is the novel code for PRSONA itself, and is the best starting place.

BGN2

This directory is its own git-tracked project, a fork of an earlier implementation of BGN by Herbert et al., which is used by PRSONA to implement prime-order BGN. More detail about this library can be found by going to its repository (https://git-crysp.uwaterloo.ca/tmgurtler/BGN2), and more information about prime-order BGN in general can be found in Freeman's original discussion of such: https://link.springer.com/content/pdf/10.1007%2F978-3-642-13190-5_3.pdf

Civetweb

This directory is also its own git-tracked project. No forks or changes were made by the authors on this project in the construction of PRSONA. This library serves to enable networking within PRSONA, so that servers and clients can be used across multiple networked machines. More information on this project can be found by going to its repository (https://github.com/civetweb/civetweb)

PRSONA

This directory contains the code for PRSONA (as well as code to orchestrate the experiments to benchmark PRSONA), configuration settings used when benchmarking the code in our test environment, and code that generates the plots used in the paper and thesis forms of PRSONA. In the repository, there are 5 subdirectories:

  • ./prsona/cfg: Configuration files used when running PRSONA in our test environment
  • ./prsona/inc: C++ Header files for the classes used in PRSONA
  • ./prsona/plt: Plots of the data generated by PRSONA
  • ./prsona/scripts: Two scripts that help manage debugging of PRSONA in the test environment, and one script that generates the plots given PRSONA outputs
  • ./prsona/src: Implementation of the classes used in PRSONA, as well as code for the executables that use these classes, and code that is used to orchestrate PRSONA in the test environment

Upon building PRSONA, an additional 3 subdirectories are generated as follows:

  • ./prsona/obj: Object files generated when compiling PRSONA
  • ./prsona/bin: Final executables for PRSONA
  • ./prsona/tmp: A directory used for temporary files by PRSONA when running (this should be empty when PRSONA is not actively running)

Upon running PRSONA, a final additional subdirectory is generated as follows:

  • ./prsona/out: Recorded data outputs for PRSONA, organized into further subdirectories, identified below.

Cloning PRSONA

PRSONA makes use of BGN2 and Civetweb as submodules, so cloning PRSONA takes a few additional steps beyond what is normally required to clone a git repo. First, clone PRSONA into a new directory as normal:

git clone https://git-crysp.uwaterloo.ca/tmgurtler/PRSONA.git prsona

cd into the new directory this operation creates. Initialize the submodules, then update them:

git submodule init && git submodule update

Once this has been done, the code has been properly cloned into your local directory.

Building PRSONA

PRSONA and the libraries it uses all use make and g++ to build themselves, and those must be installed before compilation is possible. libgmp-dev and libssl-dev or their equivalents should also be installed. These are all the dependencies PRSONA requires to compile, but it additionally requires some further dependencies to generate the plots used in the paper and thesis versions of PRSONA. See "Generating PRSONA Plots" for more details.

To build PRSONA, navigate to the prsona subdirectory within the repo (if following the instructions above to clone the repository, this will be /rest/of/path/prsona/prsona). Run make. Assuming the code has been properly cloned, and all dependencies are installed and up-to-date, this will compile all code used in PRSONA (including libraries).

Running PRSONA

Following the steps above generates 5 executables in the ./prsona/bin subdirectory as follows:

  • ./prsona/bin/client: Operates one client node for PRSONA.
  • ./prsona/bin/localTest: Executes a fully local version of the benchmarks used in PRSONA. As this skips all networking code, this is not used in any plot in the paper or thesis versions of PRSONA, but can be useful to confirm compilation executed correctly.
  • ./prsona/bin/orchestrator: Takes information from configuration files to spin up client and server nodes, and issue instructions to them to perform an experiment used to benchmark the components of PRSONA in our test environment.
  • ./prsona/bin/queue: Takes information from configuration files to run consecutive benchmarking experiments without any need for operator involvement.
  • ./prsona/bin/server: Operates one server node for PRSONA.

Running PRSONA local tests

To confirm that compilation performed correctly, you may wish to run the local versions of the PRSONA benchmarks. To do so, once the executable has been built, navigate to ./prsona/. You will be using bin/localTest, which takes parameters like so:

bin/localTest <numberServers> <numberClients> <numberEpochs> <numberVotesPerEpoch> <lambda> <maliciousServers> <maliciousClients> <seed>

  • <numberServers>: The number of server nodes to be used in the experiment. Defaults to 2.
  • <numberClients>: The number of client nodes to be used in the experiment. Defaults to 5.
  • <numberEpochs>: The number of epochs to be executed in the experiment. Defaults to 3.
  • <numberVotesPerEpoch>: The number of votes each user should randomly change during each epoch. Defaults to 3.
  • <lambda>: The value of the batch parameter, lambda, to be used in the experiment. Setting this value to 0 indicates that no proof batching should be conducted. Defaults to 0.
  • <maliciousServer>: T if the servers should be treated under covert security, and F if servers should be treated under honest-but-curious security. Defaults to T.
  • <maliciousClient>: T if the clients should be treated under malicious security, and F if clients should be treated under honest-but-curious security. Defaults to T.
  • <seed>: A random seed used in the experiment so that results and errors are repeatable. Defaults to "seed".

This executable runs a fully local version of the benchmarks, and is mostly useful to confirm that compilation was done correctly.

Running PRSONA networked tests

The plots used in the paper and thesis versions of PRSONA involved output from the networked version of the code. There are two executables that are most important for this action: bin/client and bin/server. The server node can be operated like so:

bin/server <id> <output> <lambda> <maliciousServer>

  • <id>: a name for this instance, which comes with a config file identifying its IP address and port
  • <output>: a string that will name the file in which outputs for this run of the program will be written (that is, timings and traffic data)
  • <lambda>: a positive integer that determines the absolute soundness parameter for batched proofs
  • <maliciousServer>: a bool (given as T/t or F/f) which is true when servers are in covert security and false when they are in HBC security

The client node can be operated like so:

bin/client <id> <output> <lambda> <maliciousServer>

  • <id>: a name for this instance, which comes with a config file identifying its IP address and port
  • <output>: a string that will name the file in which outputs for this run of the program will be written (that is, timings and traffic data)
  • <lambda>: a positive integer that determines the absolute soundness parameter for batched proofs
  • <maliciousServer>: a bool (given as T/t or F/f) which is true when servers are in covert security and false when they are in HBC security

IDs for both must match configurations specified in ./prsona/cfg/<output>/, which mostly detail the IP addresses that clients and servers can be found at (as well as the number of clients and servers). The dealer server for any configuration should be initialized first, then the rest of the servers, before any clients may be initialized.

Once servers and clients have been initialized, they are ready to be issued instructions. Instructions are given via HTTP GET requests. Given a server IP address/port combination (<serverIP>:<serverPort>), the following instructions can be issued by making the following GET requests:

  • <serverIP>:<serverPort>/epoch: This instruction can only be issued to the dealer server. Upon receiving this instruction, the dealer initiates an epoch changeover, and orchestrates the other servers' participation in the correct order.
  • <serverIP>:<serverPort>/exit: This instruction signals the server to gracefully shut down.

Given a client IP address/port combination (<clientIP>:<clientPort>), the following instructions can be issued by making the following GET requests:

  • <clientIP>:<clientPort>/vote: This instruction signals the client to randomly update its votes with the servers.
  • <clientIP>:<clientPort>/rep?<otherClientIP>:<otherClientPort>: This instruction signals the client to initiate a reputation proof with another client, specified by <otherClientIP>:<otherClientPort>.
  • <clientIP>:<clientPort>/exit: This instruction signals the client to gracefully shut down.

Operating servers and clients directly can be helpful for debugging purposes, but may be undesirable to actually replicate experiments. To replicate a single experiment, bin/orchestrator may be used instead. The orchestrator is operated like so:

bin/orchestrator <output> <lambda> <maliciousServer>

  • <output>: a string that will name the files in which outputs for this run of the experiment will be written (that is, timings and traffic data)
  • <lambda>: a positive integer that determines the absolute soundness parameter for batched proofs
  • <maliciousServer>: a bool (given as T/t or F/f) which is true when servers are in covert security and false when they are in HBC security

Some local alteration to ./prsona/src/networkOrchestrator.cpp and ./prsona/src/orchestratorMain.cpp may be necessary to run the orchestrator on your own machine, as those files rely on details of our test environment that may not be reflected in your own. The orchestrator starts up the servers and clients, issues a set of commands to them, then gracefully shuts them down. The orchestrator relies on configuration settings specified in ./prsona/cfg/<output>/ for both the individual client and server setups (IP addresses), as well as for the set of commands to be issued.

To replicate several experiments in succession, bin/queue may be used. The experiment queue takes no explicit parameters (that is, it is run simply as bin/queue). It relies on ./prsona/cfg/queue.cfg/ being complete; each line in this file specifies the parameters to be supplied to the orchestrator for one experiment.

PRSONA Output Subdirectories

The further subdirectories of the output directory have the following format: ./prsona/out/<experimentLabel>/<experimentEntity>. <experimentLabel> identifies which experiment that subdirectory contains data for (which is itself broken into components like so: <experimentType>-<numberServers>-<numberClients>-<lambda>; <experimentType> refers to which component is being benchmarked (and if applicable, with which workload), <numberServers> and <numberClients> refers to parameters set on the number of servers and clients being used in the experiment, and <lambda> refers to the used value of lambda, the proof batching parameter, in that experiment). <experimentEntity> identifies which node data came from specifically (nodes that start with c are clients, nodes that start with s are non-dealer servers, and the node identified by d is the dealer server, which initiates epochs).

Generating PRSONA Plots

In order to generate the plots used in the paper and thesis versions of PRSONA, additional dependencies are required. python3 must be installed, and matplotlib, numpy, and scipy must be installed within Python 3.

Once these dependencies have been installed, and PRSONA has been run to populate ./prsona/out with outputs, first observe ./prsona/plt/plots.json. This file contains the configuration information used to generate the plots specifically used in the paper and thesis version of PRSONA. This file may be altered if alternative plots are desired. Note that the plot generation script will expect valid output to be present for all desired plots specified in ./prsona/plt/plots.json. Any output for plots not specified in the configuration file can be safely omitted. It may be necessary to remove plots from the configuration settings if you do not have output to use for their generation.

With a proper configuration file set, navigate to ./prsona/scripts. Execute python3 make_graphs.py. The script will generate all plots specified in ./prsona/plt/plots.json, outputting them in ./prsona/plt/.