1 |
\input texinfo @c -*-texinfo-*- |
2 |
@c %**start of header |
3 |
@setfilename vpe.info |
4 |
@settitle vpe Manual |
5 |
@setchapternewpage odd |
6 |
@c %**end of header |
7 |
|
8 |
@ifinfo |
9 |
@dircategory Networking tools |
10 |
@direntry |
11 |
* vpe: (vpe). The vpe Manual. |
12 |
@end direntry |
13 |
|
14 |
This is the info manual for vpe, a Virtual Private Ethernet daemon. |
15 |
|
16 |
Copyright @copyright{} 2003 Marc Lehmann <vpe@@plan9.de>. The original |
17 |
document that was used as a base for this manual is copyright |
18 |
@copyright{} 1998-2002 Ivo Timmermans <ivo@@o2w.nl>, Guus Sliepen |
19 |
<guus@@sliepen.eu.org> and Wessel Dankers <wsl@@nl.linux.org>. |
20 |
|
21 |
Permission is granted to make and distribute verbatim copies of this |
22 |
manual provided the copyright notice and this permission notice are |
23 |
preserved on all copies. |
24 |
|
25 |
Permission is granted to copy and distribute modified versions of this |
26 |
manual under the conditions for verbatim copying, provided that the |
27 |
entire resulting derived work is distributed under the terms of a |
28 |
permission notice identical to this one. |
29 |
|
30 |
@end ifinfo |
31 |
|
32 |
@titlepage |
33 |
@title vpe Manual |
34 |
@subtitle Setting up a Virtual Private Ethernet |
35 |
@author Marc Lehmann, Ivo Timmermans and Guus Sliepen |
36 |
|
37 |
@page |
38 |
@vskip 0pt plus 1filll |
39 |
@cindex copyright |
40 |
Copyright @copyright{} 2003 Marc Lehmann <vpe@@plan9.de>, 1998-2002 Ivo |
41 |
Timmermans <ivo@@o2w.nl>, Guus Sliepen <guus@@sliepen.eu.org> and Wessel |
42 |
Dankers <wsl@@nl.linux.org>. |
43 |
|
44 |
Permission is granted to make and distribute verbatim copies of this |
45 |
manual provided the copyright notice and this permission notice are |
46 |
preserved on all copies. |
47 |
|
48 |
Permission is granted to copy and distribute modified versions of this |
49 |
manual under the conditions for verbatim copying, provided that the |
50 |
entire resulting derived work is distributed under the terms of a |
51 |
permission notice identical to this one. |
52 |
|
53 |
@end titlepage |
54 |
|
55 |
@c ================================================================== |
56 |
@node Top, Introduction, (dir), (dir) |
57 |
|
58 |
This is the documentation for the Virtual Private Ethernet suite. |
59 |
|
60 |
As you will quickly find out, this manual was adopted from the tincd |
61 |
manual, and many things, like the technical infromation or config |
62 |
directives, aren't yet documented here. |
63 |
|
64 |
@menu |
65 |
* Introduction:: Introduction |
66 |
* Preparations:: |
67 |
* Installation:: |
68 |
* Configuration:: |
69 |
* Running vpe:: |
70 |
* Technical information:: |
71 |
* About us:: |
72 |
* Concept Index:: All used terms explained |
73 |
@end menu |
74 |
|
75 |
|
76 |
@contents |
77 |
|
78 |
@c ================================================================== |
79 |
@node Introduction, Preparations, Top, Top |
80 |
@chapter Introduction |
81 |
|
82 |
@cindex vpe |
83 |
vpe is a Virtual Private Network (VPN) suite that uses tunneling and |
84 |
encryption to create a secure (and optionally untrusted) private network |
85 |
between hosts on the Internet. |
86 |
|
87 |
Because the tunnel appears to the IP level network code as a normal |
88 |
network device, there is no need to adapt any existing software. |
89 |
The encrypted tunnels allows VPN sites to share information with each other |
90 |
over the Internet without exposing any information to others. |
91 |
|
92 |
This document is the manual for vpe. Included are chapters on how to |
93 |
configure your computer to use vpe, as well as the configuration process |
94 |
of vpe itself. |
95 |
|
96 |
@menu |
97 |
* VPNs:: Virtual Private Networks in general |
98 |
* vpe:: about vpe |
99 |
* Supported platforms:: |
100 |
@end menu |
101 |
|
102 |
@c ================================================================== |
103 |
@node VPNs, vpe, Introduction, Introduction |
104 |
@section Virtual Private Networks |
105 |
|
106 |
@cindex VPN |
107 |
|
108 |
A Virtual Private Network or VPN is a network that can only be accessed by |
109 |
a few elected computers that participate. This goal is achievable in more |
110 |
than just one way. |
111 |
|
112 |
@cindex private |
113 |
|
114 |
Private networks can consist of a single stand-alone Ethernet LAN. Or |
115 |
even two computers hooked up using a null-modem cable. In these cases, |
116 |
it is obvious that the network is @emph{private}, no one can access it |
117 |
from the outside. But if your computers are linked to the Internet, |
118 |
the network is not private anymore, unless one uses firewalls to block |
119 |
all private traffic. But then, there is no way to send private data to |
120 |
trusted computers on the other end of the Internet. |
121 |
|
122 |
@cindex virtual |
123 |
|
124 |
This problem can be solved by using @emph{virtual} networks. Virtual |
125 |
networks can live on top of other networks, but they use encapsulation to |
126 |
keep using their private address space so they do not interfere with the |
127 |
Internet. Mostly, virtual networks appear like a singe LAN, even though |
128 |
they can span the entire world. But virtual networks can't be secured |
129 |
by using firewalls, because the traffic that flows through it has to go |
130 |
through the Internet, where other people can look at it. |
131 |
|
132 |
As is the case with either type of VPN, anybody could eavesdrop. Or worse, |
133 |
alter data. Hence it's probably advisable to encrypt and sign the data |
134 |
that flows over the network. |
135 |
|
136 |
When one introduces encryption, we can form a true VPN. Other people may |
137 |
see encrypted traffic, but if they don't know how to decipher it (they |
138 |
need to know the key for that), they cannot read the information that |
139 |
flows through the VPN. This is what vpe was made for. |
140 |
|
141 |
|
142 |
@c ================================================================== |
143 |
@node vpe, Supported platforms, VPNs, Introduction |
144 |
@section vpe |
145 |
|
146 |
@cindex vped |
147 |
|
148 |
vpe supports encryption, it consists of a daemon (vped) for both the |
149 |
receiving and sending end and a control program (vpectrl) that generates |
150 |
keys, checks the config file and can control the daemon. |
151 |
|
152 |
@cindex Traditional VPNs |
153 |
@cindex scalability |
154 |
|
155 |
vpe also allows more than two sites to connect to eachother and form a |
156 |
single VPN. Traditionally VPNs are created by making tunnels, which only |
157 |
have two endpoints. Larger VPNs with more sites are created by adding |
158 |
more tunnels. vpe takes another approach: only endpoints are specified, |
159 |
the software itself will take care of creating the tunnels. This allows |
160 |
for easier configuration and improved scalability. |
161 |
|
162 |
@c ================================================================== |
163 |
@node Supported platforms, , vpe, Introduction |
164 |
@section Supported platforms |
165 |
|
166 |
@cindex platforms |
167 |
|
168 |
So far, vpe only owrks under Linux. Although the project it comes from, |
169 |
tincd, supports FreeBSD, OpenBSD and Solaris, the lowlevel capturing |
170 |
interface had to be rewritten, and due to lack of access to these |
171 |
platforms, support for them has been dropped, but could be added back |
172 |
relatively easily. |
173 |
|
174 |
@ignore |
175 |
@cindex release |
176 |
For an up to date list of supported platforms, please check the list on |
177 |
our website: |
178 |
@uref{http://tinc.nl.linux.org/platforms.html}. |
179 |
@end ignore |
180 |
|
181 |
|
182 |
@c ================================================================== |
183 |
@subsection Linux |
184 |
|
185 |
@cindex Linux vpe was first written for Linux running on an intel x86 |
186 |
processor, so this is the best supported platform. The protocol however, |
187 |
and actually anything about vpe, has been rewritten to support random byte |
188 |
ordering and arbitrary word length (with the exception of alignment issues |
189 |
within packets, so test this first ;). So in theory it should run on other |
190 |
processors that Linux runs on. |
191 |
|
192 |
@ignore |
193 |
@c ================================================================== |
194 |
@subsection FreeBSD |
195 |
|
196 |
@cindex FreeBSD |
197 |
vpe on FreeBSD relies on the universal tun/tap driver for its data |
198 |
acquisition from the kernel. Therefore, vpe will work on the same platforms |
199 |
as this driver. These are: FreeBSD 3.x, 4.x, 5.x. |
200 |
|
201 |
|
202 |
@c ================================================================== |
203 |
@subsection OpenBSD |
204 |
|
205 |
@cindex OpenBSD |
206 |
vpe on OpenBSD relies on the tun driver for its data |
207 |
acquisition from the kernel. It has been verified to work under at least OpenBSD 2.9. |
208 |
|
209 |
Tunneling IPv6 packets may not work on OpenBSD. |
210 |
|
211 |
|
212 |
@c ================================================================== |
213 |
@subsection Solaris |
214 |
|
215 |
@c ================================================================== |
216 |
@subsection NetBSD |
217 |
|
218 |
@cindex NetBSD |
219 |
vpe on NetBSD relies on the tun driver for its data |
220 |
acquisition from the kernel. It has been verified to work under at least NetBSD 1.5.2. |
221 |
|
222 |
Tunneling IPv6 does not work on OpenBSD. |
223 |
|
224 |
|
225 |
@c ================================================================== |
226 |
@subsection Solaris |
227 |
|
228 |
@cindex Solaris |
229 |
vpe on Solaris relies on the universal tun/tap driver for its data |
230 |
acquisition from the kernel. Therefore, vpe will work on the same platforms |
231 |
as this driver. These are: Solaris 8 (SunOS 5.8). |
232 |
|
233 |
IPv6 packets cannot be tunneled on Solaris. |
234 |
|
235 |
@c ================================================================== |
236 |
@subsection Darwin (MacOS/X) |
237 |
|
238 |
@cindex Darwin |
239 |
@cindex MacOS/X |
240 |
vpe on Darwin relies on the tunnel driver for its data |
241 |
acquisition from the kernel. This driver is not part of Darwin but can be |
242 |
downloaded from @uref{http://chrisp.de/en/projects/tunnel.html}. |
243 |
|
244 |
IPv6 packets cannot be tunneled on Darwin. |
245 |
|
246 |
@end ignore |
247 |
|
248 |
|
249 |
@c |
250 |
@c |
251 |
@c |
252 |
@c |
253 |
@c |
254 |
@c |
255 |
@c Preparing your system |
256 |
@c |
257 |
@c |
258 |
@c |
259 |
@c |
260 |
@c |
261 |
|
262 |
@c ================================================================== |
263 |
@node Preparations, Installation, Introduction, Top |
264 |
@chapter Preparations |
265 |
|
266 |
This chapter contains information on how to prepare your system to |
267 |
support vpe. |
268 |
|
269 |
@menu |
270 |
* Configuring the kernel:: |
271 |
* Libraries:: |
272 |
@end menu |
273 |
|
274 |
|
275 |
@c ================================================================== |
276 |
@node Configuring the kernel, Libraries, Preparations, Preparations |
277 |
@section Configuring the kernel |
278 |
|
279 |
@cindex RedHat |
280 |
@cindex Debian |
281 |
@cindex netlink_dev |
282 |
@cindex tun |
283 |
@cindex ethertap |
284 |
If you are running Linux, chances are good that your kernel already supports |
285 |
all the devices that vpe needs for proper operation. For example, the |
286 |
standard kernel from Redhat Linux already has support for ethertap and netlink |
287 |
compiled in. Debian users can use the modconf utility to select the modules. |
288 |
If your Linux distribution supports this method of selecting devices, look out |
289 |
for something called `ethertap', and `netlink_dev' if it is using a kernel |
290 |
version prior to 2.4.0. In that case you will need both these devices. If you |
291 |
are using kernel 2.4.0 or later, you need to select `tun'. |
292 |
|
293 |
@cindex Kernel-HOWTO |
294 |
If you can install these devices in a similar manner, you may skip this section. |
295 |
Otherwise, you will have to recompile the kernel in order to turn on the required features. |
296 |
If you are unfamiliar with the process of configuring and compiling a new kernel, |
297 |
you should read the @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html, Kernel HOWTO} first. |
298 |
|
299 |
@menu |
300 |
* Configuration of Linux kernels 2.4.0 and higher:: |
301 |
* Configuration of FreeBSD kernels:: |
302 |
* Configuration of OpenBSD kernels:: |
303 |
* Configuration of NetBSD kernels:: |
304 |
* Configuration of Solaris kernels:: |
305 |
* Configuration of Darwin (MacOS/X) kernels:: |
306 |
@end menu |
307 |
|
308 |
|
309 |
@c ================================================================== |
310 |
@node Configuration of Linux kernels 2.4.0 and higher, Configuration of FreeBSD kernels, Configuring the kernel, Configuring the kernel |
311 |
@subsection Configuration of Linux kernels 2.4.0 and higher |
312 |
|
313 |
Here are the options you have to turn on when configuring a new kernel: |
314 |
|
315 |
@example |
316 |
Code maturity level options |
317 |
[*] Prompt for development and/or incomplete code/drivers |
318 |
Network device support |
319 |
<M> Universal tun/tap device driver support |
320 |
@end example |
321 |
|
322 |
It's not necessary to compile this driver as a module, even if you are going to |
323 |
run more than one instance of vpe. |
324 |
|
325 |
If you have an early 2.4 kernel, you can choose both the tun/tap driver and the |
326 |
`Ethertap network tap' device. This latter is marked obsolete, and chances are |
327 |
that it won't even function correctly anymore. Make sure you select the |
328 |
universal tun/tap driver. |
329 |
|
330 |
If you decide to build the tun/tap driver as a kernel module, add these lines |
331 |
to @file{/etc/modules.conf}: |
332 |
|
333 |
@example |
334 |
alias char-major-10-200 tun |
335 |
@end example |
336 |
|
337 |
@c ================================================================== |
338 |
@node Configuration of FreeBSD kernels, Configuration of OpenBSD kernels, Configuration of Linux kernels 2.4.0 and higher, Configuring the kernel |
339 |
@subsection Configuration of FreeBSD kernels |
340 |
|
341 |
This section will contain information on how to configure your FreeBSD |
342 |
kernel to support the universal tun/tap device. For 4.1 and higher |
343 |
versions, this is included in the default kernel configuration, for earlier |
344 |
systems (4.0 and earlier), you need to install the universal tun/tap driver |
345 |
yourself. |
346 |
|
347 |
Unfortunately somebody still has to write the text. |
348 |
|
349 |
|
350 |
@c ================================================================== |
351 |
@node Configuration of OpenBSD kernels, Configuration of NetBSD kernels, Configuration of FreeBSD kernels, Configuring the kernel |
352 |
@subsection Configuration of OpenBSD kernels |
353 |
|
354 |
This section will contain information on how to configure your OpenBSD |
355 |
kernel to support the tun device. For 2.9 and 3.0 systems, |
356 |
this is included in the default kernel configuration. |
357 |
|
358 |
Unfortunately somebody still has to write the text. |
359 |
|
360 |
|
361 |
@c ================================================================== |
362 |
@node Configuration of NetBSD kernels, Configuration of Solaris kernels, Configuration of OpenBSD kernels, Configuring the kernel |
363 |
@subsection Configuration of NetBSD kernels |
364 |
|
365 |
This section will contain information on how to configure your NetBSD |
366 |
kernel to support the tun device. For 1.5.2 systems, |
367 |
this is included in the default kernel configuration. |
368 |
|
369 |
Unfortunately somebody still has to write the text. |
370 |
|
371 |
|
372 |
@c ================================================================== |
373 |
@node Configuration of Solaris kernels, Configuration of Darwin (MacOS/X) kernels, Configuration of NetBSD kernels, Configuring the kernel |
374 |
@subsection Configuration of Solaris kernels |
375 |
|
376 |
This section will contain information on how to configure your Solaris |
377 |
kernel to support the universal tun/tap device. For Solaris 8 (SunOS 5.8), |
378 |
this is included in the default kernel configuration. |
379 |
|
380 |
Unfortunately somebody still has to write the text. |
381 |
|
382 |
|
383 |
@c ================================================================== |
384 |
@node Configuration of Darwin (MacOS/X) kernels, , Configuration of Solaris kernels, Configuring the kernel |
385 |
@subsection Configuration of Darwin (MacOS/X) kernels |
386 |
|
387 |
Darwin does not come with a tunnel driver. You must download it at |
388 |
@uref{http://chrisp.de/en/projects/tunnel.html}. If compiling the source fails, |
389 |
try the binary module. The tunnel driver must be loaded before starting vpe |
390 |
with the following command: |
391 |
|
392 |
@example |
393 |
kmodload tunnel |
394 |
@end example |
395 |
|
396 |
Once loaded, the tunnel driver will automatically create @file{/dev/tun0}..@file{/dev/tun3} |
397 |
and the corresponding network interfaces. |
398 |
|
399 |
|
400 |
@c ================================================================== |
401 |
@node Libraries, , Configuring the kernel, Preparations |
402 |
@section Libraries |
403 |
|
404 |
@cindex requirements |
405 |
@cindex libraries |
406 |
|
407 |
Before you can configure or build vpe, you need to have the OpenSSL |
408 |
library installed on your system. If you try to configure vpe without |
409 |
having it installed, configure will give you an error message, and stop. |
410 |
|
411 |
@menu |
412 |
* OpenSSL:: |
413 |
@end menu |
414 |
|
415 |
|
416 |
@c ================================================================== |
417 |
@node OpenSSL, , Libraries, Libraries |
418 |
@subsection OpenSSL |
419 |
|
420 |
@cindex OpenSSL |
421 |
For all cryptography-related functions, vpe uses the functions provided |
422 |
by the OpenSSL library. |
423 |
|
424 |
If this library is not installed, you wil get an error when configuring |
425 |
vpe for build. Support for running vpe without having OpenSSL |
426 |
installed @emph{may} be added in the future. |
427 |
|
428 |
You can use your operating system's package manager to install this if |
429 |
available. Make sure you install the development AND runtime versions |
430 |
of this package. |
431 |
|
432 |
If you have to install OpenSSL manually, you can get the source code |
433 |
from @url{http://www.openssl.org/}. Instructions on how to configure, |
434 |
build and install this package are included within the package. Please |
435 |
make sure you build development and runtime libraries (which is the |
436 |
default). |
437 |
|
438 |
If you installed the OpenSSL libraries from source, it may be necessary |
439 |
to let configure know where they are, by passing configure one of the |
440 |
--with-openssl-* parameters. |
441 |
|
442 |
@example |
443 |
--with-openssl=DIR OpenSSL library and headers prefix |
444 |
--with-openssl-include=DIR OpenSSL headers directory |
445 |
(Default is OPENSSL_DIR/include) |
446 |
--with-openssl-lib=DIR OpenSSL library directory |
447 |
(Default is OPENSSL_DIR/lib) |
448 |
@end example |
449 |
|
450 |
@ignore |
451 |
@c |
452 |
@c |
453 |
@c WARNING: this is commented out because I didn't add this exception |
454 |
@c to my (vpe) code. |
455 |
@c |
456 |
@c |
457 |
@subsubheading License |
458 |
|
459 |
@cindex license |
460 |
Since the license under which OpenSSL is distributed is not directly |
461 |
compatible with the terms of the GNU GPL |
462 |
@uref{http://www.openssl.org/support/faq.html#LEGAL2}, therefore we |
463 |
include an addition to the GPL (see also the file COPYING.README): |
464 |
|
465 |
@quotation |
466 |
This program is released under the GPL with the additional exemption |
467 |
that compiling, linking, and/or using OpenSSL is allowed. You may |
468 |
provide binary packages linked to the OpenSSL libraries, provided that |
469 |
all other requirements of the GPL are met. |
470 |
@end quotation |
471 |
@end ignore |
472 |
|
473 |
|
474 |
@c |
475 |
@c |
476 |
@c |
477 |
@c Installing vpe |
478 |
@c |
479 |
@c |
480 |
@c |
481 |
@c |
482 |
|
483 |
@c ================================================================== |
484 |
@node Installation, Configuration, Preparations, Top |
485 |
@chapter Installation |
486 |
|
487 |
@ignore |
488 |
If you use Debian, you may want to install one of the |
489 |
precompiled packages for your system. These packages are equipped with |
490 |
system startup scripts and sample configurations. |
491 |
|
492 |
If you cannot use one of the precompiled packages, or you want to compile vpe |
493 |
for yourself, you can use the source. The source is distributed under |
494 |
the GNU General Public License (GPL). Download the source from the |
495 |
@uref{http://vpe.nl.linux.org/download.html, download page}, which has |
496 |
the checksums of these files listed; you may wish to check these with |
497 |
md5sum before continuing. |
498 |
@end ignore |
499 |
|
500 |
vpe comes in a convenient autoconf/automake package, which you can just |
501 |
treat the same as any other package. Which is just untar it, type |
502 |
`./configure' and then `make'. |
503 |
|
504 |
More detailed instructions are in the file @file{INSTALL}, which is |
505 |
included in the source distribution. |
506 |
|
507 |
@menu |
508 |
* Building and installing vpe:: |
509 |
* System files:: |
510 |
@end menu |
511 |
|
512 |
|
513 |
@c ================================================================== |
514 |
@node Building and installing vpe, System files, Installation, Installation |
515 |
@section Building and installing vpe |
516 |
|
517 |
Detailed instructions on configuring the source, building vpe and |
518 |
installing vpe can be found in the file called @file{INSTALL}. |
519 |
|
520 |
@c ================================================================== |
521 |
@node System files, , Building and installing vpe, Installation |
522 |
@section System files |
523 |
|
524 |
Before you can run vpe, you must make sure you have all the needed |
525 |
files on your system. |
526 |
|
527 |
@menu |
528 |
* Device files:: |
529 |
* Other files:: |
530 |
@end menu |
531 |
|
532 |
|
533 |
@c ================================================================== |
534 |
@node Device files, Other files, System files, System files |
535 |
@subsection Device files |
536 |
|
537 |
@cindex device files |
538 |
First, you'll need the special device file(s) that form the interface |
539 |
between the kernel and the daemon. |
540 |
|
541 |
The permissions for these files have to be such that only the super user |
542 |
may read/write to this file. You'd want this, because otherwise |
543 |
eavesdropping would become a bit too easy. This does, however, imply |
544 |
that you'd have to run vped as root. |
545 |
|
546 |
If you use Linux and have a kernel version prior to 2.4.0, you have to make the |
547 |
ethertap devices: |
548 |
|
549 |
@example |
550 |
mknod -m 600 /dev/tap0 c 36 16 |
551 |
mknod -m 600 /dev/tap1 c 36 17 |
552 |
... |
553 |
mknod -m 600 /dev/tap@emph{N} c 36 @emph{N+16} |
554 |
@end example |
555 |
|
556 |
There is a maximum of 16 ethertap devices. |
557 |
|
558 |
If you use the universal tun/tap driver, you have to create the |
559 |
following device file (unless it already exist): |
560 |
|
561 |
@example |
562 |
mknod -m 600 /dev/tun c 10 200 |
563 |
@end example |
564 |
|
565 |
If you use Linux, and you run the new 2.4 kernel using the devfs filesystem, |
566 |
then the tun/tap device will probably be automatically generated as |
567 |
@file{/dev/net/tun}. |
568 |
|
569 |
Unlike the ethertap device, you do not need multiple device files if |
570 |
you are planning to run multiple vpe daemons. |
571 |
|
572 |
|
573 |
@c ================================================================== |
574 |
@node Other files, , Device files, System files |
575 |
@subsection Other files |
576 |
|
577 |
@subsubheading @file{/etc/networks} |
578 |
|
579 |
You may add a line to @file{/etc/networks} so that your VPN will get a |
580 |
symbolic name. For example: |
581 |
|
582 |
@example |
583 |
myvpn 10.0.0.0 |
584 |
@end example |
585 |
|
586 |
@ignore |
587 |
@subsubheading @file{/etc/services} |
588 |
|
589 |
@cindex port numbers |
590 |
You may add this line to @file{/etc/services}. The effect is that you |
591 |
may supply a @samp{vpe} as a valid port number to some programs. The |
592 |
number 655 is registered with the IANA. |
593 |
|
594 |
@example |
595 |
vpe 655/tcp TINC |
596 |
vpe 655/udp TINC |
597 |
@end example |
598 |
@end ignore |
599 |
|
600 |
|
601 |
@c |
602 |
@c |
603 |
@c |
604 |
@c |
605 |
@c Configuring vpe |
606 |
@c |
607 |
@c |
608 |
@c |
609 |
@c |
610 |
|
611 |
|
612 |
@c ================================================================== |
613 |
@node Configuration, Running vpe, Installation, Top |
614 |
@chapter Configuration |
615 |
|
616 |
@menu |
617 |
* Configuration introduction:: |
618 |
* Multiple networks:: |
619 |
* How connections work:: |
620 |
* Configuration files:: |
621 |
* Generating keypairs:: |
622 |
* Network interfaces:: |
623 |
* Example configuration:: |
624 |
@end menu |
625 |
|
626 |
@c ================================================================== |
627 |
@node Configuration introduction, Multiple networks, Configuration, Configuration |
628 |
@section Configuration introduction |
629 |
|
630 |
@cindex Network Administrators Guide |
631 |
Before actually starting to configure vpe and editing files, |
632 |
make sure you have read this entire section so you know what to expect. |
633 |
Then, make it clear to yourself how you want to organize your VPN: |
634 |
What are the nodes (computers running vpe)? |
635 |
What IP addresses/subnets do they have? |
636 |
What is the network mask of the entire VPN? |
637 |
Do you need special firewall rules? |
638 |
Do you have to set up masquerading or forwarding rules? |
639 |
These questions can only be answered by yourself, |
640 |
you will not find the answers in this documentation. |
641 |
Make sure you have an adequate understanding of networks in general. |
642 |
A good resource on networking is the |
643 |
@uref{http://www.linuxdoc.org/LDP/nag2/, Linux Network Administrators Guide}. |
644 |
|
645 |
If you have everything clearly pictured in your mind, |
646 |
proceed in the following order: |
647 |
First, generate the configuration files (@file{vpe.conf}, your host configuration file, @file{vpe-up} and perhaps @file{vpe-down}). |
648 |
Then generate the keypairs. |
649 |
Finally, distribute the host configuration files. |
650 |
These steps are described in the subsections below. |
651 |
|
652 |
|
653 |
@c ================================================================== |
654 |
@node Multiple networks, How connections work, Configuration introduction, Configuration |
655 |
@section Multiple networks |
656 |
|
657 |
@cindex multiple networks |
658 |
@cindex netname |
659 |
In order to allow you to run more than one vpe daemon on one computer, |
660 |
for instance if your computer is part of more than one VPN, |
661 |
you can assign a ``netname'' to your VPN. |
662 |
It is not required if you only run one vpe daemon, |
663 |
it doesn't even have to be the same on all the sites of your VPN, |
664 |
but it is recommended that you choose one anyway. |
665 |
|
666 |
We will asume you use a netname throughout this document. |
667 |
This means that you call vped with the -n argument, |
668 |
which will assign a netname to this daemon. |
669 |
|
670 |
The effect of this is that the daemon will set its configuration |
671 |
``root'' to /etc/vpe/netname/, where netname is your argument to the -n |
672 |
option. You'll notice that it appears in syslog as ``vpe.netname''. |
673 |
|
674 |
However, it is not strictly necessary that you call vpe with the -n |
675 |
option. In this case, the network name would just be empty, and it will |
676 |
be used as such. vpe now looks for files in /etc/vpe/, instead of |
677 |
/etc/vpe/netname/; the configuration file should be /etc/vpe/vpe.conf, |
678 |
and the host configuration files are now expected to be in /etc/vpe/hosts/. |
679 |
|
680 |
But it is highly recommended that you use this feature of vpe, because |
681 |
it will be so much clearer whom your daemon talks to. Hence, we will |
682 |
assume that you use it. |
683 |
|
684 |
|
685 |
@c ================================================================== |
686 |
@node How connections work, Configuration files, Multiple networks, Configuration |
687 |
@section How connections work |
688 |
|
689 |
When vpe starts up, it parses the command-line options and then |
690 |
reads in the configuration file vpe.conf. |
691 |
If it sees one or more `ConnectTo' values pointing to other vpe daemons in that file, |
692 |
it will try to connect to those other daemons. |
693 |
Whether this succeeds or not and whether `ConnectTo' is specified or not, |
694 |
vpe will listen for incoming connection from other deamons. |
695 |
If you did specify a `ConnectTo' value and the other side is not responding, |
696 |
vpe will keep retrying. |
697 |
This means that once started, vpe will stay running until you tell it to stop, |
698 |
and failures to connect to other vpe daemons will not stop your vpe daemon |
699 |
for trying again later. |
700 |
This means you don't have to intervene if there are temporary network problems. |
701 |
|
702 |
@cindex client |
703 |
@cindex server |
704 |
There is no real disvpetion between a server and a client in vpe. |
705 |
If you wish, you can view a vpe daemon without a `ConnectTo' value as a server, |
706 |
and one which does specify such a value as a client. |
707 |
It does not matter if two vpe daemons have a `ConnectTo' value pointing to each other however. |
708 |
|
709 |
|
710 |
@c ================================================================== |
711 |
@node Configuration files, Generating keypairs, How connections work, Configuration |
712 |
@section Configuration files |
713 |
|
714 |
The actual configuration of the daemon is done in the file |
715 |
@file{/etc/vpe/netname/vpe.conf} and at least one other file in the directory |
716 |
@file{/etc/vpe/netname/hosts/}. |
717 |
|
718 |
These file consists of comments (lines started with a #) or assignments |
719 |
in the form of |
720 |
|
721 |
@example |
722 |
Variable = Value. |
723 |
@end example |
724 |
|
725 |
The variable names are case insensitive, and any spaces, tabs, newlines |
726 |
and carriage returns are ignored. Note: it is not required that you put |
727 |
in the `=' sign, but doing so improves readability. If you leave it |
728 |
out, remember to replace it with at least one space character. |
729 |
|
730 |
In this section all valid variables are listed in alphabetical order. |
731 |
The default value is given between parentheses, |
732 |
other comments are between square brackets and |
733 |
required directives are given in @strong{bold}. |
734 |
|
735 |
@menu |
736 |
* Main configuration variables:: |
737 |
* Host configuration variables:: |
738 |
* How to configure:: |
739 |
@end menu |
740 |
|
741 |
|
742 |
@c ================================================================== |
743 |
@node Main configuration variables, Host configuration variables, Configuration files, Configuration files |
744 |
@subsection Main configuration variables |
745 |
|
746 |
@table @asis |
747 |
@cindex AddressFamily |
748 |
@item AddressFamily = <ipv4|ipv6|any> (ipv4) [experimental] |
749 |
This option affects the address family of listening and outgoing sockets. |
750 |
If "any" is selected, then depending on the operating system |
751 |
both IPv4 and IPv6 or just IPv6 listening sockets will be created. |
752 |
|
753 |
@cindex BindToInterface |
754 |
@item BindToInterface = <interface> [experimental] |
755 |
If you have more than one network interface in your computer, vpe will |
756 |
by default listen on all of them for incoming connections. It is |
757 |
possible to bind vpe to a single interface like eth0 or ppp0 with this |
758 |
variable. |
759 |
|
760 |
This option may not work on all platforms. |
761 |
|
762 |
@cindex ConnectTo |
763 |
@item @strong{ConnectTo = <name>} |
764 |
Specifies which other vpe daemon to connect to on startup. |
765 |
Multiple ConnectTo variables may be specified, |
766 |
in which case outgoing connections to each specified vpe daemon are made. |
767 |
The names should be known to this vpe daemon |
768 |
(i.e., there should be a host configuration file for the name on the ConnectTo line). |
769 |
|
770 |
If you don't specify a host with ConnectTo, |
771 |
vpe won't try to connect to other daemons at all, |
772 |
and will instead just listen for incoming connections. |
773 |
|
774 |
@cindex Device |
775 |
@item @strong{Device = <device>} (/dev/tap0 or /dev/net/tun) |
776 |
The virtual network device to use. Note that you can only use one device per |
777 |
daemon. See also @ref{Device files}. |
778 |
|
779 |
@cindex Hostnames |
780 |
@item Hostnames = <yes|no> (no) |
781 |
This option selects whether IP addresses (both real and on the VPN) |
782 |
should be resolved. Since DNS lookups are blocking, it might affect |
783 |
vpe's efficiency, even stopping the daemon for a few seconds everytime |
784 |
it does a lookup if your DNS server is not responding. |
785 |
|
786 |
This does not affect resolving hostnames to IP addresses from the |
787 |
configuration file. |
788 |
|
789 |
@cindex Interface |
790 |
@item Interface = <interface> |
791 |
Defines the name of the interface corresponding to the virtual network device. |
792 |
Depending on the operating system and the type of device this may or may not actually set the name. |
793 |
Currently this option only affects the Linux tun/tap device. |
794 |
|
795 |
@cindex Mode |
796 |
@item Mode = <router|switch|hub> (router) |
797 |
This option selects the way packets are routed to other daemons. |
798 |
|
799 |
@table @asis |
800 |
@cindex router |
801 |
@item router |
802 |
In this mode Subnet |
803 |
variables in the host configuration files will be used to form a routing table. |
804 |
Only unicast packets of routable protocols (IPv4 and IPv6) are supported in this mode. |
805 |
|
806 |
@cindex switch |
807 |
@item switch |
808 |
In this mode the MAC addresses of the packets on the VPN will be used to |
809 |
dynamically create a routing table just like an Ethernet switch does. |
810 |
Unicast, multicast and broadcast packets of every protocol that runs over Ethernet are supported in this mode |
811 |
at the cost of frequent broadcast ARP requests and routing table updates. |
812 |
|
813 |
@cindex hub |
814 |
@item hub |
815 |
This mode is almost the same as the switch mode, but instead |
816 |
every packet will be broadcast to the other daemons |
817 |
while no routing table is managed. |
818 |
@end table |
819 |
|
820 |
@cindex KeyExpire |
821 |
@item KeyExpire = <seconds> (3600) |
822 |
This option controls the time the encryption keys used to encrypt the data |
823 |
are valid. It is common practice to change keys at regular intervals to |
824 |
make it even harder for crackers, even though it is thought to be nearly |
825 |
impossible to crack a single key. |
826 |
|
827 |
@cindex MACExpire |
828 |
@item MACExpire = <seconds> (600) |
829 |
This option controls the amount of time MAC addresses are kept before they are removed. |
830 |
This only has effect when Mode is set to "switch". |
831 |
|
832 |
@cindex Name |
833 |
@item @strong{Name = <name>} |
834 |
This is a symbolic name for this connection. It can be anything |
835 |
|
836 |
@cindex PingTimeout |
837 |
@item PingTimeout = <seconds> (60) |
838 |
The number of seconds of inactivity that vpe will wait before sending a |
839 |
probe to the other end. If that other end doesn't answer within that |
840 |
same amount of seconds, the connection is terminated, and the others |
841 |
will be notified of this. |
842 |
|
843 |
@cindex PriorityInheritance |
844 |
@item PriorityInheritance = <yes|no> (no) [experimental] |
845 |
When this option is enabled the value of the TOS field of tunneled IPv4 packets |
846 |
will be inherited by the UDP packets that are sent out. |
847 |
|
848 |
@cindex PrivateKey |
849 |
@item PrivateKey = <key> [obsolete] |
850 |
This is the RSA private key for vpe. However, for safety reasons it is |
851 |
advised to store private keys of any kind in separate files. This prevents |
852 |
accidental eavesdropping if you are editting the configuration file. |
853 |
|
854 |
@cindex PrivateKeyFile |
855 |
@item @strong{PrivateKeyFile = <path>} [recommended] |
856 |
This is the full path name of the RSA private key file that was |
857 |
generated by ``vped --generate-keys''. It must be a full path, not a |
858 |
relative directory. |
859 |
|
860 |
Note that there must be exactly one of PrivateKey |
861 |
or PrivateKeyFile |
862 |
specified in the configuration file. |
863 |
|
864 |
@end table |
865 |
|
866 |
|
867 |
@c ================================================================== |
868 |
@node Host configuration variables, How to configure, Main configuration variables, Configuration files |
869 |
@subsection Host configuration variables |
870 |
|
871 |
@table @asis |
872 |
@cindex Address |
873 |
@item @strong{Address = <IP address|hostname>} [recommended] |
874 |
This variable is only required if you want to connect to this host. It |
875 |
must resolve to the external IP address where the host can be reached, |
876 |
not the one that is internal to the VPN. |
877 |
|
878 |
@cindex Cipher |
879 |
@item Cipher = <cipher> (blowfish) |
880 |
The symmetric cipher algorithm used to encrypt UDP packets. |
881 |
Any cipher supported by OpenSSL is recognized. |
882 |
|
883 |
@cindex Compression |
884 |
@item Compression = <level> (0) |
885 |
This option sets the level of compression used for UDP packets. |
886 |
Possible values are 0 (off), 1 (fast) and any integer up to 9 (best). |
887 |
|
888 |
@cindex Digest |
889 |
@item Digest = <digest> (sha1) |
890 |
The digest algorithm used to authenticate UDP packets. |
891 |
Any digest supported by OpenSSL is recognized. |
892 |
Furthermore, specifying "none" will turn off packet authentication. |
893 |
|
894 |
@cindex IndirectData |
895 |
@item IndirectData = <yes|no> (no) |
896 |
This option specifies whether other vpe daemons besides the one you |
897 |
specified with ConnectTo can make a direct connection to you. This is |
898 |
especially useful if you are behind a firewall and it is impossible to |
899 |
make a connection from the outside to your vpe daemon. Otherwise, it |
900 |
is best to leave this option out or set it to no. |
901 |
|
902 |
@cindex MACLength |
903 |
@item MACLength = <length> (4) |
904 |
The length of the message authentication code used to authenticate UDP packets. |
905 |
Can be anything from 0 |
906 |
up to the length of the digest produced by the digest algorithm. |
907 |
|
908 |
@cindex Port |
909 |
@item Port = <port> (655) |
910 |
This is the port this vpe daemon listens on. |
911 |
You can use decimal portnumbers or symbolic names (as listed in /etc/services). |
912 |
|
913 |
@cindex PublicKey |
914 |
@item PublicKey = <key> [obsolete] |
915 |
This is the RSA public key for this host. |
916 |
|
917 |
@cindex PublicKeyFile |
918 |
@item PublicKeyFile = <path> [obsolete] |
919 |
This is the full path name of the RSA public key file that was generated |
920 |
by ``vped --generate-keys''. It must be a full path, not a relative |
921 |
directory. |
922 |
|
923 |
@cindex PEM format |
924 |
From version 1.0pre4 on vpe will store the public key directly into the |
925 |
host configuration file in PEM format, the above two options then are not |
926 |
necessary. Either the PEM format is used, or exactly |
927 |
@strong{one of the above two options} must be specified |
928 |
in each host configuration file, if you want to be able to establish a |
929 |
connection with that host. |
930 |
|
931 |
@cindex Subnet |
932 |
@item Subnet = <address[/prefixlength]> |
933 |
The subnet which this vpe daemon will serve. |
934 |
vpe tries to look up which other daemon it should send a packet to by searching the appropiate subnet. |
935 |
If the packet matches a subnet, |
936 |
it will be sent to the daemon who has this subnet in his host configuration file. |
937 |
Multiple subnet lines can be specified for each daemon. |
938 |
|
939 |
Subnets can either be single MAC, IPv4 or IPv6 addresses, |
940 |
in which case a subnet consisting of only that single address is assumed, |
941 |
or they can be a IPv4 or IPv6 network address with a prefixlength. |
942 |
Shorthand notations are not supported. |
943 |
For example, IPv4 subnets must be in a form like 192.168.1.0/24, |
944 |
where 192.168.1.0 is the network address and 24 is the number of bits set in the netmask. |
945 |
Note that subnets like 192.168.1.1/24 are invalid! |
946 |
Read a networking HOWTO/FAQ/guide if you don't understand this. |
947 |
IPv6 subnets are notated like fec0:0:0:1:0:0:0:0/64. |
948 |
MAC addresses are notated like 0:1a:2b:3c:4d:5e. |
949 |
|
950 |
@cindex CIDR notation |
951 |
prefixlength is the number of bits set to 1 in the netmask part; for |
952 |
example: netmask 255.255.255.0 would become /24, 255.255.252.0 becomes |
953 |
/22. This conforms to standard CIDR notation as described in |
954 |
@uref{ftp://ftp.isi.edu/in-notes/rfc1519.txt, RFC1519} |
955 |
|
956 |
@cindex TCPonly |
957 |
@item TCPonly = <yes|no> (no) [experimental] |
958 |
If this variable is set to yes, then the packets are tunnelled over a |
959 |
TCP connection instead of a UDP connection. This is especially useful |
960 |
for those who want to run a vpe daemon from behind a masquerading |
961 |
firewall, or if UDP packet routing is disabled somehow. |
962 |
Setting this options also implicitly sets IndirectData. |
963 |
@end table |
964 |
|
965 |
|
966 |
@c ================================================================== |
967 |
@node How to configure, , Host configuration variables, Configuration files |
968 |
@subsection How to configure |
969 |
|
970 |
@subsubheading Step 1. Creating the main configuration file |
971 |
|
972 |
The main configuration file will be called @file{/etc/vpe/netname/vpe.conf}. |
973 |
Adapt the following example to create a basic configuration file: |
974 |
|
975 |
@example |
976 |
Name = @emph{yourname} |
977 |
Device = @emph{/dev/tap0} |
978 |
PrivateKeyFile = /etc/vpe/@emph{netname}/rsa_key.priv |
979 |
@end example |
980 |
|
981 |
Then, if you know to which other vpe daemon(s) yours is going to connect, |
982 |
add `ConnectTo' values. |
983 |
|
984 |
@subsubheading Step 2. Creating your host configuration file |
985 |
|
986 |
If you added a line containing `Name = yourname' in the main configuarion file, |
987 |
you will need to create a host configuration file @file{/etc/vpe/netname/hosts/yourname}. |
988 |
Adapt the following example to create a host configuration file: |
989 |
|
990 |
@example |
991 |
Address = @emph{your.real.hostname.org} |
992 |
Subnet = @emph{192.168.1.0/24} |
993 |
@end example |
994 |
|
995 |
You can also use an IP address instead of a hostname. |
996 |
The `Subnet' specifies the address range that is local for @emph{your part of the VPN only}. |
997 |
If you have multiple address ranges you can specify more than one `Subnet'. |
998 |
You might also need to add a `Port' if you want your vpe daemon to run on a different port number than the default (655). |
999 |
|
1000 |
|
1001 |
@c ================================================================== |
1002 |
@node Generating keypairs, Network interfaces, Configuration files, Configuration |
1003 |
@section Generating keypairs |
1004 |
|
1005 |
@cindex key generation |
1006 |
Now that you have already created the main configuration file and your host configuration file, |
1007 |
you can easily create a public/private keypair by entering the following command: |
1008 |
|
1009 |
@example |
1010 |
vped -n @emph{netname} -K |
1011 |
@end example |
1012 |
|
1013 |
vpe will generate a public and a private key and ask you where to put them. |
1014 |
Just press enter to accept the defaults. |
1015 |
|
1016 |
|
1017 |
@c ================================================================== |
1018 |
@node Network interfaces, Example configuration, Generating keypairs, Configuration |
1019 |
@section Network interfaces |
1020 |
|
1021 |
Before vpe can start transmitting data over the tunnel, it must |
1022 |
set up the virtual network interface. |
1023 |
|
1024 |
First, decide which IP addresses you want to have associated with these |
1025 |
devices, and what network mask they must have. |
1026 |
|
1027 |
vpe will open a virtual network device (@file{/dev/tun}, @file{/dev/tap0} or similar), |
1028 |
which will also create a network interface called something like `tun0', `tap0', or, |
1029 |
if you are using the Linux tun/tap driver, the network interface will by default have the same name as the netname. |
1030 |
|
1031 |
@cindex vpe-up |
1032 |
You can configure the network interface by putting ordinary ifconfig, route, and other commands |
1033 |
to a script named @file{/etc/vpe/netname/vpe-up}. When vpe starts, this script |
1034 |
will be executed. When vpe exits, it will execute the script named |
1035 |
@file{/etc/vpe/netname/vpe-down}, but normally you don't need to create that script. |
1036 |
|
1037 |
An example @file{vpe-up} script: |
1038 |
|
1039 |
@example |
1040 |
#!/bin/sh |
1041 |
ifconfig $INTERFACE hw ether fe:fd:0:0:0:0 |
1042 |
ifconfig $INTERFACE 192.168.1.1 netmask 255.255.0.0 |
1043 |
ifconfig $INTERFACE -arp |
1044 |
@end example |
1045 |
|
1046 |
@cindex MAC address |
1047 |
@cindex hardware address |
1048 |
The first line sets up the MAC address of the network interface. |
1049 |
Due to the nature of how Ethernet and vpe work, it has to be set to fe:fd:0:0:0:0 |
1050 |
for vpe to work in it's normal mode. |
1051 |
If you configured vpe to work in `switch' or `hub' mode, the hardware address should instead |
1052 |
be set to a unique address instead of fe:fd:0:0:0:0. |
1053 |
|
1054 |
You can use the environment variable $INTERFACE to get the name of the interface. |
1055 |
However, this might not be reliable. If in doubt, use the name of the interface explicitly. |
1056 |
|
1057 |
@cindex ifconfig |
1058 |
The next line gives the interface an IP address and a netmask. |
1059 |
The kernel will also automatically add a route to this interface, so normally you don't need |
1060 |
to add route commands to the @file{vpe-up} script. |
1061 |
The kernel will also bring the interface up after this command. |
1062 |
@cindex netmask |
1063 |
The netmask is the mask of the @emph{entire} VPN network, not just your |
1064 |
own subnet. |
1065 |
|
1066 |
@cindex arp |
1067 |
The last line tells the kernel not to use ARP on that interface. |
1068 |
Again this has to do with how Ethernet and vpe work. |
1069 |
Use this option only if you are running vpe under Linux and are using vpe's normal routing mode. |
1070 |
|
1071 |
|
1072 |
@c ================================================================== |
1073 |
@node Example configuration, , Network interfaces, Configuration |
1074 |
@section Example configuration |
1075 |
|
1076 |
|
1077 |
@cindex example |
1078 |
Imagine the following situation. Branch A of our example `company' wants to connect |
1079 |
three branch offices in B, C and D using the Internet. All four offices |
1080 |
have a 24/7 connection to the Internet. |
1081 |
|
1082 |
A is going to serve as the center of the network. B and C will connect |
1083 |
to A, and D will connect to C. Each office will be assigned their own IP |
1084 |
network, 10.x.0.0. |
1085 |
|
1086 |
@example |
1087 |
A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4 |
1088 |
B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5 |
1089 |
C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6 |
1090 |
D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7 |
1091 |
@end example |
1092 |
|
1093 |
``gateway'' is the VPN IP address of the machine that is running the |
1094 |
vped. ``internet IP'' is the IP address of the firewall, which does not |
1095 |
need to run vped, but it must do a port forwarding of TCP&UDP on port |
1096 |
655 (unless otherwise configured). |
1097 |
|
1098 |
In this example, it is assumed that eth0 is the interface that points to |
1099 |
the inner (physical) LAN of the office, although this could also be the |
1100 |
same as the interface that leads to the Internet. The configuration of |
1101 |
the real interface is also shown as a comment, to give you an idea of |
1102 |
how these example host is set up. All branches use the netname `company' |
1103 |
for this particular VPN. |
1104 |
|
1105 |
@subsubheading For Branch A |
1106 |
|
1107 |
@emph{BranchA} would be configured like this: |
1108 |
|
1109 |
In @file{/etc/vpe/company/vpe-up}: |
1110 |
|
1111 |
@example |
1112 |
# Real interface of internal network: |
1113 |
# ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255 |
1114 |
|
1115 |
ifconfig tap0 hw ether fe:fd:0:0:0:0 |
1116 |
ifconfig tap0 10.1.54.1 netmask 255.0.0.0 |
1117 |
ifconfig tap0 -arp |
1118 |
@end example |
1119 |
|
1120 |
and in @file{/etc/vpe/company/vpe.conf}: |
1121 |
|
1122 |
@example |
1123 |
Name = BranchA |
1124 |
PrivateKey = /etc/vpe/company/rsa_key.priv |
1125 |
Device = /dev/tap0 |
1126 |
@end example |
1127 |
|
1128 |
On all hosts, /etc/vpe/company/hosts/BranchA contains: |
1129 |
|
1130 |
@example |
1131 |
Subnet = 10.1.0.0/16 |
1132 |
Address = 1.2.3.4 |
1133 |
|
1134 |
Note that the IP addresses of eth0 and tap0 are the same. |
1135 |
This is quite possible, if you make sure that the netmasks of the interfaces are different. |
1136 |
It is in fact recommended to give give both real internal network interfaces and tap interfaces the same IP address, |
1137 |
since that will make things a lot easier to remember and set up. |
1138 |
|
1139 |
-----BEGIN RSA PUBLIC KEY----- |
1140 |
... |
1141 |
-----END RSA PUBLIC KEY----- |
1142 |
@end example |
1143 |
|
1144 |
|
1145 |
@subsubheading For Branch B |
1146 |
|
1147 |
In @file{/etc/vpe/company/vpe-up}: |
1148 |
|
1149 |
@example |
1150 |
# Real interface of internal network: |
1151 |
# ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255 |
1152 |
|
1153 |
ifconfig tap0 hw ether fe:fd:0:0:0:0 |
1154 |
ifconfig tap0 10.2.1.12 netmask 255.0.0.0 |
1155 |
ifconfig tap0 -arp |
1156 |
@end example |
1157 |
|
1158 |
and in @file{/etc/vpe/company/vpe.conf}: |
1159 |
|
1160 |
@example |
1161 |
Name = BranchB |
1162 |
ConnectTo = BranchA |
1163 |
PrivateKey = /etc/vpe/company/rsa_key.priv |
1164 |
@end example |
1165 |
|
1166 |
Note here that the internal address (on eth0) doesn't have to be the |
1167 |
same as on the tap0 device. Also, ConnectTo is given so that no-one can |
1168 |
connect to this node. |
1169 |
|
1170 |
On all hosts, in @file{/etc/vpe/company/hosts/BranchB}: |
1171 |
|
1172 |
@example |
1173 |
Subnet = 10.2.0.0/16 |
1174 |
Address = 2.3.4.5 |
1175 |
|
1176 |
-----BEGIN RSA PUBLIC KEY----- |
1177 |
... |
1178 |
-----END RSA PUBLIC KEY----- |
1179 |
@end example |
1180 |
|
1181 |
|
1182 |
@subsubheading For Branch C |
1183 |
|
1184 |
In @file{/etc/vpe/company/vpe-up}: |
1185 |
|
1186 |
@example |
1187 |
# Real interface of internal network: |
1188 |
# ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255 |
1189 |
|
1190 |
ifconfig tap1 hw ether fe:fd:0:0:0:0 |
1191 |
ifconfig tap1 10.3.69.254 netmask 255.0.0.0 |
1192 |
ifconfig tap1 -arp |
1193 |
@end example |
1194 |
|
1195 |
and in @file{/etc/vpe/company/vpe.conf}: |
1196 |
|
1197 |
@example |
1198 |
Name = BranchC |
1199 |
ConnectTo = BranchA |
1200 |
Device = /dev/tap1 |
1201 |
@end example |
1202 |
|
1203 |
C already has another daemon that runs on port 655, so they have to |
1204 |
reserve another port for vpe. It knows the portnumber it has to listen on |
1205 |
from it's own host configuration file. |
1206 |
|
1207 |
On all hosts, in @file{/etc/vpe/company/hosts/BranchC}: |
1208 |
|
1209 |
@example |
1210 |
Address = 3.4.5.6 |
1211 |
Subnet = 10.3.0.0/16 |
1212 |
Port = 2000 |
1213 |
|
1214 |
-----BEGIN RSA PUBLIC KEY----- |
1215 |
... |
1216 |
-----END RSA PUBLIC KEY----- |
1217 |
@end example |
1218 |
|
1219 |
|
1220 |
@subsubheading For Branch D |
1221 |
|
1222 |
In @file{/etc/vpe/company/vpe-up}: |
1223 |
|
1224 |
@example |
1225 |
# Real interface of internal network: |
1226 |
# ifconfig eth0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255 |
1227 |
|
1228 |
ifconfig company hw ether fe:fd:0:0:0:0 |
1229 |
ifconfig company 10.4.3.32 netmask 255.0.0.0 |
1230 |
ifconfig company -arp |
1231 |
@end example |
1232 |
|
1233 |
and in @file{/etc/vpe/company/vpe.conf}: |
1234 |
|
1235 |
@example |
1236 |
Name = BranchD |
1237 |
ConnectTo = BranchC |
1238 |
Device = /dev/net/tun |
1239 |
PrivateKeyFile = /etc/vpe/company/rsa_key.priv |
1240 |
@end example |
1241 |
|
1242 |
D will be connecting to C, which has a vped running for this network on |
1243 |
port 2000. It knows the port number from the host configuration file. |
1244 |
Also note that since D uses the tun/tap driver, the network interface |
1245 |
will not be called `tun' or `tap0' or something like that, but will |
1246 |
have the same name as netname. |
1247 |
|
1248 |
On all hosts, in @file{/etc/vpe/company/hosts/BranchD}: |
1249 |
|
1250 |
@example |
1251 |
Subnet = 10.4.0.0/16 |
1252 |
Address = 4.5.6.7 |
1253 |
|
1254 |
-----BEGIN RSA PUBLIC KEY----- |
1255 |
... |
1256 |
-----END RSA PUBLIC KEY----- |
1257 |
@end example |
1258 |
|
1259 |
@subsubheading Key files |
1260 |
|
1261 |
A, B, C and D all have generated a public/private keypair with the following command: |
1262 |
|
1263 |
@example |
1264 |
vped -n company -K |
1265 |
@end example |
1266 |
|
1267 |
The private key is stored in @file{/etc/vpe/company/rsa_key.priv}, |
1268 |
the public key is put into the host configuration file in the @file{/etc/vpe/company/hosts/} directory. |
1269 |
During key generation, vpe automatically guesses the right filenames based on the -n option and |
1270 |
the Name directive in the @file{vpe.conf} file (if it is available). |
1271 |
|
1272 |
@subsubheading Starting |
1273 |
|
1274 |
After each branch has finished configuration and they have distributed |
1275 |
the host configuration files amongst them, they can start their vpe daemons. |
1276 |
They don't necessarily have to wait for the other branches to have started |
1277 |
their daemons, vpe will try connecting until they are available. |
1278 |
|
1279 |
|
1280 |
@c ================================================================== |
1281 |
@node Running vpe, Technical information, Configuration, Top |
1282 |
@chapter Running vpe |
1283 |
|
1284 |
If everything else is done, you can start vpe by typing the following command: |
1285 |
|
1286 |
@example |
1287 |
vped -n @emph{netname} |
1288 |
@end example |
1289 |
|
1290 |
@cindex daemon |
1291 |
vpe will detach from the terminal and continue to run in the background like a good daemon. |
1292 |
If there are any problems however you can try to increase the debug level |
1293 |
and look in the syslog to find out what the problems are. |
1294 |
|
1295 |
@menu |
1296 |
* Runtime options:: |
1297 |
* Error messages:: |
1298 |
@end menu |
1299 |
|
1300 |
|
1301 |
@c ================================================================== |
1302 |
@node Runtime options, Error messages, , Running vpe |
1303 |
@section Runtime options |
1304 |
|
1305 |
Besides the settings in the configuration file, vpe also accepts some |
1306 |
command line options. |
1307 |
|
1308 |
@cindex command line |
1309 |
@cindex runtime options |
1310 |
@cindex options |
1311 |
@c from the manpage |
1312 |
@table @samp |
1313 |
@item --bypass-security |
1314 |
Disables encryption and authentication. |
1315 |
Only useful for debugging. |
1316 |
|
1317 |
@item -c, --config=PATH |
1318 |
Read configuration options from the directory PATH. The default is |
1319 |
@file{/etc/vpe/netname/}. |
1320 |
|
1321 |
@cindex debug level |
1322 |
@item -d, --debug=LEVEL |
1323 |
Set debug level to LEVEL. The higher the debug level, the more gets |
1324 |
logged. Everything goes via syslog. |
1325 |
|
1326 |
@item -K, --generate-keys[=BITS] |
1327 |
Generate public/private keypair of BITS length. If BITS is not specified, |
1328 |
1024 is the default. vpe will ask where you want to store the files, |
1329 |
but will default to the configuration directory (you can use the -c or -n option |
1330 |
in combination with -K). After that, vpe will quit. |
1331 |
|
1332 |
@item --help |
1333 |
Display a short reminder of these runtime options and terminate. |
1334 |
|
1335 |
@item -k, --kill[=SIGNAL] |
1336 |
Attempt to kill a running vped (optionally with the specified SIGNAL instead of SIGTERM) and exit. |
1337 |
Use it in conjunction with the -n option to make sure you kill the right vpe daemon. |
1338 |
|
1339 |
@item -n, --net=NETNAME |
1340 |
Connect to net NETNAME. @xref{Multiple networks}. |
1341 |
|
1342 |
@item -D, --no-detach |
1343 |
Don't fork and detach. |
1344 |
This will also disable the automatic restart mechanism for fatal errors. |
1345 |
|
1346 |
@item -L, --mlock |
1347 |
Lock vpe into main memory. |
1348 |
This will prevent sensitive data like shared private keys to be written to the system swap files/partitions. |
1349 |
|
1350 |
@item --version |
1351 |
Output version information and exit. |
1352 |
|
1353 |
@end table |
1354 |
|
1355 |
|
1356 |
@c ================================================================== |
1357 |
@node Error messages, , Runtime options, Running vpe |
1358 |
@section Error messages |
1359 |
|
1360 |
What follows is a list of the most common error messages you can see |
1361 |
when configuring vpe. Most of these messages are visible in the syslog |
1362 |
only, so keep an eye on it! |
1363 |
|
1364 |
@table @strong |
1365 |
@item Could not open /dev/tap0: No such device |
1366 |
|
1367 |
@itemize |
1368 |
@item You forgot to `modprobe netlink_dev' or `modprobe ethertap'. |
1369 |
@item You forgot to compile `Netlink device emulation' in the kernel. |
1370 |
@end itemize |
1371 |
|
1372 |
@item Can't write to /dev/net/tun: No such device |
1373 |
|
1374 |
@itemize |
1375 |
@item You forgot to `modprobe tun'. |
1376 |
@item You forgot to compile `Universal TUN/TAP driver' in the kernel. |
1377 |
@end itemize |
1378 |
|
1379 |
@item Packet with destination 1.2.3.4 is looping back to us! |
1380 |
|
1381 |
@itemize |
1382 |
@item Something is not configured right. Packets are being sent out to the |
1383 |
virtual network device, but according to the Subnet directives in your host configuration |
1384 |
file, those packets should go to your own host. Most common mistake is that |
1385 |
you have a Subnet line in your host configuration file with a prefix length which is |
1386 |
just as large as the prefix of the virtual network interface. The latter should in almost all |
1387 |
cases be larger. Rethink your configuration. |
1388 |
Note that you will only see this message if you specified a debug |
1389 |
level of 5 or higher! |
1390 |
@item Chances are that a `Subnet = ...' line in the host configuration file of this vpe daemon is wrong. |
1391 |
Change it to a subnet that is accepted locally by another interface, |
1392 |
or if that is not the case, try changing the prefix length into /32. |
1393 |
@end itemize |
1394 |
|
1395 |
@item Network doesn't work, syslog shows only packets of length 46 |
1396 |
|
1397 |
@item Network address and prefix length do not match! |
1398 |
|
1399 |
@itemize |
1400 |
@item The Subnet field must contain a @emph{network} address. |
1401 |
@item If you only want to use one IP address, set the netmask to /32. |
1402 |
@end itemize |
1403 |
|
1404 |
@item This is a bug: net.c:253: 24: Some error |
1405 |
|
1406 |
@itemize |
1407 |
@item This is something that should not have happened. |
1408 |
Please report this, and tell us exactly what went wrong before you got |
1409 |
this message. In normal operation, these errors should not occur. |
1410 |
@end itemize |
1411 |
|
1412 |
@item Error reading RSA key file `rsa_key.priv': No such file or directory |
1413 |
|
1414 |
@itemize |
1415 |
@item You must specify the complete pathname. |
1416 |
Specifying a relative path does not make sense here. vpe changes its |
1417 |
directory to / when starting (to avoid keeping a mount point busy). |
1418 |
@end itemize |
1419 |
|
1420 |
@end table |
1421 |
|
1422 |
@c ================================================================== |
1423 |
@node Technical information, About us, Running vpe, Top |
1424 |
@chapter Technical information |
1425 |
|
1426 |
|
1427 |
@menu |
1428 |
* The connection:: |
1429 |
* The meta-protocol:: |
1430 |
* Security:: |
1431 |
@end menu |
1432 |
|
1433 |
|
1434 |
@c ================================================================== |
1435 |
@node The connection, The meta-protocol, Technical information, Technical information |
1436 |
@section The connection |
1437 |
|
1438 |
@cindex connection |
1439 |
vpe is a daemon that takes VPN data and transmit that to another host |
1440 |
computer over the existing Internet infrastructure. |
1441 |
|
1442 |
@menu |
1443 |
* The UDP tunnel:: |
1444 |
* The meta-connection:: |
1445 |
@end menu |
1446 |
|
1447 |
|
1448 |
@c ================================================================== |
1449 |
@node The UDP tunnel, The meta-connection, The connection, The connection |
1450 |
@subsection The UDP tunnel |
1451 |
|
1452 |
@cindex virtual network device |
1453 |
@cindex frame type |
1454 |
The data itself is read from a character device file, the so-called |
1455 |
@emph{virtual network device}. This device is associated with a network |
1456 |
interface. Any data sent to this interface can be read from the device, |
1457 |
and any data written to the device gets sent from the interface. Data to |
1458 |
and from the device is formatted as if it were a normal Ethernet card, |
1459 |
so a frame is preceded by two MAC addresses and a @emph{frame type} |
1460 |
field. |
1461 |
|
1462 |
So when vpe reads an Ethernet frame from the device, it determines its |
1463 |
type. When vpe is in it's default routing mode, it can handle IPv4 and IPv6 |
1464 |
packets. Depending on the Subnet lines, it will send the packets off to their destination. |
1465 |
In the `switch' and `hub' mode, vpe will use broadcasts and MAC address discovery |
1466 |
to deduce the destination of the packets. |
1467 |
Since the latter modes only depend on the link layer information, |
1468 |
any protocol that runs over Ethernet is supported (for instance IPX and Appletalk). |
1469 |
|
1470 |
After the destination has been determined, |
1471 |
the packet will be compressed (optionally), |
1472 |
a sequence number will be added to the packet, |
1473 |
the packet will then be encrypted |
1474 |
and a message authentication code will be appended. |
1475 |
|
1476 |
@cindex encapsulating |
1477 |
@cindex UDP |
1478 |
When that is done, time has come to actually transport the |
1479 |
packet to the destination computer. We do this by sending the packet |
1480 |
over an UDP connection to the destination host. This is called |
1481 |
@emph{encapsulating}, the VPN packet (though now encrypted) is |
1482 |
encapsulated in another IP datagram. |
1483 |
|
1484 |
When the destination receives this packet, the same thing happens, only |
1485 |
in reverse. So it checks the message authentication code, decrypts the contents of the UDP datagram, |
1486 |
checks the sequence number |
1487 |
and writes the decrypted information to its own virtual network device. |
1488 |
|
1489 |
To let the kernel on the receiving end accept the packet, the destination MAC |
1490 |
address must match that of the virtual network interface. |
1491 |
If vpe is in it's default routing mode, ARP does not work, so the correct destination MAC cannot be set |
1492 |
by the sending daemons. |
1493 |
vpe solves this by letting the receiving end detect the MAC address |
1494 |
and overwriting the destination MAC address of the received packet. |
1495 |
However, the MAC address of the network interface at the receiver might not always be known to vpe. |
1496 |
That is the reason why you should set the MAC address of your tap interface to that address |
1497 |
when in routing mode. |
1498 |
|
1499 |
In switch or hub modes ARP does work so the sender already knows the correct destination MAC address. |
1500 |
In those modes every interface should have a unique MAC address, so make sure they are not the same. |
1501 |
|
1502 |
|
1503 |
@c ================================================================== |
1504 |
@node The meta-connection, , The UDP tunnel, The connection |
1505 |
@subsection The meta-connection |
1506 |
|
1507 |
Having only a UDP connection available is not enough. Though suitable |
1508 |
for transmitting data, we want to be able to reliably send other |
1509 |
information, such as routing and session key information to somebody. |
1510 |
|
1511 |
@cindex TCP |
1512 |
TCP is a better alternative, because it already contains protection |
1513 |
against information being lost, unlike UDP. |
1514 |
|
1515 |
So we establish two connections. One for the encrypted VPN data, and one |
1516 |
for other information, the meta-data. Hence, we call the second |
1517 |
connection the meta-connection. We can now be sure that the |
1518 |
meta-information doesn't get lost on the way to another computer. |
1519 |
|
1520 |
@cindex data-protocol |
1521 |
@cindex meta-protocol |
1522 |
Like with any communication, we must have a protocol, so that everybody |
1523 |
knows what everything stands for, and how she should react. Because we |
1524 |
have two connections, we also have two protocols. The protocol used for |
1525 |
the UDP data is the ``data-protocol,'' the other one is the |
1526 |
``meta-protocol.'' |
1527 |
|
1528 |
The reason we don't use TCP for both protocols is that UDP is much |
1529 |
better for encapsulation, even while it is less reliable. The real |
1530 |
problem is that when TCP would be used to encapsulate a TCP stream |
1531 |
that's on the private network, for every packet sent there would be |
1532 |
three ACKs sent instead of just one. Furthermore, if there would be |
1533 |
a timeout, both TCP streams would sense the timeout, and both would |
1534 |
start re-sending packets. |
1535 |
|
1536 |
|
1537 |
@c ================================================================== |
1538 |
@node The meta-protocol, Security, The connection, Technical information |
1539 |
@section The meta-protocol |
1540 |
|
1541 |
The meta protocol is used to tie all vpe daemons together, and |
1542 |
exchange information about which vpe daemon serves which virtual |
1543 |
subnet. |
1544 |
|
1545 |
The meta protocol consists of requests that can be sent to the other |
1546 |
side. Each request has a unique number and several parameters. All |
1547 |
requests are represented in the standard ASCII character set. It is |
1548 |
possible to use tools such as telnet or netcat to connect to a vpe |
1549 |
daemon started with the --bypass-security option |
1550 |
and to read and write requests by hand, provided that one |
1551 |
understands the numeric codes sent. |
1552 |
|
1553 |
The authentication scheme is described in @ref{Authentication protocol}. After a |
1554 |
successful authentication, the server and the client will exchange all the |
1555 |
information about other vpe daemons and subnets they know of, so that both |
1556 |
sides (and all the other vpe daemons behind them) have their information |
1557 |
synchronised. |
1558 |
|
1559 |
@cindex ADD_EDGE |
1560 |
@cindex ADD_SUBNET |
1561 |
@example |
1562 |
daemon message |
1563 |
-------------------------------------------------------------------------- |
1564 |
origin ADD_EDGE node1 node2 21.32.43.54 655 222 0 |
1565 |
| | | | | +-> options |
1566 |
| | | | +----> weight |
1567 |
| | | +--------> UDP port of node2 |
1568 |
| | +----------------> real address of node2 |
1569 |
| +-------------------------> name of destination node |
1570 |
+-------------------------------> name of source node |
1571 |
|
1572 |
origin ADD_SUBNET node 192.168.1.0/24 |
1573 |
| | +--> prefixlength |
1574 |
| +--------> network address |
1575 |
+------------------> owner of this subnet |
1576 |
-------------------------------------------------------------------------- |
1577 |
@end example |
1578 |
|
1579 |
The ADD_EDGE messages are to inform other vpe daemons that a connection between |
1580 |
two nodes exist. The address of the destination node is available so that |
1581 |
VPN packets can be sent directly to that node. |
1582 |
|
1583 |
The ADD_SUBNET messages inform other vpe daemons that certain subnets belong |
1584 |
to certain nodes. vpe will use it to determine to which node a VPN packet has |
1585 |
to be sent. |
1586 |
|
1587 |
@cindex DEL_EDGE |
1588 |
@cindex DEL_SUBNET |
1589 |
@example |
1590 |
message |
1591 |
------------------------------------------------------------------ |
1592 |
DEL_EDGE node1 node2 |
1593 |
| +----> name of destination node |
1594 |
+----------> name of source node |
1595 |
|
1596 |
DEL_SUBNET node 192.168.1.0/24 |
1597 |
| | +--> prefixlength |
1598 |
| +--------> network address |
1599 |
+------------------> owner of this subnet |
1600 |
------------------------------------------------------------------ |
1601 |
@end example |
1602 |
|
1603 |
In case a connection between two daemons is closed or broken, DEL_EDGE messages |
1604 |
are sent to inform the other daemons of that fact. Each daemon will calculate a |
1605 |
new route to the the daemons, or mark them unreachable if there isn't any. |
1606 |
|
1607 |
@cindex REQ_KEY |
1608 |
@cindex ANS_KEY |
1609 |
@cindex KEY_CHANGED |
1610 |
@example |
1611 |
message |
1612 |
------------------------------------------------------------------ |
1613 |
REQ_KEY origin destination |
1614 |
| +--> name of the vpe daemon it wants the key from |
1615 |
+----------> name of the daemon that wants the key |
1616 |
|
1617 |
ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 |
1618 |
| | \______________/ | | +--> MAC length |
1619 |
| | | | +-----> digest algorithm |
1620 |
| | | +--------> cipher algorithm |
1621 |
| | +--> 128 bits key |
1622 |
| +--> name of the daemon that wants the key |
1623 |
+----------> name of the daemon that uses this key |
1624 |
|
1625 |
KEY_CHANGED origin |
1626 |
+--> daemon that has changed it's packet key |
1627 |
-------------------------------------------------------------------------- |
1628 |
@end example |
1629 |
|
1630 |
The keys used to encrypt VPN packets are not sent out directly. This is |
1631 |
because it would generate a lot of traffic on VPNs with many daemons, and |
1632 |
chances are that not every vpe daemon will ever send a packet to every |
1633 |
other daemon. Instead, if a daemon needs a key it sends a request for it |
1634 |
via the meta connection of the nearest hop in the direction of the |
1635 |
destination. |
1636 |
|
1637 |
@cindex PING |
1638 |
@cindex PONG |
1639 |
@example |
1640 |
daemon message |
1641 |
-------------------------------------------------------------------------- |
1642 |
origin PING |
1643 |
dest. PONG |
1644 |
-------------------------------------------------------------------------- |
1645 |
@end example |
1646 |
|
1647 |
There is also a mechanism to check if hosts are still alive. Since network |
1648 |
failures or a crash can cause a daemon to be killed without properly |
1649 |
shutting down the TCP connection, this is necessary to keep an up to date |
1650 |
connection list. PINGs are sent at regular intervals, except when there |
1651 |
is also some other traffic. A little bit of salt (random data) is added |
1652 |
with each PING and PONG message, to make sure that long sequences of PING/PONG |
1653 |
messages without any other traffic won't result in known plaintext. |
1654 |
|
1655 |
This basically covers what is sent over the meta connection by |
1656 |
vpe. |
1657 |
|
1658 |
|
1659 |
@c ================================================================== |
1660 |
@node Security, , The meta-protocol, Technical information |
1661 |
@section About vpe's encryption and other security-related issues. |
1662 |
|
1663 |
@cindex TINC |
1664 |
@cindex Cabal |
1665 |
vpe got its name from ``TINC,'' short for @emph{There Is No Cabal}; the |
1666 |
alleged Cabal was/is an organisation that was said to keep an eye on the |
1667 |
entire Internet. As this is exactly what you @emph{don't} want, we named |
1668 |
the vpe project after TINC. |
1669 |
|
1670 |
@cindex SVPN |
1671 |
But in order to be ``immune'' to eavesdropping, you'll have to encrypt |
1672 |
your data. Because vpe is a @emph{Secure} VPN (SVPN) daemon, it does |
1673 |
exactly that: encrypt. |
1674 |
vpe by default uses blowfish encryption with 128 bit keys in CBC mode, 32 bit |
1675 |
sequence numbers and 4 byte long message authentication codes to make sure |
1676 |
eavesdroppers cannot get and cannot change any information at all from the |
1677 |
packets they can intercept. The encryption algorithm and message authentication |
1678 |
algorithm can be changed in the configuration. The length of the message |
1679 |
authentication codes is also adjustable. The length of the key for the |
1680 |
encryption algorithm is always the default length used by OpenSSL. |
1681 |
|
1682 |
@menu |
1683 |
* Authentication protocol:: |
1684 |
* Encryption of network packets:: |
1685 |
@end menu |
1686 |
|
1687 |
|
1688 |
@c ================================================================== |
1689 |
@node Authentication protocol, Encryption of network packets, Security, Security |
1690 |
@subsection Authentication protocol |
1691 |
|
1692 |
@cindex authentication |
1693 |
A new scheme for authentication in vpe has been devised, which offers some |
1694 |
improvements over the protocol used in 1.0pre2 and 1.0pre3. Explanation is |
1695 |
below. |
1696 |
|
1697 |
@cindex ID |
1698 |
@cindex META_KEY |
1699 |
@cindex CHALLENGE |
1700 |
@cindex CHAL_REPLY |
1701 |
@cindex ACK |
1702 |
@example |
1703 |
daemon message |
1704 |
-------------------------------------------------------------------------- |
1705 |
client <attempts connection> |
1706 |
|
1707 |
server <accepts connection> |
1708 |
|
1709 |
client ID client 12 |
1710 |
| +---> version |
1711 |
+-------> name of vpe daemon |
1712 |
|
1713 |
server ID server 12 |
1714 |
| +---> version |
1715 |
+-------> name of vpe daemon |
1716 |
|
1717 |
client META_KEY 5f0823a93e35b69e...7086ec7866ce582b |
1718 |
\_________________________________/ |
1719 |
+-> RSAKEYLEN bits totally random string S1, |
1720 |
encrypted with server's public RSA key |
1721 |
|
1722 |
server META_KEY 6ab9c1640388f8f0...45d1a07f8a672630 |
1723 |
\_________________________________/ |
1724 |
+-> RSAKEYLEN bits totally random string S2, |
1725 |
encrypted with client's public RSA key |
1726 |
|
1727 |
From now on: |
1728 |
- the client will symmetrically encrypt outgoing traffic using S1 |
1729 |
- the server will symmetrically encrypt outgoing traffic using S2 |
1730 |
|
1731 |
client CHALLENGE da02add1817c1920989ba6ae2a49cecbda0 |
1732 |
\_________________________________/ |
1733 |
+-> CHALLEN bits totally random string H1 |
1734 |
|
1735 |
server CHALLENGE 57fb4b2ccd70d6bb35a64c142f47e61d57f |
1736 |
\_________________________________/ |
1737 |
+-> CHALLEN bits totally random string H2 |
1738 |
|
1739 |
client CHAL_REPLY 816a86 |
1740 |
+-> 160 bits SHA1 of H2 |
1741 |
|
1742 |
server CHAL_REPLY 928ffe |
1743 |
+-> 160 bits SHA1 of H1 |
1744 |
|
1745 |
After the correct challenge replies are received, both ends have proved |
1746 |
their identity. Further information is exchanged. |
1747 |
|
1748 |
client ACK 655 123 0 |
1749 |
| | +-> options |
1750 |
| +----> estimated weight |
1751 |
+--------> listening port of client |
1752 |
|
1753 |
server ACK 655 321 0 |
1754 |
| | +-> options |
1755 |
| +----> estimated weight |
1756 |
+--------> listening port of server |
1757 |
-------------------------------------------------------------------------- |
1758 |
@end example |
1759 |
|
1760 |
This new scheme has several improvements, both in efficiency and security. |
1761 |
|
1762 |
First of all, the server sends exactly the same kind of messages over the wire |
1763 |
as the client. The previous versions of vpe first authenticated the client, |
1764 |
and then the server. This scheme even allows both sides to send their messages |
1765 |
simultaneously, there is no need to wait for the other to send something first. |
1766 |
This means that any calculations that need to be done upon sending or receiving |
1767 |
a message can also be done in parallel. This is especially important when doing |
1768 |
RSA encryption/decryption. Given that these calculations are the main part of |
1769 |
the CPU time spent for the authentication, speed is improved by a factor 2. |
1770 |
|
1771 |
Second, only one RSA encrypted message is sent instead of two. This reduces the |
1772 |
amount of information attackers can see (and thus use for a cryptographic |
1773 |
attack). It also improves speed by a factor two, making the total speedup a |
1774 |
factor 4. |
1775 |
|
1776 |
Third, and most important: |
1777 |
The symmetric cipher keys are exchanged first, the challenge is done |
1778 |
afterwards. In the previous authentication scheme, because a man-in-the-middle |
1779 |
could pass the challenge/chal_reply phase (by just copying the messages between |
1780 |
the two real vpe daemons), but no information was exchanged that was really |
1781 |
needed to read the rest of the messages, the challenge/chal_reply phase was of |
1782 |
no real use. The man-in-the-middle was only stopped by the fact that only after |
1783 |
the ACK messages were encrypted with the symmetric cipher. Potentially, it |
1784 |
could even send it's own symmetric key to the server (if it knew the server's |
1785 |
public key) and read some of the metadata the server would send it (it was |
1786 |
impossible for the mitm to read actual network packets though). The new scheme |
1787 |
however prevents this. |
1788 |
|
1789 |
This new scheme makes sure that first of all, symmetric keys are exchanged. The |
1790 |
rest of the messages are then encrypted with the symmetric cipher. Then, each |
1791 |
side can only read received messages if they have their private key. The |
1792 |
challenge is there to let the other side know that the private key is really |
1793 |
known, because a challenge reply can only be sent back if the challenge is |
1794 |
decrypted correctly, and that can only be done with knowledge of the private |
1795 |
key. |
1796 |
|
1797 |
Fourth: the first thing that is send via the symmetric cipher encrypted |
1798 |
connection is a totally random string, so that there is no known plaintext (for |
1799 |
an attacker) in the beginning of the encrypted stream. |
1800 |
|
1801 |
|
1802 |
@c ================================================================== |
1803 |
@node Encryption of network packets, , Authentication protocol, Security |
1804 |
@subsection Encryption of network packet |
1805 |
@cindex encryption |
1806 |
|
1807 |
A data packet can only be sent if the encryption key is known to both |
1808 |
parties, and the connection is activated. If the encryption key is not |
1809 |
known, a request is sent to the destination using the meta connection |
1810 |
to retrieve it. The packet is stored in a queue while waiting for the |
1811 |
key to arrive. |
1812 |
|
1813 |
@cindex UDP |
1814 |
The UDP packet containing the network packet from the VPN has the following layout: |
1815 |
|
1816 |
@example |
1817 |
... | IP header | UDP header | seqno | VPN packet | MAC | UDP trailer |
1818 |
\___________________/\_____/ |
1819 |
| | |
1820 |
V +---> digest algorithm |
1821 |
Encrypted with symmetric cipher |
1822 |
@end example |
1823 |
|
1824 |
So, the entire VPN packet is encrypted using a symmetric cipher, including a 32 bits |
1825 |
sequence number that is added in front of the actual VPN packet, to act as a unique |
1826 |
IV for each packet and to prevent replay attacks. A message authentication code |
1827 |
is added to the UDP packet to prevent alteration of packets. By default the |
1828 |
first 4 bytes of the digest are used for this, but this can be changed using |
1829 |
the MACLength configuration variable. |
1830 |
|
1831 |
@c ================================================================== |
1832 |
@node About us, Concept Index, Technical information, Top |
1833 |
@chapter About us |
1834 |
|
1835 |
|
1836 |
@menu |
1837 |
* Contact Information:: |
1838 |
* Authors:: |
1839 |
@end menu |
1840 |
|
1841 |
|
1842 |
@c ================================================================== |
1843 |
@node Contact Information, Authors, About us, About us |
1844 |
@section Contact information |
1845 |
|
1846 |
@cindex website |
1847 |
vpe's website is at @url{http://vpe.nl.linux.org/}, |
1848 |
this server is located in the Netherlands. |
1849 |
|
1850 |
@cindex IRC |
1851 |
We have an IRC channel on the FreeNode IRC network. Connect to |
1852 |
@uref{http://www.freenode.net/, irc.freenode.net} |
1853 |
and join channel #vpe. |
1854 |
|
1855 |
|
1856 |
@c ================================================================== |
1857 |
@node Authors, , Contact Information, About us |
1858 |
@section Authors |
1859 |
|
1860 |
@table @asis |
1861 |
@item Ivo Timmermans (zarq) (@email{ivo@@o2w.nl}) |
1862 |
@item Guus Sliepen (guus) (@email{guus@@sliepen.eu.org}) |
1863 |
@end table |
1864 |
|
1865 |
We have received a lot of valuable input from users. With their help, |
1866 |
vpe has become the flexible and robust tool that it is today. We have |
1867 |
composed a list of contributions, in the file called @file{THANKS} in |
1868 |
the source distribution. |
1869 |
|
1870 |
|
1871 |
@c ================================================================== |
1872 |
@node Concept Index, , About us, Top |
1873 |
@c node-name, next, previous, up |
1874 |
@unnumbered Concept Index |
1875 |
|
1876 |
@c ================================================================== |
1877 |
@printindex cp |
1878 |
|
1879 |
|
1880 |
@c ================================================================== |
1881 |
@contents |
1882 |
@bye |