quincy 0.1.1

QUIC-based VPN
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Quincy
[![Crates.io](https://img.shields.io/crates/v/quincy.svg)](https://crates.io/crates/quincy)
[![Documentation](https://docs.rs/quincy/badge.svg)](https://docs.rs/quincy/)
[![Build status](https://github.com/M0dEx/quincy/workflows/CI/badge.svg)](https://github.com/M0dEx/quincy/actions?query=workflow%3ACI)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENCE)

Quincy is a VPN client and server implementation using the [QUIC](https://en.wikipedia.org/wiki/QUIC) protocol.

## Design
Quincy uses the QUIC protocol implemented by [`quinn`](https://github.com/quinn-rs/quinn) to create an encrypted tunnnel between clients and the server.

This tunnel serves two purposes:
- authentication using a reliable bidirectional stream
- data transfer using unreliable datagrams (for lower latency and avoidance of multiple reliability layers)

After a connection is established and the client is authenticated, a TUN interface is spawned using an IP address provided by the server.

When all is set up, multiple tasks are spawned (on both the client and the server), with 2 of them being the most important:
- authentication task - responsible for sending the session token in the specified interval
- connection task - responsible for relaying packets between the TUN interface and the QUIC tunnel

These tasks run in parallel using the [`tokio`](https://github.com/tokio-rs/tokio) runtime for added efficiency and throughput.

## Supported platforms
- [ ] Windows
- [X] Linux
- [X] MacOS

## Building from sources
As Quincy does not rely upon any non-Rust libraries, the build process is incredibly simple:
```bash
$ cargo build
```
If you additionally want to build Quincy in release mode with optimizations, add the `--release` switch:
```bash
$ cargo build --release
```
The resulting binaries can be found in the `target/debug` and `target/release` directories.

## Usage
Quincy is split into 3 binaries: 
- `client`: The VPN client
- `server`: The VPN server
- `users`: A utility binary meant for managing the `users` file

### Client
The Quincy client requires a separate configuration file, an example of which can be found in `examples/client.toml`:
```toml
# The address and port the Quincy server is available at
connection_string = "quincy:55555"

[authentication]
# The username used for authentication
username = "test"
# The password used for authentication
password = "test"
# A list of trusted certificates the server can use or have its certificate signed by
trusted_certificates = ["examples/cert/ca_cert.pem"]

[connection]
# The MTU used by the QUIC tunnel and the spawned TUN interface
mtu = 1400

[log]
# The log level
level = "info"
```

With the configuration file in place, the client can be started using the following command:
```bash
$ client --config-path examples/client.toml
```

Routes are set up by default on some systems (Linux) and not set-up at all on others (MacOS).

### Server
The Quincy server requires a separate configuration file, an example of which can be found in `examples/server.toml`:
```toml
# Section representing tunnel configuration
[tunnels.tun0]
# Name of the tunnel (currently not used as the name of the interface)
name = "tun0"
# Path to the certificate used for TLS
certificate_file = "examples/cert/server_cert.pem"
# Path to the certificate key used for TLS
certificate_key_file = "examples/cert/server_key.pem"
# The address of the tunnel endpoint and base address of the address pool available to clients
address_tunnel = "10.0.0.1"
# Netmask used to generate the address pool available to clients
address_mask = "255.255.255.0"
# Path to the file containing user credentials
users_file = "examples/users"

[connection]
# The MTU used by the QUIC tunnel and the spawned TUN interface
mtu = 1400

[log]
# The log level
level = "info"
```

With the configuration file in place, the client can be started using the following command:
```bash
$ server --config-path examples/server.toml
```

### Users
The users utility can be used to manage entries the `users` file. 
The `users` file contains usernames and password hashes in the following format (`examples/users`):
```
test:$argon2id$v=19$m=19456,t=2,p=1$S9rMLOcz/dnYN4cnyc/TJg$ES0p+DErLfcWoUJ2tvZlxZSSIGYNUEe0ZpKBDz7MOj0
```

The following command can be used to add users to this file:
```bash
$ users --add examples/users
```

The prompts will look something like this:
```
Enter the username: test 
Enter password for user 'test': 
Confirm password for user 'test': 
```

A similar command can be used to remove users from the file:
```bash
$ users --remove examples/users
```

The prompt will again look something like this:
```
Enter the username: test 
```