BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
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>