1badvpn(7)              Miscellaneous Information Manual              badvpn(7)
2
3
4

NAME

6       BadVPN - peer-to-peer VPN system
7

DESCRIPTION

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
15   Features
16       Data connections
17
18       Peers  can transfer network data either over UDP or TCP. For both there
19       are ways of securing the data (see below).
20
21       IPv6 support
22
23       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
27       Address selection
28
29       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
51       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
62       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
66       Relaying
67
68       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
77       IGMP snooping
78
79       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
84       Code quality
85
86       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
96   Security features
97       BadVPN  contains many security features, all of which are optional. The
98       included security features are described here.
99
100       TLS for client-server connections
101
102       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
109       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
115       TLS for peer messaging
116
117       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
123       TLS for TCP data connections
124
125       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
131       Encryption for UDP data connections
132
133       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
140       Hashes for UDP data connections
141
142       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
150       One-time passwords for UDP data connections
151
152       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
161       Control over peer communication
162
163       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

EXAMPLES

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
175       Setting up the Certificate Authority (CA)
176
177       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
180       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
188       Export the public CA certificate (this file is public):
189
190       vpnca $ certutil -d sql:/home/vpnca/nssdb -L -n vpnca -a > ca.pem
191
192       Setting up the server certificate
193
194       On the CA system, generate a certificate for the server  valid  for  24
195       months, with TLS server usage context:
196
197       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
207       Export the server certificate to a PKCS#12 file (this file must be kept
208       secret):
209
210       vpnca  $   pk12util   -d   sql:/home/vpnca/nssdb   -o   server.p12   -n
211       "<insert_server_name>"
212
213       On  the  system  that  will  run  the server, create a NSS database and
214       import the CA certificate and the server cerificate:
215
216       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
222       Setting up peer certificates
223
224       On the CA system, generate a certificate for  the  peer  valid  for  24
225       months, with TLS client and TLS server usage contexts:
226
227       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
238       Export  the  peer certificate to a PKCS#12 file (this file must be kept
239       secret):
240
241       vpnca $ pk12util -d sql:/home/vpnca/nssdb -o peer-<insert_name>.p12  -n
242       "peer-<insert_name>"
243
244       On  the  system that will run the VPN client, create a NSS database and
245       import the CA certificate and the peer cerificate:
246
247       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
253   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
258   Example: Local IPv4 network, UDP transport, zero security
259       Starting the server:
260
261       badvpn-server --listen-addr 0.0.0.0:7000
262
263       Starting the peers:
264
265       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
273   Example: Adding TLS and UDP security
274       Starting the server (other options as above):
275
276       badvpn-server ...
277              --ssl   --nssdb   sql:/home/vpnserver/nssdb   --server-cert-name
278              "<insert_server_name>"
279
280       Starting the peers (other options as above):
281
282       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
288   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
296       Starting the peers in the local network (other options as above):
297
298       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
306       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
310       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
320       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

PROTOCOL

326       The protocols used in BadVPN are described in the source  code  in  the
327       protocol/ directory.
328

SEE ALSO

330       badvpn-server(8), badvpn-client(8)
331

AUTHORS

333       Ambroz Bizjak <ambrop7@gmail.com>
334
335
336
337                                6 October 2010                       badvpn(7)
Impressum