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