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

Commit 2785de2

Browse files
lbarmanlbarman
authored
Merge pull request #52 from lbarman/new-readme
Rework the ReadMe's
2 parents 801f973 + 4dc2f3e commit 2785de2

File tree

4 files changed

+319
-96
lines changed

4 files changed

+319
-96
lines changed

‎README.md

Lines changed: 18 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -5,125 +5,47 @@
55

66
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.
77

8+
For an extended introduction, please check our [website](https://lbarman.ch/prifi/).
9+
810
For more details about PriFi, please check our [WPES 2016 paper](http://www.cs.yale.edu/homes/jf/PriFi-WPES2016.pdf).
911

1012

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

13-
## Getting and running PriFi
14-
15-
## Understanding the architecture
16-
17-
### Structure
18-
19-
The current code is organized in two main parts :
20-
21-
1) `PriFi-Lib`, which is network-agnostic; it takes an interface "MessageSender" that give it functions like SendToRelay(), SendToTrustee, ... and ReceivedMessage()
22-
23-
This is the core of the protocol PriFi.
24-
25-
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.
26-
27-
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`).
28-
29-
### SOCKS
30-
31-
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.
32-
33-
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.
34-
35-
Then, PriFi anonymizes the traffic with the help of the other clients and the relay. The anonymized traffic is outputted at the relay.
36-
37-
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.
38-
3915
## Getting PriFi
4016

41-
Simply do
42-
```
43-
git clone https://github.com/lbarman/prifi_dev
44-
```
45-
46-
WORK IN PROGRESS
47-
48-
Fixed in cothority's test_ism_2_699 branch.
49-
But this branch will not be merged into anything, DeDiS working on a new version.
50-
So for the time being, we need to check out test_ism_2_699 on $GOPATH/src/github/dedis/cothority
17+
First, [get the Go language](https://golang.org/dl/). They have some `.tar.gz`, but I personally prefer to use my package manager :
18+
`sudo apt-get install golang` for Ubuntu, or `sudo dnf install golang` for Fedora 24.
5119

52-
## Running PriFi
53-
54-
### SOCKS Preamble
20+
Then, get PriFi by doing:
5521

56-
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 :
5722
```
58-
./run-socks-proxy.sh 8090
23+
go get github.com/lbarman/prifi
24+
./prifi.sh install
5925
```
26+
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.
6027

6128
## Running PriFi
6229

63-
There is one big startup script `run-prifi.sh`.
64-
65-
```
66-
./run-prifi.sh
67-
Usage: run-prifi.sh role/operation [params]
68-
role: client, relay, trustee
69-
operation: sockstest, all, deploy-all
70-
params for role relay: [socks_server_port] (optional, numeric)
71-
params for role trustee: id (required, numeric)
72-
params for role client: id (required, numeric), [prifi_socks_server_port] (optional, numeric)
73-
params for operation all, deploy: none
74-
params for operation sockstest, deploy: [socks_server_port] (optional, numeric), [prifi_socks_server_port] (optional, numeric)
75-
76-
```
77-
78-
For instance, you can start a relay like this :
79-
80-
```
81-
./run-prifi.sh relay
82-
```
30+
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.
8331

84-
... or to specify the port of the second, non-prifi socks server, like this :
32+
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`.
8533

86-
```
87-
./run-prifi.sh relay 8090
88-
```
34+
### Testing PriFi, all components in localhost
8935

90-
You can start a client like this :
36+
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`.
9137

92-
```
93-
./run-prifi.sh client 0
94-
```
38+
### Using PriFi in a real setup
9539

96-
and to specify the port of the first socks proxy integrated in PriFi :
40+
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).
9741

98-
```
99-
./run-prifi.sh client 0 8080
100-
```
42+
## More documentation :
10143

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

104-
```
105-
./run-prifi.sh relay 8090
106-
./run-prifi.sh trustee 0
107-
./run-prifi.sh client 0 8080
108-
./run-prifi.sh client 1 8081
109-
```
46+
- [README about ./prifi.sh startup script](README_prifi.sh.md)
11047

111-
## Configuration
112-
113-
The PriFi configuration file is in `config.demo/prifi.toml`
114-
115-
- `DataOutputEnbaled (bool)`: Enables the link from and to the socks proxy.
116-
- `NTrustees (int)`: Number of trustees.
117-
- `CellSizeUp (int)`: Size of upstream data sent in one PriFi round (?)
118-
- `CellSizeDown (int)`: Size of upstream data sent in one PriFi round (?)
119-
- `RelayWindowSize (int)`: Number of ciphers from each trustee to buffer
120-
- `RelayUseDummyDataDown (bool)`: When true, the relay always send
121-
CellSizeDown bits down. When false, it may send only 1 bit.
122-
- `RelayReportingLimit (int)`: Unused, was for the statistics.
123-
- `UseUDP (bool)`: Enable or disable UDP broadcast for downstream data (?)
124-
- `DoLatencyTests (bool)`: Enable or disable latency tests.
125-
- `ReportingLimit (int)`: PriFi shuts down after this number of rounds if
126-
not equal to `-1`.
48+
- [README about contributing to this repository](README_contributing.md)
12749

12850
## API Documentation
12951

‎README_architecture.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# 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)
2+
3+
[back to main README](README.md)
4+
5+
## Architecture, and SOCKS proxies
6+
7+
### Structure
8+
9+
The current code is organized in two main parts :
10+
11+
1) `PriFi-Lib`, which is network-agnostic; it takes an interface "MessageSender" that give it functions like `SendToRelay()`, `SendToTrustee()`, ... and `ReceivedMessage()`
12+
13+
This is the core of the protocol PriFi.
14+
15+
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.
16+
17+
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`).
18+
19+
To sum up, the architecture is as follow :
20+
21+
```
22+
###################### ######################
23+
# PriFi-Lib (client) # <--- this can be instanciated as client, relay, etc. # PriFi-Lib (relay)
24+
###################### ######################
25+
^ ^
26+
| |
27+
v v
28+
###################### <--- this box is the SDA, provided by DeDiS ######################
29+
# SDA-Protocol # <--- (also called PriFi-SDA-Wrapper) # SDA-Protocol
30+
# ^ # # ^
31+
# | # # |
32+
# v # # v
33+
# SDA-Service # # SDA-Service
34+
# ^ # # ^
35+
# | # # |
36+
# SDA-App # <--- started by ./prifi.sh # SDA-App
37+
###################### #######################
38+
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
39+
HOST 1 <================ COMMUNICATES WITH ====================> HOST 2
40+
vvvvvvvvvvvvvvvvvvvvvv vvvvvvvvvvvvvvvvvvv
41+
42+
```
43+
44+
### SOCKS
45+
46+
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.
47+
48+
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.
49+
50+
Then, PriFi anonymizes the traffic with the help of the other clients and the relay. The anonymized traffic is outputted at the relay.
51+
52+
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.
53+
54+
To sum up, without SOCKS proxy, your browser does not use its SOCKS-client, and connects directly to the internet :
55+
56+
```
57+
.______________.
58+
| Browser |<--------------------------------------------------> Internet
59+
| |
60+
| Socks-Client | <- (unused)
61+
|______________|
62+
63+
```
64+
65+
You can set up your browser to connect to a SOCKS server, in that case it will use its SOCKS client :
66+
67+
68+
```
69+
70+
.______________.
71+
| Browser |
72+
| |
73+
| Socks-Client | <--------------------------------------------------> SOCKS-Server
74+
|______________| ^
75+
|
76+
v
77+
Internet
78+
79+
80+
```
81+
82+
Finally, using PriFi, the architecture is as follow :
83+
84+
```
85+
86+
._____________.
87+
| Browser | PriFi Client
88+
| | ._______________.
89+
| Socks-Client| <------>| SOCKS-Server 1|
90+
|_____________| | ^ |
91+
| | | PriFi Relay
92+
| v | ._______________.
93+
| Anonymization | <--------> | Anonymization |
94+
|_______________| | ^ |
95+
| | |
96+
| v |
97+
| SOCKS-Client | <---> SOCKS-Server 2
98+
|_______________| ^
99+
|
100+
v
101+
Internet
102+
103+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
104+
On your machine (localhost) | | On the PriFi relay
105+
```
106+
107+
You could also decide not to use the SOCKS server we provide in `socks/`, and connect to a remote, public server :
108+
109+
110+
```
111+
112+
._____________.
113+
| Browser | PriFi Client
114+
| | ._______________.
115+
| Socks-Client| <------>| SOCKS-Server 1|
116+
|_____________| | ^ |
117+
| | | PriFi Relay
118+
| v | ._______________.
119+
| Anonymization | <--------> | Anonymization |
120+
|_______________| | ^ |
121+
| | |
122+
| v |
123+
| SOCKS-Client | <---------------> Public SOCKS Server
124+
|_______________| ^
125+
|
126+
v
127+
Internet
128+
129+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
130+
On your machine (localhost) | | On the PriFi relay | | Any machine
131+
```
132+
133+
This setting is decided globally by the relay, not on a per-client basis.
134+
135+
[back to main README](README.md)

‎README_contributing.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# 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)
2+
3+
[back to main README](README.md)
4+
5+
## How to contribute
6+
7+
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.
8+
9+
A typical workflow would be :
10+
11+
```
12+
$ git clone github.com/lbarman/prifi
13+
14+
[do great improvements]
15+
16+
$ git commit -am "I did great changes!"
17+
$ git push
18+
To github.com:lbarman/prifi.git
19+
! [remote rejected] master -> master (protected branch hook declined)
20+
```
21+
22+
Your work was rejected, as you are trying to push to master.
23+
24+
```
25+
git checkout -b my-branch
26+
git push -u origin my-branch
27+
```
28+
29+
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.
30+
31+
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.
32+
33+
## Contributing rules
34+
35+
The code is checked with the following tools :
36+
```
37+
go fmt
38+
go vet
39+
golint*
40+
go test
41+
```
42+
43+
If any of those tool exit with status 1, the code will be qualified as "non-compliant" by Travis.
44+
45+
*For `golint`, we add the following exceptions (i.e., we remove the original constraints) :
46+
- Variables with underscores (`G_s`) are now allowed
47+
- `ALL_CAPS_VARIABLES` are now allowed
48+
- Comments for `FieldXYZ` do not need to start with `FieldXYZ...`
49+
50+
Additionnally, we ignore all files
51+
- finishing by `_test.go`
52+
- in `.deprecated` folders
53+
54+
One can run the tests locally with `make all` and/or `make test_verbose`
55+
56+
57+
[back to main README](README.md)

0 commit comments

Comments
 (0)