Skip to content
This repository has been archived by the owner on Jan 9, 2024. It is now read-only.

Commit

Permalink
Merge pull request #52 from lbarman/new-readme
Browse files Browse the repository at this point in the history 
Rework the ReadMe's
  • Loading branch information
@lbarman
lbarman authored Dec 29, 2016
2 parents 801f973 + 4dc2f3e commit 2785de2
Show file tree
Hide file tree
Showing 4 changed files with 319 additions and 96 deletions.
114 changes: 18 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,125 +5,47 @@

This repository implements PriFi, an anonymous communication protocol with provable traffic-analysis resistance and small latency suitable for wireless networks. PriFi provides a network access mechanism for protecting members of an organization who access the Internet while on-site (via privacy-preserving WiFi networking) and while off-site (via privacy-preserving virtual private networking or VPN). The small latency cost is achieved by leveraging the client-relay-server topology common in WiFi networks. The main entities of PriFi are: relay, trustee server (or Trustees), and clients. These collaborate to implement a Dining Cryptographer's network ([DC-nets](https://en.wikipedia.org/wiki/Dining_cryptographers_problem)) that can anonymize the client upstream traffic. The relay is a WiFi router that can process normal TCP/IP traffic in addition to running our protocol.

For an extended introduction, please check our [website](https://lbarman.ch/prifi/).

For more details about PriFi, please check our [WPES 2016 paper](http://www.cs.yale.edu/homes/jf/PriFi-WPES2016.pdf).


**Warning: This software is experimental and still under development. Do not use it yet for security-critical purposes. Use at your own risk!**

## Getting and running PriFi

## Understanding the architecture

### Structure

The current code is organized in two main parts :

1) `PriFi-Lib`, which is network-agnostic; it takes an interface "MessageSender" that give it functions like SendToRelay(), SendToTrustee, ... and ReceivedMessage()

This is the core of the protocol PriFi.

2) `PriFi-SDA-Wrapper` (what is in folder `sda`), that does the mapping between the tree entities of SDA and our roles (Relay, Trustee, Client), and provides the MessageSender interface discussed above.

The SDA is a framework for Secure Distributed Algorithm, developped by DeDiS, EPFL. It help bootstrapping secure protocols. The "wrapper" is simply the link between this framework and our library `PriFi-lib` (which does not know at all about `sda`).

### SOCKS

PriFi anonymizes the traffic via SOCKS proxy. Once PriFi is running, you can configure your SOCKS client (e.g. browser, mail application) to connect to PriFi.

The structure is a big convoluted : we have *two* socks servers. One is *in* the PriFi client code; that's the entry point of your upstream traffic, e.g. your browser connects to the socks server *in* PriFi on your local machine.

Then, PriFi anonymizes the traffic with the help of the other clients and the relay. The anonymized traffic is outputted at the relay.

This anonymized traffic is *SOCKS traffic*. Hence, the relay needs to connect to the second SOCKS server, which is not related to PriFi (but we provide the code for it in `socks/`). It could also be a remote, public SOCKS server.

## Getting PriFi

Simply do
```
git clone https://github.com/lbarman/prifi_dev
```

WORK IN PROGRESS

Fixed in cothority's test_ism_2_699 branch.
But this branch will not be merged into anything, DeDiS working on a new version.
So for the time being, we need to check out test_ism_2_699 on $GOPATH/src/github/dedis/cothority
First, [get the Go language](https://golang.org/dl/). They have some `.tar.gz`, but I personally prefer to use my package manager :
`sudo apt-get install golang` for Ubuntu, or `sudo dnf install golang` for Fedora 24.

## Running PriFi

### SOCKS Preamble
Then, get PriFi by doing:

As explained, you need a non-prifi SOCKS server running to handle the traffic from the relay. If you don't have one, run ours :
```
./run-socks-proxy.sh 8090
go get github.com/lbarman/prifi
./prifi.sh install
```
Ignore the `No buildable source` after the first step, that's OK. This script gets all the dependencies (via `go get`), and make sure everything is correctly set.

## Running PriFi

There is one big startup script `run-prifi.sh`.

```
./run-prifi.sh
Usage: run-prifi.sh role/operation [params]
role: client, relay, trustee
operation: sockstest, all, deploy-all
params for role relay: [socks_server_port] (optional, numeric)
params for role trustee: id (required, numeric)
params for role client: id (required, numeric), [prifi_socks_server_port] (optional, numeric)
params for operation all, deploy: none
params for operation sockstest, deploy: [socks_server_port] (optional, numeric), [prifi_socks_server_port] (optional, numeric)
```

For instance, you can start a relay like this :

```
./run-prifi.sh relay
```
PriFi uses [SDA](https://github.com/dedis/cothority) as a network framework. It is easy to run all components (trustees, relay, clients) on one machine for testing purposes, or on different machines for the real setup.

... or to specify the port of the second, non-prifi socks server, like this :
Each component has a *SDA configuration* : an identity (`identity.toml`, containing a private and public key), and some knowledge of the others participants via `group.toml`. For your convenience, we pre-generated some identities in `config/identities_default`.

```
./run-prifi.sh relay 8090
```
### Testing PriFi, all components in localhost

You can start a client like this :
You can test PriFi by running `./prifi.sh all-localhost`. This will run a SOCKS server, a PriFi relay, a Trustee, and three clients on your machine. They will use the identities in `config/identities_default`. You can check what is going on by doing `tail -f {clientX|relay|trusteeX|socks}.log`. You can test browsing through PriFi by setting your browser to use a SOCKS proxy on `localhost:8081`.

```
./run-prifi.sh client 0
```
### Using PriFi in a real setup

and to specify the port of the first socks proxy integrated in PriFi :
To test a real PriFi deployement, first, re-generates your identity (so your private key is really private). The processed is detailed in the [README about ./prifi.sh startup script](README_prifi.sh.md).

```
./run-prifi.sh client 0 8080
```
## More documentation :

A typical deployement could be :
- [README about the Architecture and SOCKS Proxies](README_architecture.md)

```
./run-prifi.sh relay 8090
./run-prifi.sh trustee 0
./run-prifi.sh client 0 8080
./run-prifi.sh client 1 8081
```
- [README about ./prifi.sh startup script](README_prifi.sh.md)

## Configuration

The PriFi configuration file is in `config.demo/prifi.toml`

- `DataOutputEnbaled (bool)`: Enables the link from and to the socks proxy.
- `NTrustees (int)`: Number of trustees.
- `CellSizeUp (int)`: Size of upstream data sent in one PriFi round (?)
- `CellSizeDown (int)`: Size of upstream data sent in one PriFi round (?)
- `RelayWindowSize (int)`: Number of ciphers from each trustee to buffer
- `RelayUseDummyDataDown (bool)`: When true, the relay always send
CellSizeDown bits down. When false, it may send only 1 bit.
- `RelayReportingLimit (int)`: Unused, was for the statistics.
- `UseUDP (bool)`: Enable or disable UDP broadcast for downstream data (?)
- `DoLatencyTests (bool)`: Enable or disable latency tests.
- `ReportingLimit (int)`: PriFi shuts down after this number of rounds if
not equal to `-1`.
- [README about contributing to this repository](README_contributing.md)

## API Documentation

Expand Down
135 changes: 135 additions & 0 deletions README_architecture.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# PriFi: A Low-Latency, Tracking-Resistant Protocol for Local-Area Anonymity [![Build Status](https://travis-ci.org/lbarman/prifi.svg?branch=master)](https://travis-ci.org/lbarman/prifi)

[back to main README](README.md)

## Architecture, and SOCKS proxies

### Structure

The current code is organized in two main parts :

1) `PriFi-Lib`, which is network-agnostic; it takes an interface "MessageSender" that give it functions like `SendToRelay()`, `SendToTrustee()`, ... and `ReceivedMessage()`

This is the core of the protocol PriFi.

2) `PriFi-SDA-Wrapper` (what is in folder `sda`), that does the mapping between the tree entities of SDA and our roles (Relay, Trustee, Client), and provides the MessageSender interface discussed above.

The [SDA](https://github.com/dedis/cothority) is a framework for Secure Distributed Algorithms, developped by DeDiS, EPFL. It help bootstrapping secure protocols. The "wrapper" is simply the link between this framework and our library `PriFi-lib` (which does not know at all about `sda`).

To sum up, the architecture is as follow :

```
###################### ######################
# PriFi-Lib (client) # <--- this can be instanciated as client, relay, etc. # PriFi-Lib (relay)
###################### ######################
^ ^
| |
v v
###################### <--- this box is the SDA, provided by DeDiS ######################
# SDA-Protocol # <--- (also called PriFi-SDA-Wrapper) # SDA-Protocol
# ^ # # ^
# | # # |
# v # # v
# SDA-Service # # SDA-Service
# ^ # # ^
# | # # |
# SDA-App # <--- started by ./prifi.sh # SDA-App
###################### #######################
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
HOST 1 <================ COMMUNICATES WITH ====================> HOST 2
vvvvvvvvvvvvvvvvvvvvvv vvvvvvvvvvvvvvvvvvv
```

### SOCKS

PriFi anonymizes the traffic via SOCKS proxy. Once PriFi is running, you can configure your SOCKS client (e.g. browser, mail application) to connect to PriFi.

The structure is a big convoluted : we have *two* socks servers. One is *in* the PriFi client code; that's the entry point of your upstream traffic, e.g. your browser connects to the socks server *in* PriFi on your local machine.

Then, PriFi anonymizes the traffic with the help of the other clients and the relay. The anonymized traffic is outputted at the relay.

This anonymized traffic is *SOCKS traffic*. Hence, the relay needs to connect to the second SOCKS server, which is not related to PriFi (but we provide the code for it in `socks/`). It could also be a remote, public SOCKS server.

To sum up, without SOCKS proxy, your browser does not use its SOCKS-client, and connects directly to the internet :

```
.______________.
| Browser |<--------------------------------------------------> Internet
| |
| Socks-Client | <- (unused)
|______________|
```

You can set up your browser to connect to a SOCKS server, in that case it will use its SOCKS client :


```
.______________.
| Browser |
| |
| Socks-Client | <--------------------------------------------------> SOCKS-Server
|______________| ^
|
v
Internet
```

Finally, using PriFi, the architecture is as follow :

```
._____________.
| Browser | PriFi Client
| | ._______________.
| Socks-Client| <------>| SOCKS-Server 1|
|_____________| | ^ |
| | | PriFi Relay
| v | ._______________.
| Anonymization | <--------> | Anonymization |
|_______________| | ^ |
| | |
| v |
| SOCKS-Client | <---> SOCKS-Server 2
|_______________| ^
|
v
Internet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On your machine (localhost) | | On the PriFi relay
```

You could also decide not to use the SOCKS server we provide in `socks/`, and connect to a remote, public server :


```
._____________.
| Browser | PriFi Client
| | ._______________.
| Socks-Client| <------>| SOCKS-Server 1|
|_____________| | ^ |
| | | PriFi Relay
| v | ._______________.
| Anonymization | <--------> | Anonymization |
|_______________| | ^ |
| | |
| v |
| SOCKS-Client | <---------------> Public SOCKS Server
|_______________| ^
|
v
Internet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
On your machine (localhost) | | On the PriFi relay | | Any machine
```

This setting is decided globally by the relay, not on a per-client basis.

[back to main README](README.md)
57 changes: 57 additions & 0 deletions README_contributing.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# PriFi: A Low-Latency, Tracking-Resistant Protocol for Local-Area Anonymity [![Build Status](https://travis-ci.org/lbarman/prifi.svg?branch=master)](https://travis-ci.org/lbarman/prifi)

[back to main README](README.md)

## How to contribute

This repository uses Travis CI to check continually that the code is bug-free and compliant to coding standards. No one can push to `master` directly.

A typical workflow would be :

```
$ git clone github.com/lbarman/prifi
[do great improvements]
$ git commit -am "I did great changes!"
$ git push
To github.com:lbarman/prifi.git
! [remote rejected] master -> master (protected branch hook declined)
```

Your work was rejected, as you are trying to push to master.

```
git checkout -b my-branch
git push -u origin my-branch
```

You can now check in [https://github.com/lbarman/prifi/commits/my-branch](https://github.com/lbarman/prifi/commits/my-branch) that integration tests passed (green check). A yellow dot means that the tests are still running.

Regardless of the result, you can create a new pull request (base: `master`, compare: `my-branch`), and continue commiting changes. When all integration tests passes, you will be able to merge the pull request into master.

## Contributing rules

The code is checked with the following tools :
```
go fmt
go vet
golint*
go test
```

If any of those tool exit with status 1, the code will be qualified as "non-compliant" by Travis.

*For `golint`, we add the following exceptions (i.e., we remove the original constraints) :
- Variables with underscores (`G_s`) are now allowed
- `ALL_CAPS_VARIABLES` are now allowed
- Comments for `FieldXYZ` do not need to start with `FieldXYZ...`

Additionnally, we ignore all files
- finishing by `_test.go`
- in `.deprecated` folders

One can run the tests locally with `make all` and/or `make test_verbose`


[back to main README](README.md)
Loading

0 comments on commit 2785de2

Please sign in to comment.