Updated by Lubomir Bulej and Mads Kiilerich: it uses /etc/tinc/nets.boot and the...
[tinc] / doc / tinc.texi
1 \input texinfo   @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename tinc.info
4 @settitle tinc Manual
5 @setchapternewpage odd
6 @c %**end of header
7
8 @ifinfo
9 @direntry
10 * tinc: (tinc).              The tinc Manual.
11 @end direntry
12
13 This is the info manual for tinc, a Virtual Private Network daemon.
14
15 Copyright 1998,199,2000 Ivo Timmermans <itimmermans@@bigfoot.com>
16
17      Permission is granted to make and distribute verbatim
18      copies of this manual provided the copyright notice and
19      this permission notice are preserved on all copies.
20
21      Permission is granted to copy and distribute modified
22      versions of this manual under the conditions for
23      verbatim copying, provided
24      that the entire resulting derived work is distributed
25      under the terms of a permission notice identical to this
26      one.
27
28 @end ifinfo
29
30 @titlepage
31 @title tinc Manual
32 @subtitle Setting up a Virtual Private Network with tinc
33 @author Ivo Timmermans <itimmermans@@bigfoot.com>
34
35 @page
36 @vskip 0pt plus 1filll
37 Copyright @copyright{} 1998,1999,2000 Ivo Timmermans <itimmermans@@bigfoot.com>
38
39      Permission is granted to make and distribute verbatim
40      copies of this manual provided the copyright notice and
41      this permission notice are preserved on all copies.
42
43      Permission is granted to copy and distribute modified
44      versions of this manual under the conditions for
45      verbatim copying, provided
46      that the entire resulting derived work is distributed
47      under the terms of a permission notice identical to this
48      one.
49
50 @end titlepage
51
52 @c ==================================================================
53 @node Top, Introduction, (dir), (dir)
54
55 @menu
56 * Introduction::                Introduction
57 * Configuring a Linux system::  Before compiling tinc
58 * Installing tinc::             
59 * Configuring tinc::            
60 * Running tinc::                
61 * Technical information::       
62 * About us::                    
63 * Concept Index::               All used terms explained
64 @end menu
65
66 @c ==================================================================
67 @node    Introduction, Configuring a Linux system, Top, Top
68 @chapter Introduction
69
70 @c straight from the www page
71
72 tinc is a Virtual Private Network (VPN) daemon that uses tunneling and
73 encryption to create a secure private network between hosts on the
74 Internet.
75
76 Because the tunnel appears to the IP level network code as a normal
77 network device, there is no need to adapt any existing software.
78
79 This tunneling allows VPN sites to share information with each other
80 over the Internet without exposing any information to others.
81
82 This document is the manual for tinc. Included are chapters on how to
83 configure your computer to use tinc, as well as the configuration
84 process of tinc itself.
85
86 @menu
87 * VPNs::                        Virtual Private Networks in general
88 * tinc::                        about tinc
89 @end menu
90
91 @c ==================================================================
92 @node    VPNs, tinc, Introduction, Introduction
93 @section Virtual Private Networks
94
95 A Virtual Private Network or VPN is a network that can only be accessed
96 by a few elected computers that participate. This goal is achievable in
97 more than just one way.
98
99 @cindex private
100 For instance, a VPN can consist of a single stand-alone ethernet LAN. Or
101 even two computers hooked up using a null-modem cable@footnote{Though
102 discuss-able, I think it qualifies as a VPN.}. In these cases, it is
103 obvious that the network is @emph{private}. But there is another type
104 of VPN, the type tinc was made for.
105
106 @cindex virtual
107 tinc uses normal IP datagrams to encapsulate data that goes over the VPN
108 network link. In this case it's also clear that the network is
109 @emph{virtual}, because no direct network link has to exist between to
110 participants.
111
112 As is the case with either type of VPN, anybody could eavesdrop. Or
113 worse, alter data. Hence it's probably advisable to encrypt the data
114 that flows over the network.
115
116
117 @c ==================================================================
118 @node    tinc,  , VPNs, Introduction
119 @section tinc
120
121 I really don't quite remember what got us started, but it must have been
122 Guus' idea. He wrote a simple implementation (about 50 lines of C) that
123 used the @emph{ethertap} device that Linux knows of since somewhere
124 about kernel 2.1.60. It didn't work immediately and he improved it a
125 bit. At this stage, the project was still simply called @samp{vpnd}.
126
127 Since then, a lot has changed---to say the least.
128
129 @cindex tincd
130 tinc now supports encryption, it consists of a single daemon (tincd) for
131 both the receiving and sending end, it has become largely
132 runtime-configurable---in short, it has become a full-fledged
133 professional package.
134
135 A lot can---and will be---changed. I have a few things that I'd like to
136 see in the future releases of tinc. Not everything will be available in
137 the near future. Our first objective is to make tinc work perfectly as
138 it stands, and then add more advanced features.
139
140 Meanwhile, we're always open-minded towards new ideas. And we're
141 available too.
142
143
144 @c ==================================================================
145 @node    Configuring a Linux system, Installing tinc, Introduction, Top
146 @chapter Configuring a Linux system
147
148 This chapter contains information on how a Linux system is configured
149 for the use of tinc.
150
151 @menu
152 * Configuring the kernel::      
153 * Files Needed::                
154 * Setting up the devices::      
155 @end menu
156
157
158 @c ==================================================================
159 @node    Configuring the kernel, Files Needed, Configuring a Linux system, Configuring a Linux system
160 @section Configuring the kernel
161
162 Since this particular implementation only runs on 2.1 or higher Linux
163 kernels, you should grab one (2.2 is current at this time). A 2.0 port
164 is not really possible, unless someone tells me someone ported the
165 ethertap and netlink devices back to 2.0.
166
167 If you are unfamiliar with the process of configuring and compiling a
168 new kernel, you should read the
169 @uref{http://howto.linuxberg.com/LDP/HOWTO/Kernel-HOWTO.html, Kernel
170 HOWTO} first. Do that now!
171
172 Here are the options you have to turn on/off when configuring a new
173 kernel.
174
175 @example
176 Code maturity level options
177 [*] Prompt for development and/or incomplete code/drivers
178 Networking options
179 [*] Kernel/User netlink socket
180 <*> Netlink device emulation
181 Network device support
182 <*> Ethertap network tap
183 @end example
184
185 Any other options not mentioned here are not relevant to tinc. If you
186 decide to build any of these as dynamic kernel modules, it's a good idea
187 to add these lines to @file{/etc/modules.conf}.
188
189 @example
190 alias tap0 ethertap
191 alias char-major-36 netlink_dev
192 @end example
193
194 Finally, after having set up other options, build the kernel and boot
195 it. Unfortunately it's not possible to insert these modules in a running
196 kernel.
197
198
199 @c ==================================================================
200 @node    Files Needed, Setting up the devices, Configuring the kernel, Configuring a Linux system
201 @section Files Needed
202
203 @subsubheading Device files
204
205 First, you'll need the special device file(s) that form the interface
206 between the kernel and the daemon.
207
208 @example
209 mknod -m 600 /dev/tap0 c 36 16
210 chown 0.0 /dev/tap0
211 @end example
212
213 The permissions now will be such that only the super user may read/write
214 to this file. You'd want this, because otherwise eavesdropping would
215 become a bit too easy. This does, however, imply that you'd have to run
216 tincd as root.
217
218 If you want to, you may also create more device files, which would be
219 numbered 0...15, with minor device numbers 16...31. They all should be
220 owned by root and have permission 600.
221
222
223 @subsubheading @file{/etc/networks}
224
225 You may add a line to @file{/etc/networks} so that your VPN will get a
226 symbolic name. For example:
227
228 @example
229 myvpn 10.0.0.0
230 @end example
231
232
233 @subsubheading @file{/etc/services}
234
235 You may add this line to @file{/etc/services}. The effect is that you
236 may supply a @samp{tinc} as a valid port number to some programs. The
237 number 655 is registered with the IANA.
238
239 @example
240 tinc            655/tcp    TINC
241 tinc            655/udp    TINC
242 #                          Ivo Timmermans <itimmermans@@bigfoot.com>
243 @end example
244
245
246 @c ==================================================================
247 @node    Setting up the devices,  , Files Needed, Configuring a Linux system
248 @section Setting up the devices
249
250 Before you can start transmitting data over the tinc tunnel, you must
251 set up the ethertap network devices.
252
253 First, decide which IP addresses you want to have associated with these
254 devices, and what network mask they must have. You also need these
255 numbers when you are going to configure tinc itself. @xref{Configuring
256 tinc}.
257
258 It doesn't matter much which part you do first, setting up the network
259 devices or configure tinc. But they both have to be done before you try
260 to start a tincd.
261
262 The actual setup of the ethertap device is quite simple, just repeat
263 after me:
264
265 @example
266 ifconfig tap@emph{n} hw ether fe:fd:@emph{xx}:@emph{xx}:@emph{xx}:@emph{xx}
267 @end example
268
269 The @emph{n} here is the number of the ethertap device you want to
270 use. It should be the same @emph{n} as the one you use for
271 @file{/dev/tap@emph{n}}. The @emph{xx}s are four hexadecimal numbers
272 (0--ff). With previous versions of tincd, it didn't matter what they
273 were. But newer kernels require properly set up ethernet addresses.
274 In fact, the old behavior was wrong. It is required that the @emph{xx}s
275 match MyOwnVPNIP.
276
277 @example
278 ifconfig tap@emph{n} @emph{IP} netmask @emph{mask}
279 @end example
280
281 This will activate the device with an IP address @emph{IP} with network
282 mask @emph{mask}.
283
284
285
286 @c ==================================================================
287 @node    Installing tinc, Configuring tinc, Configuring a Linux system, Top
288 @chapter Installing tinc
289
290 First download it. This is the
291 @uref{http://tinc.nl.linux.org/download.html, download
292 page}, which has the checksums of these files listed; you may wish to
293 check these with md5sum before continuing.
294
295 tinc comes in a handy autoconf/automake package, which you can just
296 treat the same as any other package. Which is just untar it, type
297 `configure' and then `make'.
298
299 More detailed instructions are in the file @file{INSTALL}, which is
300 included in the source distribution.
301
302
303 @c ==================================================================
304 @node    Configuring tinc, Running tinc, Installing tinc, Top
305 @chapter Configuring tinc
306
307 @menu
308 * Multiple networks::           
309 * How connections work::        
310 * Configuration file::          
311 * Example::                     
312 @end menu
313
314
315 @c ==================================================================
316 @node    Multiple networks, How connections work, Configuring tinc, Configuring tinc
317 @section Multiple networks
318
319 @c from the manpage
320
321 It is perfectly OK for you to run more than one tinc daemon.
322 However, in its default form, you will soon notice that you can't use
323 two different configuration files without the -c option.
324
325 We have thought of another way of dealing with this: network names. This
326 means that you call tincd with the -n argument, which will assign a name
327 to this daemon.
328
329 The effect of this is that the daemon will set its configuration
330 ``root'' to /etc/tinc/nn/, where nn is your argument to the -n
331 option. You'll notice that it appears in syslog as ``tinc.nn''.
332
333 However, it is not strictly necessary that you call tinc with the -n
334 option. In this case, the network name would just be empty, and it will
335 be used as such. tinc now looks for files in /etc/tinc/, instead of
336 /etc/tinc/nn/; the configuration file should be /etc/tinc/tinc.conf,
337 and the passphrases are now expected to be in /etc/tinc/passphrases/.
338
339 But it is highly recommended that you use this feature of tinc, because
340 it will be so much clearer whom your daemon talks to. Hence, we will
341 assume that you use it.
342
343
344 @c ==================================================================
345 @node    How connections work, Configuration file, Multiple networks, Configuring tinc
346 @section How connections work
347
348 Before going on, first a bit on how tinc sees connections.
349
350 When tinc starts up, it reads in the configuration file and parses the
351 command-line options. If it sees a `ConnectTo' value in the file, it
352 will try to connect to it, on the given port. If this fails, tinc exits.
353
354
355 @c ==================================================================
356 @node    Configuration file, Example, How connections work, Configuring tinc
357 @section Configuration file
358
359 The actual configuration of the daemon is done in the file
360 @file{/etc/tinc/nn/tinc.conf}.
361
362 This file consists of comments (lines started with a #) or assignments
363 in the form of
364
365 @example
366 Variable = Value.
367 @end example
368
369 The variable names are case insensitive, and any spaces, tabs, newlines
370 and carriage returns are ignored. Note: it is not required that you put
371 in the `=' sign, but doing so improves readability.  If you leave it
372 out, remember to replace it with at least one space character.
373
374 @menu
375 * Variables::                   
376 @end menu
377
378 @c ==================================================================
379 @node    Variables,  , Configuration file, Configuration file
380 @subsection Variables
381
382 Here are all valid variables, listed in alphabetical order:
383
384 @c straight from the manpage
385 @table @asis
386 @item AllowConnect = (yes|no)
387 If set to yes, anyone may try to connect to you. If you set this to no,
388 no incoming connections will be accepted. This does not affect the
389 outgoing connections.
390
391 @item ConnectPort = port
392 Connect to the upstream host (given with the ConnectTo directive) on
393 port port. port may be given in decimal (default), octal (when preceded
394 by a single zero) or hexadecimal (prefixed with 0x).  port is the port
395 number for both the UDP and the TCP (meta) connections.
396
397 @item ConnectTo = (IP address|hostname)
398 Specifies which host to connect to on startup. If the ConnectPort
399 variable is omitted, then tinc will try to connect to port 655.
400
401 If you don't specify a host with ConnectTo, regardless of whether a
402 value for ConnectPort is given, tinc won't connect at all, and will
403 instead just listen for incoming connections. Only the initiator of a
404 tinc VPN should need this.
405
406 @item ListenPort = port
407 Listen on local port port. The computer connecting to this daemon should
408 use this number as the argument for his ConnectPort. Again, the
409 default is 655.
410
411 @item MyOwnVPNIP = local address[/maskbits]
412 The local address is the number that the daemon will propagate to
413 other daemons on the network when it is identifying itself. Hence this
414 will be the file name of the passphrase file that the other end expects
415 to find the passphrase in.
416
417 The local address is the IP address of the tap device, not the real IP
418 address of the host running tincd. Due to changes in recent kernels, it
419 is also necessary that you make the ethernet (also known as MAC) address
420 equal to the IP address (see the example).
421
422 maskbits is the number of bits set to 1 in the netmask part.
423
424 @item MyVirtualIP = local address[/maskbits]
425 This is an alias for MyOwnVPNIP.
426
427 @item Passphrases = directory
428 The directory where tinc will look for passphrases when someone tries to
429 connect. Please see the manpage for genauth(8) for more information
430 about passphrases as used by tinc.
431
432 @item PingTimeout = number
433 The number of seconds of inactivity that tinc will wait before sending a
434 probe to the other end. If that other end doesn't answer within that
435 same amount of seconds, the connection is terminated, and the others
436 will be notified of this.
437
438 @item TapDevice = device
439 The ethertap device to use. Note that you can only use one device per
440 daemon. The info pages of the tinc package contain more information
441 about configuring an ethertap device for Linux.
442
443 @end table
444
445
446 @c ==================================================================
447 @node    Example,  , Configuration file, Configuring tinc
448 @section Example
449
450 Imagine the following situation. An A-based company wants to connect
451 three branch offices in B, C and D using the internet. All four offices
452 have a 24/7 connection to the internet.
453
454 A is going to serve as the center of the network. B and C will connect
455 to A, and D will connect to C. Each office will be assigned their own IP
456 network, 10.x.0.0.
457
458 @example
459 A: net 10.1.0.0 mask 255.255.0.0 gateway 10.1.54.1 internet IP 1.2.3.4
460 B: net 10.2.0.0 mask 255.255.0.0 gateway 10.2.1.12 internet IP 2.3.4.5
461 C: net 10.3.0.0 mask 255.255.0.0 gateway 10.3.69.254 internet IP 3.4.5.6
462 D: net 10.4.0.0 mask 255.255.0.0 gateway 10.4.3.32 internet IP 4.5.6.7
463 @end example
464
465 ``gateway'' is the VPN IP address of the machine that is running the
466 tincd. ``internet IP'' is the IP address of the firewall, which does not
467 need to run tincd, but it must do a port forwarding of TCP&UDP on port
468 655 (unless otherwise configured).
469
470 In this example, it is assumed that eth0 is the interface that points to
471 the inner LAN of the office. This could be the same as the interface
472 that leads to the internet.
473
474 @subsubheading For A
475
476 @emph{A} would be configured like this:
477
478 @example
479 ifconfig tap0 hw ether fe:fd:0a:01:36:01
480 ifconfig tap0 10.1.54.1 netmask 255.0.0.0
481 ifconfig eth0 10.1.54.1 netmask 255.255.0.0 broadcast 10.1.255.255
482 @end example
483
484 and in /etc/tinc/tinc.conf:
485
486 @example
487 TapDevice = /dev/tap0
488 MyVirtualIP = 10.1.54.1/16
489 @end example
490
491 @subsubheading For B
492
493 @example
494 ifconfig tap0 hw ether fe:fd:0a:02:01:0c
495 ifconfig tap0 10.2.1.12 netmask 255.0.0.0
496 ifconfig eth0 10.2.43.8 netmask 255.255.0.0 broadcast 10.2.255.255
497 @end example
498
499 and in /etc/tinc/tinc.conf:
500
501 @example
502 TapDevice = /dev/tap0
503 MyVirtualIP = 10.2.1.12/16
504 ConnectTo = 1.2.3.4
505 AllowConnect = no
506 @end example
507
508 Note here that the internal address (on eth0) doesn't have to be the
509 same as on the tap0 device. Also, ConnectTo is given so that no-one can
510 connect to this node.
511
512 @subsubheading For C
513
514 @example
515 ifconfig tap0 hw ether fe:fd:0a:03:45:fe
516 ifconfig tap0 10.3.69.254 netmask 255.0.0.0
517 ifconfig eth0 10.3.69.254 netmask 255.255.0.0 broadcast 10.3.255.255
518 @end example
519
520 and in /etc/tinc/A/tinc.conf:
521
522 @example
523 MyVirtualIP = 10.3.69.254/16
524 ConnectTo = 1.2.3.4
525 ListenPort = 2000
526 @end example
527
528 C already has another daemon that runs on port 655, so they have to
529 reserve another port for tinc. They also use the netname to distinguish
530 between the two. tinc is started with `tincd -n A'.
531
532 @subsubheading For D
533
534 @example
535 ifconfig tap0 hw ether fe:fd:0a:04:03:20
536 ifconfig tap0 10.4.3.32 netmask 255.0.0.0
537 ifconfig tap0 10.4.3.32 netmask 255.255.0.0 broadcast 10.4.255.255
538 @end example
539
540 and in /etc/tinc/tinc.conf:
541
542 @example
543 MyVirtualIP = 10.4.3.32/16
544 ConnectTo = 3.4.5.6
545 ConnectPort = 2000
546 AllowConnect = no
547 @end example
548
549 D will be connecting to C, which has a tincd running for this network on
550 port 2000. Hence they need to put in a ConnectPort.
551
552 @subsubheading Authentication
553
554 A, B, C and D all generate a passphrase with genauth 2048, the output is
555 stored in /etc/tinc/passphrases/local, except for C, where it should be
556 /etc/tinc/A/passphrases/local.
557
558 A stores a copy of B's passphrase in /etc/tinc/passphrases/10.2.0.0
559
560 A stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.0.0
561
562 B stores a copy of A's passphrase in /etc/tinc/passphrases/10.1.0.0
563
564 C stores a copy of A's passphrase in /etc/tinc/A/passphrases/10.1.0.0
565
566 C stores a copy of D's passphrase in /etc/tinc/A/passphrases/10.4.0.0
567
568 D stores a copy of C's passphrase in /etc/tinc/passphrases/10.3.0.0
569
570 @subsubheading Starting
571
572 A has to start their tincd first. Then come B and C, where C has to
573 provide the option `-n A', because they have more than one tinc
574 network. Finally, D's tincd is started.
575
576
577
578 @c ==================================================================
579 @node    Running tinc, Technical information, Configuring tinc, Top
580 @chapter Running tinc
581
582 Running tinc isn't just as easy as typing `tincd' and hoping everything
583 will just work out the way you wanted. Instead, the use of tinc is a
584 project that involves trust relations and more than one computer.
585
586 @menu
587 * Managing keys::               
588 * Runtime options::             
589 @end menu
590
591
592 @c ==================================================================
593 @node    Managing keys, Runtime options, Running tinc, Running tinc
594 @section Managing keys
595
596 Before attempting to start tinc, you have to create passphrases. When
597 tinc tries to make a connection, it exchanges some sensitive
598 data. Before doing so, it likes to know if the other end is
599 trustworthy.
600
601 To do this, both ends must have some knowledge about the other. In the
602 case of tinc this is the authentication passphrase.
603
604 This passphrase is a number, which is chosen at random. This number is
605 then sent to the other computers which want to talk to us directly. To
606 avoid breaking security, this should be done over a known secure channel
607 (such as ssh or similar).
608
609 All passphrases are stored in the passphrases directory, which is
610 normally /etc/tinc/nn/passphrases/, but it may be changed using the
611 `Passphrases' option in the config file.
612
613 To generate a passphrase, run `genauth'. genauth takes one argument,
614 which is the length of the passphrase in bits. The length of the
615 passphrase should be in the range 1024--2048 for a key length of 128
616 bits. genauth creates a random number of the specified length, and puts
617 it to stdout.
618
619 Every computer that wants to participate in the VPN should do this, and
620 store the output in the passphrases directory, in the file @file{local}.
621
622 When every computer has his own local key, it should copy it to the
623 computer that it wants to talk to directly. (i.e. the one it connects to
624 during startup.) This should be done via a secure channel, because it is
625 sensitive information. If this is not done securely, someone might break
626 in on you later on.
627
628 Those non-local passphrase files must have the name of the VPN IP
629 address that they will advertise to you. For instance, if a computer
630 tells us it likes to be 10.1.1.3 with netmask 255.255.0.0, the file
631 should still be called 10.1.1.3, and not 10.1.0.0.
632
633
634 @c ==================================================================
635 @node    Runtime options,  , Managing keys, Running tinc
636 @section Runtime options
637
638 Besides the settings in the configuration file, tinc also accepts some
639 command line options.
640
641 This list is a longer version of that in the manpage. The latter is
642 generated automatically, so may be more up-to-date.
643
644 @c from the manpage
645 @table @asis
646 @item -c, --config=FILE
647 Read configuration options from FILE. The default is
648 @file{/etc/tinc/nn/tinc.conf}.
649
650 @item -d
651 Increase debug level. The higher it gets, the more gets
652 logged. Everything goes via syslog.
653
654 0 is the default, only some basic information connection attempts get
655 logged. Setting it to 1 will log a bit more, still not very
656 disturbing. With two -d's tincd will log protocol information, which can
657 get pretty noisy. Three or more -d's will output every single packet
658 that goes out or comes in, which probably generates more data than the
659 packets themselves.
660
661 @item -k, --kill
662 Attempt to kill a running tincd and exit. A TERM signal (15) gets sent
663 to the daemon that his its PID in /var/run/tinc.nn.pid.
664
665 Because it kills only one tincd, you should use -n here if you use it
666 normally.
667
668 @item -n, --net=NETNAME
669 Connect to net NETNAME. @xref{Multiple networks}.
670
671 @item -t, --timeout=TIMEOUT
672 Seconds to wait before giving a timeout. Should not be set too low,
673 because every time tincd senses a timeout, it disconnects and reconnects
674 again, which will cause unnecessary network traffic and log messages.
675
676 @item --help
677 Display a short reminder of these runtime options and terminate.
678
679 @item --version
680 Output version information and exit.
681
682 @end table
683
684
685 @c ==================================================================
686 @node    Technical information, About us, Running tinc, Top
687 @chapter Technical information
688
689
690 @c ==================================================================
691 @menu
692 * The Connection::              
693 * Security::                    
694 @end menu
695
696 @node    The Connection, Security, Technical information, Technical information
697 @section The basic philosophy of the way tinc works
698 @cindex Connection
699
700 tinc is a daemon that takes VPN data and transmit that to another host
701 computer over the existing Internet infrastructure.
702
703 @menu
704 * Protocol Preview::            
705 * The Meta-connection::         
706 @end menu
707
708
709 @c ==================================================================
710 @node    Protocol Preview, The Meta-connection, The Connection, The Connection
711 @subsection A preview of the way the tinc works
712
713 @cindex ethertap
714 @cindex frame type
715 The data itself is read from a character device file, the so-called
716 @emph{ethertap} device. This device is associated with a network
717 interface. Any data sent to this interface can be read from the device,
718 and any data written to the device gets sent from the interface. Data to
719 and from the device is formatted as if it were a normal ethernet card,
720 so a frame is preceded by two MAC addresses and a @emph{frame type}
721 field.
722
723 So when tinc reads an ethernet frame from the device, it determines its
724 type. Right now, tinc can only handle Internet Protocol version 4 (IPv4)
725 frames. Plans to support other protocols are being made. When tinc knows
726 which type of frame it has read, it can also read the source and
727 destination address from it.
728
729 Now it is time that the frame gets encrypted. Currently the only
730 encryption algorithm available is blowfish.
731
732 @cindex encapsulating
733 When the encryption is ready, time has come to actually transport the
734 packet to the destination computer. We do this by sending the packet
735 over an UDP connection to the destination host. This is called
736 @emph{encapsulating}, the VPN packet (though now encrypted) is
737 encapsulated in another IP datagram.
738
739 When the destination receives this packet, the same thing happens, only
740 in reverse. So it does a decrypt on the contents of the UDP datagram,
741 and it writes the decrypted information to its own ethertap device.
742
743
744 @c ==================================================================
745 @node    The Meta-connection,  , Protocol Preview, The Connection
746 @subsection The meta-connection
747
748 Having only a UDP connection available is not enough. Though suitable
749 for transmitting data, we want to be able to reliably send other
750 information, such as routing and encryption information to somebody.
751
752 TCP is a better alternative, because it already contains protection
753 against information being lost, unlike UDP.
754
755 So we establish two connections. One for the encrypted VPN data, and one
756 for other information, the meta-data. Hence, we call the second
757 connection the meta-connection. We can now be sure that the
758 meta-information doesn't get lost on the way to another computer.
759
760 @cindex data-protocol
761 @cindex meta-protocol
762 Like with any communication, we must have a protocol, so that everybody
763 knows what everything stands for, an how he should react. Because we
764 have two connections, we also have two protocols. The protocol used for
765 the UDP data is the ``data-protocol,'' the other one is the
766 ``meta-protocol.''
767
768 The reason we don't use TCP for both protocols is that UDP is much
769 better for encapsulation, even while it is less reliable. The real
770 problem is that when TCP would be used to encapsulate a TCP stream
771 that's on the private network, for every packet sent there would be
772 three ACK's sent instead of just one. Furthermore, if there would be
773 a timeout, both TCP streams would sense the timeout, and both would
774 start resending packets.
775
776 @c ==================================================================
777 @node    Security,  , The Connection, Technical information
778 @section About tinc's encryption and other security-related issues.
779
780 @cindex tinc
781 @cindex Cabal
782 tinc got its name from ``TINC,'' short for @emph{There Is No Cabal}; the
783 alleged Cabal was/is an organization that was said to keep an eye on the
784 entire Internet. As this is exactly what you @emph{don't} want, we named
785 the tinc project after TINC.
786
787 @cindex SVPN
788 But in order to be ``immune'' to eavesdropping, you'll have to encrypt
789 your data. Because tinc is a @emph{Secure} VPN (SVPN) daemon, it does
790 exactly that: encrypt.
791
792 This chapter is a mixture of ideas, reasoning and explanation, please
793 don't take it too serious.
794
795 @menu
796 * Key Management::              
797 * Authentication::              
798 * Protection::                  
799 @end menu
800
801
802 @c ==================================================================
803 @node    Key Management, Authentication, Security, Security
804 @subsection Key Management
805 @c FIXME: recheck
806
807 @cindex Diffie-Hellman
808 You can't just send a private encryption key to your peer, because
809 somebody else might already be listening to you. So you'll have to
810 negotiate over a shared but secret key. One way to do this is by using
811 the ``Diffie-Hellman key exchange'' protocol
812 (@uref{http://www.rsa.com/rsalabs/faq/html/3-6-1.html}). The idea is as
813 follows.
814
815 You have two participants A and B that want to agree over a shared
816 secret encryption key. Both parties have some large prime number p and a
817 generator g. These numbers may be known to the outside world, and hence
818 may be included in the source distribution.
819
820 @cindex secret key
821 Both parties then generate a secret key. A generates a, and computes g^a
822 mod p. This is then sent to B; while B computes g^b mod p, and transmits
823 this to A, b being generated by B. Both a and b must be smaller than
824 p-1.
825
826 These private keys are generated upon startup, and they are not changed
827 while the connection exists. A possible feature in the future is to
828 dynamically change the keys, every hour for example.
829
830 Both parties then calculate g^ab mod p = k. k is the new, shared, but
831 still secret key.
832
833 To obtain a key k of a sufficient length (128 bits in our vpnd), p
834 should be 2^129-1 or more.
835
836
837 @c ==================================================================
838 @node    Authentication, Protection, Key Management, Security
839 @subsection Authentication
840 @c FIXME: recheck
841
842 @cindex man-in-the-middle attack
843 Because the Diffie-Hellman protocol is in itself vulnerable to the
844 ``man-in-the-middle attack,'' we should introduce an authentication
845 system.
846
847 We will let A transmit a passphrase that is also known to B encrypted
848 with g^a, before A sends this to B. This way, B can check whether A is
849 really A or just someone else.
850
851 @cindex passphrase
852 This passphrase should be 2304 bits for a symmetric encryption
853 system. But since an asymmetric system is more secure, we could do with
854 2048 bits. This only holds if the passphrase is very random. 
855
856 These passphrases could be stored in a file that is non-readable by
857 anyone else but root; e.g. @file{/etc/vpn/passphrases}.
858
859 The only thing that needs to be taken care of is how A announces its
860 passphrase to B.
861
862
863 @c ==================================================================
864 @node    Protection,  , Authentication, Security
865 @subsection Protecting your data
866
867 Now we have securely hidden our data. But a malicious cracker may still
868 bother you by randomly altering the encrypted data he intercepts.
869
870
871 @c ==================================================================
872 @node    About us, Concept Index, Technical information, Top
873 @chapter About us
874
875
876 @menu
877 * Contact Information::         
878 * Authors::                     
879 @end menu
880
881
882 @c ==================================================================
883 @node    Contact Information, Authors, About us, About us
884 @section Contact information
885
886 tinc's main page is at @url{http://tinc.nl.linux.org/},
887 this server is located in the Netherlands.
888
889 We have an IRC channel on the Open Projects IRC network. Connect to
890 @uref{http://openprojects.nu/services/irc.html, irc.openprojects.net},
891 and join channel #tinc.
892
893
894 @c ==================================================================
895 @node    Authors,  , Contact Information, About us
896 @section Authors
897
898 @table @asis
899 @item Ivo Timmermans (zarq) (@email{itimmermans@@bigfoot.com})
900 Main coder/hacker and maintainer of the package.
901
902 @item Guus Sliepen (guus)
903 Originator of it all, co-author.
904
905 @item Wessel Dankers (Ubiq)
906 General obfuscater of the code.
907
908 @end table
909
910 Thank you's to: Dekan, Emphyrio, vDong
911
912 Greetings to: braque, Fluor, giggles, macro, smoke, tribbel
913
914
915 @c ==================================================================
916 @node    Concept Index,  , About us, Top
917 @c        node-name,    next, previous,        up
918 @unnumbered Concept Index
919
920 @c ==================================================================
921 @printindex cp
922
923
924 @c ==================================================================
925 @contents
926 @bye
927