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