BadVPN – Blame information for rev 1
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
1 | office | 1 | .TH badvpn 7 "6 October 2010" |
2 | .SH NAME |
||
3 | BadVPN - peer-to-peer VPN system |
||
4 | .SH DESCRIPTION |
||
5 | .P |
||
6 | BadVPN is a peer-to-peer VPN system. It provides a Layer 2 (Ethernet) network between |
||
7 | the peers (VPN network nodes). The peers connect to a central server which acts as a chat |
||
8 | server for them to establish direct connections between each other (data connections). |
||
9 | These connections are used for transferring network data (Ethernet frames). |
||
10 | .SS "Features" |
||
11 | .P |
||
12 | .B "Data connections" |
||
13 | .P |
||
14 | Peers can transfer network data either over UDP or TCP. For both there are ways of |
||
15 | securing the data (see below). |
||
16 | .P |
||
17 | .B "IPv6 support" |
||
18 | .P |
||
19 | IPv6 can be used for both server connections and data connections, alongside with IPv4. |
||
20 | Additionally, both can be combined to allow gradual migration to IPv6. |
||
21 | .P |
||
22 | .B "Address selection" |
||
23 | .P |
||
24 | Because NATs and firewalls are widespread, it is harder for peer-to-peer services to operate. |
||
25 | In general, for two computers to be able to communicate, one computer must |
||
26 | .I bind |
||
27 | to one of its addresses, and the other computer must |
||
28 | .I connect |
||
29 | to the computer that binded (both for TCP and UDP). In a network with point-to-point |
||
30 | connectivity, the connecting computer can connect to the same address as the binding computer |
||
31 | bound to, so it is sufficient for the binding computer to send its address to the connecting |
||
32 | computer. However, NATs and firewalls break point-to-point connectivity. When a network is |
||
33 | behind a NAT, it is, by default, impossible for computers outside of that network to connect |
||
34 | to computers inside the network. This is because computers inside the network have no externally |
||
35 | visible IP address, and only communicate with the outside world through the external IP address |
||
36 | of the NAT router. It is however possible to manually configure the NAT router to |
||
37 | .I forward |
||
38 | a specific port number on its external IP address to a specific computer inside the network. |
||
39 | This makes it possible for a computer outside of the network to connect to a computer inside |
||
40 | a network, however, it must connect to the external address of the NAT router (rather than |
||
41 | the address the computer inside bound to, which is its internal address). So there needs |
||
42 | to be some way for the connecting peer to know what address to connect to. |
||
43 | .P |
||
44 | BadVPN solves this problem with so-called |
||
45 | .IR "address scopes" "." |
||
46 | The peer that binds must have a list of external addresses for each address it can bind to, |
||
47 | possibly ordered from best to worst. Each external address has its scope name. A scope name |
||
48 | represents part of a network from which an external address can be reached. On the other hand, |
||
49 | the peer that connects must have a list of scopes which it can reach. When a peer binds to an |
||
50 | address, it sends the other peer a list of external addresses along with scope names. That peer |
||
51 | than chooses the first external address whose scope it recognizes and attempts to connect to it |
||
52 | (if there is one). |
||
53 | .P |
||
54 | BadVPN also allows a peer to have multiple addresses for binding to. It is possible to specify |
||
55 | both an IPv4 and an IPv6 address to work in a multi-protocol environment. |
||
56 | .P |
||
57 | .B "Relaying" |
||
58 | .P |
||
59 | BadVPN can be configured to allow pairs of peers that cannot communicate directly (i.e. because of |
||
60 | NATs or firewalls) to relay network data through a third peer. Relaying is only attempted if |
||
61 | none of the two peers recognize any of the other peer's external addresses (or there are none). |
||
62 | For relaying to work, for each of the two peers (P1, other one P2) there must be at least one |
||
63 | third peer (R) that P1 it is allowed to relay through and can communicate directly with, and all |
||
64 | such peers R must be able to communicate directly with P2. |
||
65 | .P |
||
66 | .B "IGMP snooping" |
||
67 | .P |
||
68 | BadVPN nodes perform IGMP snooping in order to efficiently deliver multicast frames. For example, |
||
69 | this makes it possible to use BadVPN as a tunnel into an IPTV network of an Internet Service Provider |
||
70 | for you to watch TV from wherever you want (given sufficient link quality). |
||
71 | .P |
||
72 | .B "Code quality" |
||
73 | .P |
||
74 | BadVPN has great focus on code quality and reliability. BadVPN is written in the C programming |
||
75 | language. It is a single-threaded event-driven program. This allows for low resource usage and |
||
76 | fast response times. Even though C is a relatively low-level language, the programs are made of |
||
77 | small, highly cohesive and loosely coupled modules that are combined into a complete program on |
||
78 | a high level. Modules are accesed and communicate through small, simple and to-the-point interfaces. |
||
79 | It utilizes a flow-based design which greatly simplifies processing of data and input and output |
||
80 | of the programs. |
||
81 | .SS "Security features" |
||
82 | .P |
||
83 | BadVPN contains many security features, all of which are optional. The included security |
||
84 | features are described here. |
||
85 | .P |
||
86 | .B TLS for client-server connections |
||
87 | .P |
||
88 | It is possible for the peers to communicate with the chat server securely with TLS. It is |
||
89 | highly recommended that this feature is used if any security whatsoever is needed. Not |
||
90 | using it renders all other security features useless, since clients exchange keys |
||
91 | unencrypted via the server. When enabled, the chat server requires each client to identify |
||
92 | itself with a certificate. |
||
93 | .P |
||
94 | BadVPN uses Mozilla's NSS library for TLS support. This means that the required certificates |
||
95 | and keys must be available in a NSS database. The database and certificates can be |
||
96 | generated with the |
||
97 | .B certutil |
||
98 | command. See the examples section on how to generate and distribute the certificates. |
||
99 | .P |
||
100 | .B TLS for peer messaging |
||
101 | .P |
||
102 | If TLS is being used for client-server connections, it will also be used between each pair of |
||
103 | peers communicating via the server, on top of the TLS connections to the server. This secures |
||
104 | the messages from the server itself. It is important because the messages may include |
||
105 | encryption keys and other private data. |
||
106 | .P |
||
107 | .B TLS for TCP data connections |
||
108 | .P |
||
109 | If TCP is used for data connections between the peers, the data connections can be secured |
||
110 | with TLS. This requires using TLS for client-server connections. The clients need to trust |
||
111 | each others' certificates to be able to connect. Additionally, each client must identify to |
||
112 | its peers with the same certificates it used for connecting to the server. |
||
113 | .P |
||
114 | .B Encryption for UDP data connections |
||
115 | .P |
||
116 | If UDP is used for data connections, it is possible for each pair of peers to encrypt their |
||
117 | UDP packets with a symmetric block cipher. Note that the encryption keys are transmitted |
||
118 | through the server unencrypted, so for this to be useful, server connections must be secured |
||
119 | with TLS. The encryption aims to prevent third parties from seeing the real contents of |
||
120 | the network data being transfered. |
||
121 | .P |
||
122 | .B Hashes for UDP data connections |
||
123 | .P |
||
124 | If UDP is used for data connections, it is possible to include hashes in packets. Note that |
||
125 | hashes are only useful together with encryption. If enabled, the hash is calculated on the |
||
126 | packet with the hash field zeroed and then written to the hash field. Hashes are calculated |
||
127 | and included before encryption (if enabled). Combined with encryption, hashes aim to prevent |
||
128 | third parties from tampering with the packets and injecting them into the network. |
||
129 | .P |
||
130 | .B One-time passwords for UDP data connections |
||
131 | .P |
||
132 | If UDP is used for data connections, it is possible to include one-time passwords in packets. |
||
133 | Note that for this to be useful, server connections must be secured with TLS. |
||
134 | One-time passwords are generated from a seed value by encrypting zero data with a block cipher. |
||
135 | The seed contains the encryption key for the block cipher and the initialization vector. |
||
136 | Only a fixed number of passwords are used from a single seed. The peers exchange seeds through |
||
137 | the server. One-time passwords aim to prevent replay attacks. |
||
138 | .P |
||
139 | .B Control over peer communication |
||
140 | .P |
||
141 | It is possible to instruct the chat server to only allow certain peers to communicate. This |
||
142 | will break end-to-end connectivity in the virtual network. It is useful in certain cases |
||
143 | to improve security, for example when the VPN is used only to allow clients to securely connect |
||
144 | to a central service. |
||
145 | .SH "EXAMPLES" |
||
146 | .SS "Setting up certificates" |
||
147 | .P |
||
148 | If you want to use TLS for server connections (recommended), the server and all the peers will |
||
149 | need certificates. This section explains how to generate and distribute the certificates using |
||
150 | NSS command line tools. |
||
151 | .P |
||
152 | .B Setting up the Certificate Authority (CA) |
||
153 | .P |
||
154 | On the system that will host the CA, create a NSS database for the CA and generate a CA certificate |
||
155 | valid for 24 months: |
||
156 | .P |
||
157 | vpnca $ certutil -d sql:/home/vpnca/nssdb -N |
||
158 | .br |
||
159 | vpnca $ certutil -d sql:/home/vpnca/nssdb -S -n "vpnca" -s "CN=vpnca" -t "TC,," -x -2 -v 24 |
||
160 | .br |
||
161 | > Is this a CA certificate [y/N]? y |
||
162 | .br |
||
163 | > Enter the path length constraint, enter to skip [<0 for unlimited path]: > -1 |
||
164 | .br |
||
165 | > Is this a critical extension [y/N]? n |
||
166 | .P |
||
167 | Export the public CA certificate (this file is public): |
||
168 | .P |
||
169 | vpnca $ certutil -d sql:/home/vpnca/nssdb -L -n vpnca -a > ca.pem |
||
170 | .P |
||
171 | .B Setting up the server certificate |
||
172 | .P |
||
173 | On the CA system, generate a certificate for the server valid for 24 months, with TLS server usage context: |
||
174 | .P |
||
175 | vpnca $ certutil -d sql:/home/vpnca/nssdb -S -n "<insert_server_name>" -s "CN=<insert_server_name>" -c "vpnca" -t ",," -2 -6 -v 24 |
||
176 | .br |
||
177 | > 0 |
||
178 | .br |
||
179 | > -1 |
||
180 | .br |
||
181 | > Is this a critical extension [y/N]? n |
||
182 | .br |
||
183 | > Is this a CA certificate [y/N]? n |
||
184 | .br |
||
185 | > Enter the path length constraint, enter to skip [<0 for unlimited path]: > |
||
186 | .br |
||
187 | > Is this a critical extension [y/N]? n |
||
188 | .P |
||
189 | Export the server certificate to a PKCS#12 file (this file must be kept secret): |
||
190 | .P |
||
191 | vpnca $ pk12util -d sql:/home/vpnca/nssdb -o server.p12 -n "<insert_server_name>" |
||
192 | .P |
||
193 | On the system that will run the server, create a NSS database and import the CA certificate |
||
194 | and the server cerificate: |
||
195 | .P |
||
196 | vpnserver $ certutil -d sql:/home/vpnserver/nssdb -N |
||
197 | .br |
||
198 | vpnserver $ certutil -d sql:/home/vpnserver/nssdb -A -t "CT,," -n "vpnca" -i /path/to/ca.pem |
||
199 | .br |
||
200 | vpnserver $ pk12util -d sql:/home/vpnserver/nssdb -i /path/to/server.p12 |
||
201 | .P |
||
202 | .B Setting up peer certificates |
||
203 | .P |
||
204 | On the CA system, generate a certificate for the peer valid for 24 months, with TLS client and |
||
205 | TLS server usage contexts: |
||
206 | .P |
||
207 | vpnca $ certutil -d sql:/home/vpnca/nssdb -S -n "peer-<insert_name>" -s "CN=peer-<insert_name>" -c "vpnca" -t ",," -2 -6 -v 24 |
||
208 | .br |
||
209 | > 0 |
||
210 | .br |
||
211 | > 1 |
||
212 | .br |
||
213 | > -1 |
||
214 | .br |
||
215 | > Is this a critical extension [y/N]? n |
||
216 | .br |
||
217 | > Is this a CA certificate [y/N]? n |
||
218 | .br |
||
219 | > Enter the path length constraint, enter to skip [<0 for unlimited path]: > |
||
220 | .br |
||
221 | > Is this a critical extension [y/N]? n |
||
222 | .P |
||
223 | Export the peer certificate to a PKCS#12 file (this file must be kept secret): |
||
224 | .P |
||
225 | vpnca $ pk12util -d sql:/home/vpnca/nssdb -o peer-<insert_name>.p12 -n "peer-<insert_name>" |
||
226 | .P |
||
227 | On the system that will run the VPN client, create a NSS database and import the CA certificate |
||
228 | and the peer cerificate: |
||
229 | .P |
||
230 | vpnclient $ certutil -d sql:/home/vpnclient/nssdb -N |
||
231 | .br |
||
232 | vpnclient $ certutil -d sql:/home/vpnclient/nssdb -A -t "CT,," -n "vpnca" -i /path/to/ca.pem |
||
233 | .br |
||
234 | vpnclient $ pk12util -d sql:/home/vpnclient/nssdb -i /path/to/peer-<insert_name>.p12 |
||
235 | .SS "Setting up TAP devices" |
||
236 | .P |
||
237 | You need to create and configure TAP devices on all computers that will participate in the virtual network |
||
238 | (i.e. run the client program). See |
||
239 | .BR badvpn-client (8), |
||
240 | section `TAP DEVICE CONFIGURATION` for details. |
||
241 | .SS "Example: Local IPv4 network, UDP transport, zero security" |
||
242 | .P |
||
243 | .B Starting the server: |
||
244 | .P |
||
245 | badvpn-server --listen-addr 0.0.0.0:7000 |
||
246 | .P |
||
247 | .B Starting the peers: |
||
248 | .P |
||
249 | badvpn-client |
||
250 | .RS |
||
251 | --server-addr <insert_server_local_address>:7000 |
||
252 | .br |
||
253 | --transport-mode udp --encryption-mode none --hash-mode none |
||
254 | .br |
||
255 | --scope local1 |
||
256 | .br |
||
257 | --bind-addr 0.0.0.0:8000 --num-ports 30 --ext-addr {server_reported}:8000 local1 |
||
258 | .br |
||
259 | --tapdev tap0 |
||
260 | .RE |
||
261 | .SS "Example: Adding TLS and UDP security" |
||
262 | .P |
||
263 | .B Starting the server (other options as above): |
||
264 | .P |
||
265 | badvpn-server ... |
||
266 | .RS |
||
267 | --ssl --nssdb sql:/home/vpnserver/nssdb --server-cert-name "<insert_server_name>" |
||
268 | .RE |
||
269 | .P |
||
270 | .B Starting the peers (other options as above): |
||
271 | .P |
||
272 | badvpn-client ... |
||
273 | .RS |
||
274 | --ssl --nssdb sql:/home/vpnclient/nssdb --client-cert-name "peer-<insert_name>" |
||
275 | .br |
||
276 | --encryption-mode blowfish --hash-mode md5 --otp blowfish 3000 2000 |
||
277 | .RE |
||
278 | .SS "Example: Multiple local networks behind NATs, all connected to the Internet" |
||
279 | .P |
||
280 | For each peer in the existing local network, configure the NAT router to forward its |
||
281 | range of ports to it (assuming their port ranges do not overlap). The clients also need |
||
282 | to know the external IP address of the NAT router. If you don't have a static one, |
||
283 | you'll need to discover it before starting the clients. Also forward the server port to |
||
284 | the server. |
||
285 | .P |
||
286 | .B Starting the peers in the local network (other options as above): |
||
287 | .P |
||
288 | badvpn-client |
||
289 | .RS |
||
290 | .RB "..." |
||
291 | .br |
||
292 | --scope internet |
||
293 | .br |
||
294 | .RB "..." |
||
295 | .br |
||
296 | --ext-addr <insert_NAT_routers_external_IP>:<insert_start_of_forwarded_port_range> internet |
||
297 | .br |
||
298 | .RB "..." |
||
299 | .RE |
||
300 | .P |
||
301 | The --ext-addr option applies to the previously specified --bind-addr option, and must come after |
||
302 | the first --ext-addr option which specifies a local address. |
||
303 | .P |
||
304 | Now perform a similar setup in some other local network behind a NAT. However: |
||
305 | .br |
||
306 | - Don't set up a new server, instead make the peers connect to the existing server in the first |
||
307 | local network. |
||
308 | .br |
||
309 | - You can't use {server_reported} for the local address --ext-addr options, because the server |
||
310 | would report the NAT router's external address rather than the peer's internal address. Instead |
||
311 | each peer has to know its internal IP address. |
||
312 | .br |
||
313 | - Use a different scope name for it, e.g. "local2" instead of "local1". |
||
314 | .P |
||
315 | If setup correctly, all peers will be able to communicate: those in the same local network will |
||
316 | communicate directly through local addresses, and those in different local networks will |
||
317 | communicate through the Internet. |
||
318 | .SH "PROTOCOL" |
||
319 | The protocols used in BadVPN are described in the source code in the protocol/ directory. |
||
320 | .SH "SEE ALSO" |
||
321 | .BR badvpn-server (8), |
||
322 | .BR badvpn-client (8) |
||
323 | .SH AUTHORS |
||
324 | Ambroz Bizjak <ambrop7@gmail.com> |