Commit | Line | Data |
---|---|---|
2c1261e5 MW |
1 | \input texinfo @c -*- mode: texinfo; TeX-PDF-mode: t -*- |
2 | @c | |
3 | @c Manual for TrIPE | |
4 | @c | |
5 | @c (c) 2009 Straylight/Edgeware | |
6 | @c | |
7 | ||
8 | @c ----- Standard boilerplate ----------------------------------------------- | |
9 | ||
10 | @c %**start of header | |
11 | @setfilename tripe.info | |
12 | @settitle TrIPE: Trivial IP Encryption | |
13 | @setchapternewpage odd | |
14 | @footnotestyle end | |
15 | @paragraphindent 0 | |
16 | @iftex | |
17 | @input texinice | |
18 | @afourpaper | |
19 | @end iftex | |
20 | ||
21 | @definfoenclose dfn,`,' | |
22 | ||
23 | @macro manpage{NAME, SECTION} | |
24 | @b{\NAME\}(\SECTION\) | |
25 | @end macro | |
26 | ||
27 | @macro user{NAME} | |
28 | @b{\NAME\} | |
29 | @end macro | |
30 | @c %**end of header | |
31 | ||
32 | @include version.texi | |
33 | ||
34 | @dircategory Internet applications | |
35 | @direntry | |
36 | * TrIPE: (tripe). Trivial IP Encryption: a VPN system | |
37 | @end direntry | |
38 | ||
39 | @c ----- Copyright matters -------------------------------------------------- | |
40 | ||
41 | @copying | |
42 | This file documents the TrIPE VPN suite version @value{VERSION}. | |
43 | ||
44 | Copyright @copyright{} 2009 Straylight/Edgeware | |
45 | ||
46 | @quotation | |
47 | Permission is granted to make and distribute verbatim copies of this | |
48 | manual provided the copyright notice and this permission notice are | |
49 | preserved on all copies. | |
50 | ||
51 | @ignore | |
52 | Permission is granted to process this file through TeX and print the | |
53 | results, provided the printed document carries a copying permission | |
54 | notice identical to this one except for the removal of this paragraph | |
55 | (this paragraph not being relevant to the printed manual). | |
56 | ||
57 | @end ignore | |
58 | Permission is granted to copy and distribute modified versions of this | |
59 | manual under the conditions for verbatim copying, provided also that the | |
60 | sections entitled `Copying' and `GNU General Public License' are | |
61 | included exactly as in the original, and provided that the entire | |
62 | resulting derived work is distributed under the terms of a permission | |
63 | notice identical to this one. | |
64 | ||
65 | Permission is granted to copy and distribute translations of this manual | |
66 | into another language, under the above conditions for modified versions, | |
67 | except that this permission notice may be stated in a translation | |
68 | approved by the copyright holder. | |
69 | @end quotation | |
70 | @end copying | |
71 | ||
72 | @c -------------------------------------------------------------------------- | |
73 | @titlepage | |
74 | ||
75 | @title TrIPE: Trivial IP Encryption | |
76 | @subtitle A moderately simple virtual private network | |
77 | @subtitle (version @value{EDITION}) | |
78 | @author Straylight/Edgeware | |
79 | @page | |
80 | ||
81 | @vskip 0pt plus 1filll | |
82 | @insertcopying | |
83 | @end titlepage | |
84 | ||
85 | @iftex | |
86 | @contents | |
87 | @end iftex | |
88 | ||
89 | @c -------------------------------------------------------------------------- | |
90 | @ifnottex | |
91 | @node Top, Copying, (dir), (dir) | |
92 | @top TrIPE: Trivial IP Encryption | |
93 | ||
94 | @menu | |
95 | * Copying:: TrIPE is free software! | |
96 | * Introduction:: What TrIPE is, and what this manual has | |
97 | to say about it | |
98 | ||
99 | * Installing:: Installing TrIPE | |
100 | * Tour:: Whistle-stop tour of the various bits | |
101 | * System configuration:: Integrating TrIPE with the rest of your OS | |
102 | * Networking:: How TrIPE fits into your network | |
103 | * Cryptography:: Key management and cryptography | |
104 | * Setting up:: How to install TrIPE and make it run | |
105 | ||
106 | Other useful information | |
107 | * Security properties:: TrIPE is secure, honest; here's why | |
108 | * Comparison:: How TrIPE compares to other VPN systems | |
109 | ||
110 | * Index:: Index of interesting things | |
111 | ||
112 | @detailmenu | |
113 | --- The Detailed Node Listing --- | |
114 | ||
115 | Introduction | |
116 | ||
117 | * About TrIPE:: What TrIPE is and what it does | |
118 | * About this manual:: What this manual tries to do, and who | |
119 | should read it | |
120 | ||
121 | Installation | |
122 | ||
123 | * Prerequisites:: What you need before you can start | |
124 | * Building:: How to compile it from the source code | |
125 | * From Git:: How to build directly from | |
126 | version-controlled sources | |
127 | * What goes where:: Where everything gets installed | |
128 | ||
129 | Where everything is installed | |
130 | ||
131 | * Installation dirs:: Directories in which files are installed | |
132 | * File locations:: Which files are put where | |
133 | ||
134 | A quick tour of TrIPE | |
135 | ||
136 | * Server:: The main VPN server | |
137 | * Key utility:: Generating and distributing keys | |
138 | * Startup script:: Starting the server and its little friends | |
139 | * Peer services:: Establishing and configuring connections | |
140 | * Config Makefile:: Using GNU Make to make life easier | |
141 | ||
142 | System configuration | |
143 | ||
144 | * Port:: | |
145 | * Users:: | |
146 | ||
147 | Networking concepts | |
148 | ||
149 | * Networks and addressing:: How TrIPE thinks networks are structured | |
150 | * Tunnels and routing:: How networks are joined together | |
151 | * Connection styles:: Ways of setting up connections | |
152 | * Firewall considerations:: How TrIPE affects your firewall | |
153 | ||
154 | Network structure and addressing | |
155 | ||
156 | * Addressing example:: A worked example | |
157 | ||
158 | Tunnels and routing | |
159 | ||
160 | * Routing example:: A worked example | |
161 | ||
162 | Security | |
163 | ||
164 | * Host security:: Security aspects of running TrIPE on | |
165 | your host | |
166 | * Crypto security:: TrIPE's use of cryptography has a | |
167 | mathematical proof of security | |
168 | * Not X.509:: TrIPE doesn't use X.509 because X.509 | |
169 | sucks | |
170 | ||
171 | Pay no attention to the man behind the curtain | |
172 | ||
173 | * Key management:: a section which hasn't been written | |
174 | ||
175 | @end detailmenu | |
176 | @end menu | |
177 | ||
178 | @end ifnottex | |
179 | ||
180 | @c -------------------------------------------------------------------------- | |
181 | @node Copying, Introduction, Top, Top | |
182 | @unnumbered The GNU General Public License | |
183 | ||
184 | @include gpl.texi | |
185 | ||
186 | @node Introduction, Installing, Copying, Top | |
187 | @unnumbered Introduction | |
188 | ||
189 | This chapter explains very briefly what TrIPE is and what this manual | |
190 | aims to tell you about it. | |
191 | ||
192 | @menu | |
193 | * About TrIPE:: What TrIPE is and what it does | |
194 | * About this manual:: What this manual tries to do, and who | |
195 | should read it | |
196 | @end menu | |
197 | ||
198 | @node About TrIPE, About this manual, Introduction, Introduction | |
199 | @unnumberedsec About TrIPE | |
200 | ||
201 | TrIPE is a TrIPE is a Virtual Private Network (VPN) implementation. It uses | |
202 | cryptography to protect network packets from being read or tampered with | |
203 | as they travel over hostile networks (e.g., the Internet). The effect | |
204 | of this is that you can connect together geographically-separated | |
205 | networks of machines and use network protocols which would be unsafe to | |
206 | use over public networks. | |
207 | ||
208 | The name `TrIPE' stands for `Trivial IP Encryption'. Unfortunately, | |
209 | while the TrIPE network protocol is still fairly simple (and this is one | |
210 | of TrIPE's conspicuous advantages over other VPN systems), the software | |
211 | suite which implements it is not. Over time, the original single server | |
212 | has acquired various strangely-shaped extensions and add-on-services in | |
213 | order to solve various problems, and even given fairly detailed | |
214 | descriptions of all of the individual pieces it can be difficult to see | |
215 | how to fit them together in order to actually do anything useful. | |
216 | ||
217 | The TrIPE software runs entirely in user mode. It does not require any | |
218 | kernel modifications. | |
219 | ||
220 | @node About this manual, , About TrIPE, Introduction | |
221 | @unnumberedsec About this manual | |
222 | @cindex Menezes, Alfred J. | |
223 | @cindex van Oorschott, Paul C. | |
224 | @cindex Vanstone, Scott A. | |
225 | ||
226 | This manual provides an overview of the TrIPE software suite. The | |
227 | individual components are described in their respective reference manual | |
228 | pages. This page exists to provide a picture for how the various pieces | |
229 | fit together and how to use them effectively. It presents a number of | |
230 | worked examples, but it's not intended to be used as a `cookbook'; TrIPE | |
231 | is a complicated system, and the author believes that you're less likely | |
232 | to become confused by it if you understand how its various bits fit | |
233 | together rather than following canned recipes which don't quite match | |
234 | your particular circumstances. | |
235 | ||
236 | This manual is intended for network administrators who are comfortable | |
237 | with the fundamentals of IP networking and routing. It assumes a | |
238 | reasonable level of knowledge of how to configure network interfaces and | |
239 | routing. It doesn't assume a strong background in cryptography, though | |
240 | a good grounding won't hurt; the author recommends the @cite{Handbook of | |
241 | Applied Cryptography} by Alfred Menezes, Paul van Oorschott and Scott | |
242 | Vanstone, which is published by CRC Press, or available online at | |
243 | @url{http://www.cacr.math.uwaterloo.ca/hac/}. | |
244 | ||
245 | Unlike other Info manuals, this one isn't intended to be a complete | |
246 | reference to the system. That information is provided in traditional | |
247 | Unix-style manual pages, which are easier to consult quickly. Instead, | |
248 | it provides a conceptual overview of the system together with examples | |
249 | to help you get started. | |
250 | ||
251 | @c -------------------------------------------------------------------------- | |
252 | @node Installing, Tour, Introduction, Top | |
253 | @chapter Installation | |
254 | ||
255 | This chapter describes how to install TrIPE. You should probably read | |
256 | it even if you obtained TrIPE as a binary package, say as part of a | |
257 | Linux distribution. | |
258 | ||
259 | @menu | |
260 | * Prerequisites:: What you need before you can start | |
261 | * Building:: How to compile it from the source code | |
262 | * From Git:: How to build directly from | |
263 | version-controlled sources | |
264 | * What goes where:: Where everything gets installed | |
265 | @end menu | |
266 | ||
267 | @node Prerequisites, Building, Installing, Installing | |
268 | @section Prerequisites | |
269 | @cindex prerequisites | |
270 | ||
271 | There are a number of other pieces of software you'll need to be able to | |
272 | build and run the TrIPE suite. Some of them are, strictly speaking, | |
273 | optional, in the sense that only part of the suite depends on them and | |
274 | the rest will continue functioning properly. But the various parts of | |
275 | TrIPE are intended to work together, and you'll have an easier time of | |
276 | it if they're all fully operational. In particular, most of this manual | |
277 | assumes that the whole suite is available: you will have to read the | |
278 | individual manpages to find out how to configure the system properly if | |
279 | you want to be clever. | |
280 | ||
281 | Anyway, in order to be able to use TrIPE, you'll need the following. | |
282 | ||
283 | @table @asis | |
284 | @item @strong{mLib}, at least version 2.1.0 | |
285 | @cindex mLib | |
286 | A library of C utilities. | |
287 | ||
288 | @item @strong{Catacomb}, at least version 2.1.1 | |
289 | @cindex Catacomb | |
290 | A cryptographic library. | |
291 | ||
292 | @item @strong{Python}, at least version 2.4 | |
293 | @cindex van Rossum, Guido | |
294 | @cindex Python | |
295 | Python is a popular high-level language designed by and under the | |
296 | lifelong benevolent dictatorship of Guido van Rossum; many of the | |
297 | peripheral parts of TrIPE are written in Python. | |
298 | ||
299 | @item @strong{mLib-python} | |
300 | Python bindings for mLib; necessary for the @strong{connect} and | |
301 | @strong{watch} services which make dynamic connections work | |
302 | (@pxref{Connection styles}), and the graphical monitor | |
303 | @strong{tripemon}. | |
304 | ||
305 | @item @strong{catacomb-python} | |
306 | Python bindings for Catacomb; necessary for the @strong{tripe-keys} | |
307 | key-distribution utility: @pxref{Key management}. | |
308 | ||
309 | @item @strong{python-cdb}, at least version 0.32 | |
310 | @cindex Bernstein, Daniel J. | |
311 | @cindex CDB | |
312 | @cindex Pomraning, M. J. | |
313 | @cindex von Leitner, Felix | |
314 | @cindex @strong{libowfat} | |
315 | A Python interface for constructing and using constant databases (CDB). | |
316 | CDB provides fast lookup and atomic updates, at the cost of having to | |
317 | rebuild databases from scratch in order to make changes. The CDB format | |
318 | was designed by D. J. Bernstein; the Python interface was written by | |
319 | M. J. Pomraning using code from Felix von Leitner's @strong{libowfat} | |
320 | and D. J. Bernstein's public-domain CDB implementation. CDB is required | |
321 | by the @strong{connect} and @strong{watch} services. | |
322 | ||
323 | @item @strong{GTK+} and @strong{pygtk}, at least version 2.12 | |
324 | @cindex GTK+ | |
325 | @cindex Mattis, Peter | |
326 | @cindex Kimball, Spencer | |
327 | @cindex MacDonald, Josh | |
328 | @cindex GNOME | |
329 | @cindex @strong{pygtk} | |
330 | @cindex Henstridge, James | |
331 | @cindex Dahlin, Johan | |
332 | GTK+ is a user-interface library, originally written by Peter Mattis, | |
333 | Spencer Kimball and Josh MacDonald; it is used by various desktops | |
334 | including GNOME. @strong{pygtk} is a set of Python bindings for GTK+ | |
335 | originally created by James Henstridge and now maintained by Johan | |
336 | Dahlin. These are needed by the graphical monitor @strong{tripemon}. | |
337 | @end table | |
338 | ||
339 | It may also be useful to have the following items. | |
340 | ||
341 | @table @asis | |
342 | @item The Codespeak @strong{py} library | |
343 | @cindex Codespeak | |
344 | @cindex py | |
345 | @cindex greenlet | |
346 | @cindex coroutine | |
347 | @c FIXME: need attribution | |
348 | The Codespeak @strong{py} library contains an implementation of | |
349 | coroutines, which it calls `greenlets'. Coroutines are used by various | |
350 | parts of the suite, though they will make use of an inefficient | |
351 | implementation in terms of threads if @strong{py} isn't available. | |
352 | @end table | |
353 | ||
354 | @node Building, From Git, Prerequisites, Installing | |
355 | @section Building from a source distribution | |
356 | @cindex tarball | |
357 | @cindex building from source | |
358 | @cindex @var{configdir} | |
359 | ||
360 | If you have a source tarball for TrIPE, you can build the software suite | |
361 | as follows. | |
362 | ||
363 | @enumerate | |
364 | @item | |
365 | Unpack the sources. The tarball should have a name like | |
366 | @file{tripe-@var{version}.tar.gz}. Type | |
367 | ||
368 | @example | |
369 | gzip -dc tripe-@var{version}.tar.gz | tar xvf - | |
370 | @end example | |
371 | ||
372 | to unpack the sources. This will create a subdirectory (the @dfn{source | |
373 | directory}) of your current working directory called | |
374 | @file{tripe-@var{version}} and containing the sources. | |
375 | ||
376 | @item | |
377 | Create a directory (the @dfn{build directory}) for the built files to | |
378 | go. I usually create a subdirectory @file{build} of the source | |
379 | directory, though it needn't even be part of the same filesystem as the | |
380 | source directory. You can have the build directory be the same as the | |
381 | source directory if you like, but I don't really recommend it. Make the | |
382 | build directory be your working directory. | |
383 | ||
384 | @item | |
385 | Run | |
386 | ||
387 | @example | |
388 | @var{source-directory}/configure | |
389 | @end example | |
390 | ||
391 | to set up the build directory. (Here, @var{source-directory} is a | |
392 | (possibly relative) path to the source directory from your chosen build | |
393 | directory; for example, with my usual choice of build directory, I can | |
394 | just type @samp{../configure}. | |
395 | ||
396 | You can provide the @file{configure} script with command-line options. | |
397 | The most important options are as follows. | |
398 | ||
399 | @table @code | |
400 | @item --prefix=@var{prefix} | |
401 | Arranges to install the software under the directory @var{prefix} -- so | |
402 | executables will end up in @file{@var{prefix}/bin} and so on. The | |
403 | default is @file{/usr/local}. | |
404 | ||
405 | @item --with-configdir=@var{configdir} | |
406 | Arranges to store and look for configuration data in @var{configdir}. | |
407 | The default is @var{localstatedir}/tripe, where @var{localstatedir} is | |
408 | itself set by the @option{--localstatedir} option and defaults to | |
409 | @file{@var{prefix}/var}. | |
410 | @end table | |
411 | ||
412 | @xref{Installation dirs}, for a table of installation directories used | |
413 | by TrIPE and the @file{configure} options for setting them; run | |
414 | ||
415 | @example | |
416 | @var{source-directory}/configure --help | |
417 | @end example | |
418 | ||
419 | for a full list of options you can set. | |
420 | ||
421 | @item | |
422 | Run | |
423 | ||
424 | @example | |
425 | make | |
426 | @end example | |
427 | ||
428 | This will build everything you need. | |
429 | ||
430 | @item | |
431 | (Optional, but recommended.) Run | |
432 | ||
433 | @example | |
434 | make check | |
435 | @end example | |
436 | ||
437 | to test that what you've just built actually works. The test suite | |
438 | isn't anywhere near as comprehensive as I'd like it to be, but it's a | |
439 | start. (Contributions are welcome!) | |
440 | ||
441 | @item | |
442 | Run | |
443 | ||
444 | @example | |
445 | make install | |
446 | @end example | |
447 | ||
448 | (probably as @user{root}) to install most things into their proper | |
449 | places. | |
450 | ||
451 | @item | |
452 | The TrIPE suite comes with a script to be run at boot time | |
453 | (@pxref{Startup script}). Because systems vary so much in their startup | |
454 | behaviour, TrIPE doesn't attempt to install this anywhere. This script | |
455 | ends up in @file{init/tripe-init} in the build directory. | |
456 | ||
457 | On many systems, you should copy it to @file{/etc/init.d} (maybe | |
458 | @file{/etc/rc.d/init.d} on Red Hat systems; maybe @file{/sbin/init.d} on | |
459 | some proprietary Unix systems) and place symbolic links in the | |
460 | @file{/etc/rc@var{?}.d} (maybe @file{/etc/rc.d/rc@var{?}.d} or | |
461 | @file{/sbin/rc@var{?}.d}) directories. | |
462 | ||
463 | On traditional BSD systems, it's probably best to copy the script to | |
464 | @file{prefix}/sbin/tripe-init, and run | |
465 | ||
466 | @example | |
467 | @var{prefix}/tripe-init start | |
468 | @end example | |
469 | ||
470 | from your @file{/etc/rc.local} script. | |
471 | @end enumerate | |
472 | ||
473 | @node From Git, What goes where, Building, Installing | |
474 | @section How to build TrIPE from the sources under version control | |
475 | @cindex Git | |
476 | @cindex Torvalds, Linus | |
477 | @cindex Hamano, Junio | |
478 | ||
479 | The author maintains the TrIPE sources using Git, a distributed version | |
480 | control system originally designed and implemented by Linus Torvalds and | |
481 | now maintained by a community under the guidance of Junio Hamano. | |
482 | ||
483 | You can obtain a copy of the project history by running | |
484 | ||
485 | @example | |
486 | git clone git://git.distorted.org.uk/~mdw/tripe | |
487 | @end example | |
488 | ||
489 | This won't have a @file{configure} script or the @file{Makefile.in} | |
490 | files provided in the source bundle. You'll need a number of additional | |
491 | tools. | |
492 | ||
493 | @table @asis | |
494 | @item GNU Autoconf, at least version 2.61 | |
495 | @cindex Autoconf | |
496 | GNU Autoconf builds @file{configure} scripts from @strong{m4} | |
497 | descriptions. | |
498 | ||
499 | @item GNU Automake, at least version 1.8 | |
500 | @cindex Automake | |
501 | GNU Automake builds @file{Makefile.in} files from a high-level | |
502 | declarative description of what needs building. | |
503 | ||
504 | @item GNU Libtool, at least version 2.2 | |
505 | @cindex Libtool | |
506 | GNU Libtool assists with the complex and messy business of dealing with | |
507 | shared libraries on many different platforms. | |
508 | ||
509 | @item Autoconf archive, from 2007--05--12 or later | |
510 | @cindex Autoconf archive | |
511 | A collection of useful Autoconf macros. You must ensure that the | |
512 | @command{aclocal} command can find these macros, e.g., by adding the | |
513 | archive installation directory to the file | |
514 | @file{/usr/share/aclocal/dirlist}. @xref{Macro search path,,, automake, | |
515 | GNU Automake}. | |
516 | ||
517 | @item Common Files Distribution, at least version 1.3.4 | |
518 | @cindex cfd | |
519 | @cindex Common Files Distribution | |
520 | The Common Files Distribution collects together a number of files which | |
521 | need to be included in many projects, and provides tools for managing | |
522 | them. | |
523 | @end table | |
524 | ||
525 | @cindex mdw-setup | |
526 | If you have these properly installed, it should be sufficient to run | |
527 | ||
528 | @example | |
529 | mdw-setup | |
530 | @end example | |
531 | ||
532 | in the source tree before following the instructions for building from a | |
533 | source distribution: @pxref{Building}. | |
534 | ||
535 | @node What goes where, , From Git, Installing | |
536 | @section Where everything is installed | |
537 | ||
538 | This section provides a handy description of where files are placed by | |
539 | TrIPE's installation system. | |
540 | ||
541 | @menu | |
542 | * Installation dirs:: Directories in which files are installed | |
543 | * File locations:: Which files are put where | |
544 | @end menu | |
545 | ||
546 | @node Installation dirs, File locations, What goes where, What goes where | |
547 | @subsection Installation directories | |
548 | As is usual with the GNU build system, the layout of the installed files | |
549 | is highly configurable. The following table describes all of the | |
550 | installation directories, and the @file{configure}-script arguments to | |
551 | modify them. | |
552 | ||
553 | @multitable @columnfractions 0.16 0.29 0.3 0.23 | |
554 | @headitem Directory name | |
555 | @tab Default | |
556 | @tab Debian | |
557 | @tab Option | |
558 | ||
559 | @item @t{@var{prefix}} | |
560 | @tab @t{/usr/local} | |
561 | @tab @t{/usr} | |
562 | @tab @t{-@w{}-prefix} | |
563 | ||
564 | @item @t{@var{exec-prefix}} | |
565 | @tab @t{@var{prefix}} | |
566 | @tab @t{/usr} | |
567 | @tab @t{-@w{}-exec-prefix} | |
568 | ||
569 | @item @t{@var{bindir}} | |
570 | @tab @t{@var{exec-prefix}/bin} | |
571 | @tab @t{/usr/bin} | |
572 | @tab @t{-@w{}-bindir} | |
573 | ||
574 | @item @t{@var{sbindir}} | |
575 | @tab @t{@var{exec-prefix}/sbin} | |
576 | @tab @t{/usr/sbin} | |
577 | @tab @t{-@w{}-sbindir} | |
578 | ||
579 | @item @t{@var{libdir}} | |
580 | @tab @t{@var{exec-prefix}/lib} | |
581 | @tab @t{/usr/lib} | |
582 | @tab @t{-@w{}-libdir} | |
583 | ||
584 | @item @t{@var{libexecdir}} | |
585 | @tab @t{@var{exec-prefix}/libexec} | |
586 | @tab @t{/usr/lib} | |
587 | @tab @t{-@w{}-libexecdir} | |
588 | ||
589 | @item @t{@var{datarootdir}} | |
590 | @tab @t{@var{prefix}/share} | |
591 | @tab @t{/usr/share} | |
592 | @tab @t{-@w{}-datarootdir} | |
593 | ||
594 | @item @t{@var{datadir}} | |
595 | @tab @t{@var{datarootdir}} | |
596 | @tab @t{/usr/share} | |
597 | @tab @t{-@w{}-datadir} | |
598 | ||
599 | @item @t{@var{sysconfdir}} | |
600 | @tab @t{@var{prefix}/etc} | |
601 | @tab @t{/etc} | |
602 | @tab @t{-@w{}-sysconfdir} | |
603 | ||
604 | @item @t{@var{configdir}} | |
605 | @tab @t{@var{prefix}/var/tripe} | |
606 | @tab @t{/etc/tripe} | |
607 | @tab @t{-@w{}-with-configdir} | |
608 | ||
609 | @item @t{@var{mandir}} | |
610 | @tab @t{@var{datarootdir}/man} | |
611 | @tab @t{/usr/share/man} | |
612 | @tab @t{-@w{}-mandir} | |
613 | ||
614 | @item @t{@var{infodir}} | |
615 | @tab @t{@var{datarootdir}/info} | |
616 | @tab @t{/usr/share/info} | |
617 | @tab @t{-@w{}-infodir} | |
618 | ||
619 | @item @t{@var{docdir}} | |
620 | @tab @t{@var{datarootdir}/doc/@/tripe} | |
621 | @tab @t{/usr/share/doc/tripe} | |
622 | @tab @t{-@w{}-docdir} | |
623 | ||
624 | @item @t{@var{socketdir}} | |
625 | @tab @t{.} | |
626 | @tab @t{/var/run} | |
627 | @tab @t{-@w{}-with-socketdir} | |
628 | ||
629 | @item @t{@var{pythondir}} | |
630 | @tab Depends on Python installation | |
631 | @tab @t{/usr/lib/@/python@var{ver}/@/site-packages} | |
632 | @tab None | |
633 | ||
634 | @item @t{@var{wiresharkdir}} | |
635 | @tab Depends on Wireshark installation | |
636 | @tab @t{/usr/lib/@/wireshark/@/plugins} | |
637 | @tab @t{-@w{}-with-wireshark} | |
638 | @end multitable | |
639 | ||
640 | In addition, there are some configure-time settings which affect the | |
641 | locations of individual files. These are as follows. | |
642 | ||
643 | @multitable @columnfractions 0.2 0.3 0.27 0.23 | |
644 | @headitem Directory name | |
645 | @tab Default | |
646 | @tab Debian | |
647 | @tab Option | |
648 | ||
649 | @item @t{@var{logfile}} | |
650 | @tab @t{./tripe.log} | |
651 | @tab @t{/var/log/tripe.log} | |
652 | @tab @t{-@w{}-with-logfile} | |
653 | ||
654 | @item @t{@var{pidfile}} | |
655 | @tab @t{./tripectl.pid} | |
656 | @tab @t{/var/run/tripectl.pid} | |
657 | @tab @t{-@w{}-with-pidfile} | |
658 | ||
659 | @item @t{@var{initconfig}} | |
660 | @tab @t{@var{sysconfdir}/tripe.conf} | |
661 | @tab @t{/etc/default/tripe} | |
662 | @tab @t{-@w{}-with-initconfig} | |
663 | @end multitable | |
664 | ||
665 | The relative pathnames shown above are relative to the working directory | |
666 | of the process. Most TrIPE programs set their working directory to | |
667 | @file{@var{configdir}} when they start up, unless a different directory | |
668 | is specified on the command line. | |
669 | ||
670 | @node File locations, , Installation dirs, What goes where | |
671 | @subsection File locations | |
672 | ||
673 | The following table shows the locations of all the files in the | |
674 | distribution. | |
675 | ||
676 | @table @t | |
677 | @item @var{infodir} | |
678 | @t{tripe.info} -- this manual, in GNU Info format. | |
679 | ||
680 | (There may possibly be other files, depending on whether | |
681 | @command{makeinfo} decided to split it into parts). Prebuilt binary | |
682 | packages may have compressed the info manual. | |
683 | ||
684 | @item @var{mandir} | |
685 | The various manual pages. Manual pages are placed into sections | |
686 | (following the Linux numbering convention). Manual pages in section | |
687 | @var{n} are placed in @file{@var{mandir}/man@var{n}}. Prebuilt binary | |
688 | packages may have compressed the manual pages. | |
689 | ||
690 | @item @var{docdir} | |
691 | @t{tripe.pdf} -- this manual, in Adobe PDF. @* | |
692 | @t{tripe.html/index.html} (and others) -- this manual, in HTML. | |
693 | ||
694 | Prebuilt binary packages may have compressed the PDF file. | |
695 | ||
696 | @item @var{bindir} | |
697 | @t{pkstream} -- a utility for transporting UDP packets over streams @* | |
698 | @t{tripe-uslip} -- a utility for testing the @manpage{tripe, 8} server@* | |
699 | @t{tripemon} -- a graphical monitor program for TrIPE @* | |
700 | @t{pathmtu} -- a utility for determining the path-MTU to a given host @* | |
701 | @t{tripe-mitm} -- a hostile proxy for the TrIPE protocol @* | |
702 | @t{tripectl} -- a client program for communicating with the | |
703 | @manpage{tripe, 8} server | |
704 | ||
705 | Some of these programs may be missing from your distribution. The | |
706 | @file{tripe-uslip} and @file{tripe-mitm} programs aren't particularly | |
707 | useful in day-to-day operations, and aren't considered further in this | |
708 | manual. | |
709 | ||
710 | @item @var{sbindir} | |
711 | @t{tripe} -- the main server @* | |
712 | @t{tripe-newpeers} -- build the peer database from text configuration @* | |
713 | @t{tripe-keys} -- a utility for generating and distributing keys @* | |
714 | @t{tripe-ifup} -- a script for configuring network interfaces | |
715 | ||
716 | @item @var{libexecdir}/tripe | |
717 | @t{tripe-privhelper} -- a program used internally by the | |
718 | @manpage{tripe, 8} server to open network-tunnel devices. The server | |
719 | drops @user{root} privileges early on during its initialization; before | |
720 | doing so, it starts a @t{tripe-privhelper} process. | |
721 | ||
722 | @t{services/connect} and @t{services/watch} -- ancillary | |
723 | peer-management services described later. | |
724 | @c FIXME want a cross-reference | |
725 | ||
726 | @item @var{libdir}/pkgconfig | |
727 | @t{tripe.pc} -- a @manpage{pkg-config, 1} file, which allows other | |
728 | packages to find out how TrIPE has been installed. | |
729 | ||
730 | @item @var{pythondir} | |
731 | @t{tripe.py} -- Python module for communicating with @manpage{tripe, | |
732 | 8} server @* | |
733 | @t{rmcr.py} -- Python module implementing coroutines in terms of | |
734 | threads | |
735 | ||
736 | There may also be @file{.pyc} and @file{.pyo} files installed here. | |
737 | ||
738 | @item @var{wiresharkdir} | |
739 | @t{tripe.so} -- Wireshark plugin for dissecting TrIPE protocol traces | |
740 | ||
741 | There may also be @file{.a} and @file{.la} files installed here. | |
742 | ||
743 | @item @var{configdir} | |
744 | @t{peers.d/10base} -- base configuration for peers database. | |
745 | @c FIXME want a cross-reference | |
746 | @end table | |
747 | ||
748 | @c -------------------------------------------------------------------------- | |
749 | @node Tour, System configuration, Installing, Top | |
750 | @chapter A quick tour of TrIPE | |
751 | ||
752 | The TrIPE suite consists of a number of separate programs, each of which | |
753 | is configured separately. This chapter provides a brief tour of the | |
754 | various components, with particular emphasis on the various | |
755 | configuration files they read. | |
756 | ||
757 | @menu | |
758 | * Server:: The main VPN server | |
759 | * Key utility:: Generating and distributing keys | |
760 | * Startup script:: Starting the server and its little friends | |
761 | * Peer services:: Establishing and configuring connections | |
762 | * Config Makefile:: Using GNU Make to make life easier | |
763 | @end menu | |
764 | ||
765 | @node Server, Key utility, Tour, Tour | |
766 | @section The main server | |
767 | @cindex @manpage{tripe, 8} server | |
768 | @cindex keyring | |
769 | ||
770 | The server @manpage{tripe, 8} is the heart of the TrIPE system. It is | |
771 | responsible for exchanging encrypted network packets with other hosts. | |
772 | As part of this, it authenticates its peers (to ensure that it's | |
773 | communicating with the right ones), agrees session keys, and performs | |
774 | various other administrative tasks. | |
775 | ||
776 | The server has very little in the way of long-term configuration. | |
777 | ||
778 | The only external files it reads are its @dfn{keyrings}. There are two | |
779 | keyrings: the @dfn{private keyring} contains the server's private key, | |
780 | which it uses to prove its identity to its peers; and the @dfn{public | |
781 | keyring} contains other servers' public keys, which are used to verify | |
782 | their identities. The keyrings also contain a small quantity of | |
783 | configuration information, in particular specifying which cryptographic | |
784 | algorithms the server should use. You can maintain the keyrings | |
785 | manually if you like, using the @manpage{key, 1} program included in the | |
786 | Catacomb distribution: detailed information about the attributes TrIPE | |
787 | expects on its keys is provided in the @manpage{tripe, 8} manpage. But | |
788 | it's easier to use the @manpage{tripe-keys, 8} system (@pxref{Key | |
789 | management}) to maintain the keyrings. | |
790 | ||
791 | Apart from the two keyrings, the server obtains configuration data from | |
792 | two sources. | |
793 | ||
794 | @enumerate | |
795 | @item | |
796 | It accepts a number of switches on its command line. If you start the | |
797 | server manually, you can provide command-line options then. However, | |
798 | the server is usually started by the startup script script, which has its own | |
799 | configuration file: @pxref{Startup script}. The server command line is | |
800 | described in full in @manpage{tripe, 8}. | |
801 | ||
802 | @item | |
803 | It provides an interactive @emph{administration interface} through which | |
804 | other processes can issue commands and read status information | |
805 | dynamically. You can use the @manpage{tripectl, 1} program to issue | |
806 | administrative commands; see @manpage{tripe-admin, 5} for full details | |
807 | about the commands available. | |
808 | @end enumerate | |
809 | ||
810 | @node Key utility, Startup script, Server, Tour | |
811 | @section Key management utility | |
812 | @cindex @manpage{tripe-keys, 8} utility | |
813 | @cindex @file{tripe-keys.master} | |
814 | @cindex @file{tripe-keys.conf} | |
815 | @cindex key generation | |
816 | @cindex key distribution | |
817 | ||
818 | Key management and distribution is a complicated topic, dealt with fully | |
819 | in its own chapter. | |
820 | ||
821 | The @manpage{tripe-keys, 8} utility implements a simple key distribution | |
822 | system. It works like this. A trusted individual or group maintains a | |
823 | master configuration file, typically called @file{tripe-keys.master}. | |
824 | ||
825 | From this master file, @manpage{tripe-keys, 8} constructs a file | |
826 | @file{tripe-keys.conf} which can be distributed (e.g., by making it | |
827 | available via HTTP or FTP) to the maintainers of the other participating | |
828 | peers. The @manpage{tripe-keys, 8} utility assists with key generation | |
829 | and secure distribution of public keys. | |
830 | ||
831 | For full details, @pxref{Key management}. | |
832 | ||
833 | @node Startup script, Peer services, Key utility, Tour | |
834 | @section The startup script | |
835 | @cindex peer script | |
836 | ||
837 | The startup script's name and location is system specific. If you built | |
838 | the suite from source, then installing it appropriately is left to you. | |
839 | The Debian GNU/Linux package places the script in | |
840 | @file{/etc/init.d/tripe}; other possible locations are | |
841 | @file{/etc/rc.d/init.d/tripe} (e.g., Red Hat, AIX), | |
842 | @file{/sbin/init.d/tripe} (e.g., SuSE, HP-UX) or | |
843 | @file{/usr/local/sbin/tripe-init} (BSD, recommended). | |
844 | ||
845 | The startup script is a Bourne shell script. It sources a configuration | |
846 | file when it runs; this file's location is also somewhat variable. The | |
847 | default location chosen by the @file{configure} script is | |
848 | @file{/etc/tripe.conf}; however, the Debian package places it in | |
849 | @file{/etc/default/tripe}. | |
850 | ||
851 | The startup script invokes @file{tripe} via the @file{tripectl} client, | |
852 | which writes messages from the server to a logfile, and provides some | |
853 | other useful services. | |
854 | ||
855 | As well as starting the server, the startup script also runs all of the | |
856 | scripts found in the @file{@var{configdir}/services} and | |
857 | @file{@var{configdir}/peers} directories. The @file{services} scripts | |
858 | are invoked as | |
859 | @example | |
860 | @var{script} --daemon --startup | |
861 | @end example | |
862 | while the @file{peers} scripts are not passed arguments. | |
863 | ||
864 | The intent is that symbolic links to programs providing useful services | |
865 | can be placed in @file{@var{configdir}/services} so that they'll start | |
866 | automatically when @manpage{tripe, 8} starts. The options | |
867 | @option{--daemon} and @option{--startup} are common to all service | |
868 | providers (see @manpage{tripe-service, 7} for details). | |
869 | ||
870 | The @file{@var{configdir}/peers} directory is intended for scripts which | |
871 | establish connections with specific peers. A simple example script | |
872 | might be something like this. | |
873 | ||
874 | @example | |
875 | #! /bin/sh | |
876 | set -e | |
877 | ||
878 | tripectl ADD vampire INET 172.29.198.1 4070 | |
879 | ifname=$(tripectl IFNAME vampire) | |
880 | ifconfig $ifname 172.29.199.129 pointopoint 172.29.199.4 | |
881 | route add -net 172.29.199.0/24 gw 172.29.199.4 dev $ifname | |
882 | @end example | |
883 | ||
884 | Stashing this file as @file{@var{configdir}/peers/vampire} would cause | |
885 | the server to establish a connection with @code{vampire} on startup, and | |
886 | configure the tunnel interface accordingly. Configuration using | |
887 | @file{peers} scripts is fairly versatile but tedious; the peer services | |
888 | provide a better approach. This manual won't discuss @file{peers} | |
889 | scripts any further. | |
890 | ||
891 | @node Peer services, Config Makefile, Startup script, Tour | |
892 | @section Peer services | |
893 | @cindex service | |
894 | @cindex ancillary service | |
895 | @cindex @manpage{connect, 8} | |
896 | @cindex @manpage{watch, 8} | |
897 | @cindex @manpage{tripe-ifup, 8} | |
898 | @cindex peer database | |
899 | @cindex @manpage{tripe-newpeers, 8} | |
900 | ||
901 | As mentioned earlier (@pxref{Server}), the main server provides an | |
902 | administration interface which accepts configuration commands and | |
903 | provides status information. This interface can be extended by | |
904 | ancillary @emph{services} which can implement additional commands and | |
905 | react to changes in the server's status. | |
906 | ||
907 | There are two services for managing connections with other peers. | |
908 | ||
909 | @table @command | |
910 | @item connect | |
911 | A fairly simple service for requesting the setup of new connections. | |
912 | ||
913 | @item watch | |
914 | A more complex service, which reacts to connections being | |
915 | established and terminated (e.g., by configuring network interfaces). | |
916 | @end table | |
917 | ||
918 | In addition, there is a shell script @manpage{tripe-ifup, 8} which | |
919 | actually does the job of configuring network interfaces. Currently, | |
920 | this script only works on Linux; I'll add versions for other systems as | |
921 | they're contributed. | |
922 | ||
923 | These services obtain information about the available peers and how to | |
924 | establish and maintain connections to them from a @dfn{peer database}, | |
925 | stored in @file{@var{configdir}/peers.cdb}. This database is | |
926 | constructed from textual input files by a program | |
927 | @manpage{tripe-newpeers, 8}. The services and script obtain all of | |
928 | their configuration from the database, and don't examine the source | |
929 | files at all. | |
930 | ||
931 | @node Config Makefile, , Peer services, Tour | |
932 | @section Managing TrIPE configuration using GNU Make | |
933 | @cindex makefile | |
934 | ||
935 | I use a simple Makefile to update my TrIPE configuration after making | |
936 | changes. I've found it easiest to put configuration data for individual | |
937 | peers in separate files under @file{peers.d}, and use GNU Make's | |
938 | @code{wildcard} function to keep track of them: @xref{Wildcard | |
939 | Function,, The Function @code{wildcard}, make, GNU @code{make}}. | |
940 | ||
941 | My Makefile is as follows. | |
942 | ||
943 | @example | |
944 | ### Makefile for tripe stuff | |
945 | ||
946 | TARGETS = peers.cdb | |
947 | all: $(TARGETS) | |
948 | ||
949 | clean::; rm -f $(TARGETS) | |
950 | .PHONY: clean | |
951 | ||
952 | ## The peers database | |
953 | peers.cdb: $(wildcard peers.d/[!@@]*[!~#]) | |
954 | tripe-newpeers -c $@@ $^ | |
955 | ||
956 | ## Keyring stuff | |
957 | update: | |
958 | tripe-keys update | |
959 | chgrp tripe keyring keyring.pub | |
960 | chmod 640 keyring keyring.pub | |
961 | ||
962 | .PHONY: update | |
963 | @end example | |
964 | ||
965 | It's intended to be placed into the @file{@var{configdir}} directory and | |
966 | invoked by @user{root}. It assumes that a @file{tripe-keys.conf} file | |
967 | has been placed alongside. Now I can run | |
968 | ||
969 | @example | |
970 | make | |
971 | @end example | |
972 | ||
973 | after changing or adding peers, and | |
974 | ||
975 | @example | |
976 | make update | |
977 | @end example | |
978 | ||
979 | to update my public keyring. The @manpage{tripe, 8} server and the | |
980 | various peer services will notice the new keyring and peer database and | |
981 | reload them automatically. | |
982 | ||
983 | @c -------------------------------------------------------------------------- | |
984 | @node System configuration, Networking, Tour, Top | |
985 | @chapter System configuration | |
986 | ||
987 | This chapter explains how to fit TrIPE into the rest of your host's | |
988 | operating system. It won't go into serious network configuration: | |
989 | that's covered by the next chapter, @pxref{Networking}. | |
990 | ||
991 | @menu | |
992 | * Port:: | |
993 | * Users:: | |
994 | @end menu | |
995 | ||
996 | @node Port, Users, System configuration, System configuration | |
997 | @section Port number | |
998 | ||
999 | @cindex Spotify | |
1000 | The @manpage{tripe, 8} server uses a single UDP port. By default, this | |
1001 | is port 4070, which has been allocated to TrIPE by the IANA -- so, in | |
1002 | theory, there shouldn't be any conflicts. (TCP port 4070 is also | |
1003 | allocated to TrIPE, though it makes no use of TCP whatsoever. This is | |
1004 | probably a good thing, since TCP port 4070 is used by the Spotify audio | |
1005 | network. This doesn't cause any conflict with TrIPE, though it may | |
1006 | incline some over-zealous network administrators to close off TrIPE's | |
1007 | UDP port unnecessarily.) | |
1008 | ||
1009 | It's possible to use a different port number. This might be reasonable | |
1010 | if you know that port 4070 is being used by some other server, or is | |
1011 | being filtered by a firewall, or you're running multiple servers on a | |
1012 | single host. Prior to obtaining an official port number, TrIPE used to | |
1013 | use port 22003; if you started using TrIPE back then, you may not want | |
1014 | to change, for the sake of compatibility or tradition. | |
1015 | ||
1016 | To change the port number used by the server, simply set the @code{port} | |
1017 | variable in the startup script configuration file: @pxref{Startup | |
1018 | script}. The value of this variable should be a port number. However, | |
1019 | it's permitted for it to be a service name, which will looked up using | |
1020 | @manpage{getservbyname, 3}, with protocol name @samp{udp}, so you'll | |
1021 | probably need to edit @file{/etc/services} or your YP map or something. | |
1022 | ||
1023 | The TrIPE server uses this UDP port for both sending and receiving. If | |
1024 | you're using the default port, then it's sufficient that your firewall | |
1025 | allows incoming UDP packets with destination port 4070 and outgoing | |
1026 | packets with source port 4070. You might want to do further filtering | |
1027 | based on the remote address and port as well, but that seems fairly | |
1028 | pointless: the server has been designed and implemented carefully in | |
1029 | order to resist network-borne attacks, and since with UDP it's pretty | |
1030 | easy to spoof source addresses, the firewall won't keep out malicious | |
1031 | packets from a determined adversary anyway. | |
1032 | ||
1033 | @node Users, , Port, System configuration | |
1034 | @section Users and groups | |
1035 | ||
1036 | The @manpage{tripe} server doesn't have to run with full @user{root} | |
1037 | privileges. However, it does need to be able to open `tunnel | |
1038 | interfaces', and this usually requires special privilege. | |
1039 | ||
1040 | @c -------------------------------------------------------------------------- | |
1041 | @node Networking, Cryptography, System configuration, Top | |
1042 | @chapter Networking concepts | |
1043 | ||
1044 | This chapter explains how TrIPE thinks about networks, and how to go | |
1045 | about fitting TrIPE into your network design. | |
1046 | ||
1047 | @menu | |
1048 | * Networks and addressing:: How TrIPE thinks networks are structured | |
1049 | * Tunnels and routing:: How networks are joined together | |
1050 | * Connection styles:: Ways of setting up connections | |
1051 | * Firewall considerations:: How TrIPE affects your firewall | |
1052 | @end menu | |
1053 | ||
1054 | @node Networks and addressing, Tunnels and routing, Networking, Networking | |
1055 | @section Network structure and addressing | |
1056 | @cindex network representative | |
1057 | @cindex representative, network | |
1058 | @cindex peer | |
1059 | @cindex internal address | |
1060 | @cindex external address | |
1061 | ||
1062 | In TrIPE's model, a virtual network consists of a number of physical | |
1063 | networks joined together. Each physical network needs a | |
1064 | @dfn{representative} (at least one, though more may be useful) which | |
1065 | actually speaks the TrIPE protocol. The representative establishes | |
1066 | secure point-to-point links with representatives of other physical | |
1067 | networks over the Internet (or at least over some larger physical | |
1068 | network). These links are strictly pairwise: they carry packets back | |
1069 | and forth between precisely two endpoints. The two endpoints of such a | |
1070 | link are @dfn{peers}: the link is, as far as TrIPE is concerned, utterly | |
1071 | symmetrical. | |
1072 | ||
1073 | Most of the hosts in the physical networks only need `internal' | |
1074 | addresses, i.e., their addresses need only be unique @emph{within} the | |
1075 | virtual network -- and, if NAT is in use, even that needn't hold, though | |
1076 | NAT is at best a necessary evil and not to be used lightly. Obviously, | |
1077 | in order to be useful, the representatives need external addresses, so | |
1078 | that they can send each other IP packets over the wider Internet. | |
1079 | ||
1080 | @menu | |
1081 | * Addressing example:: A worked example | |
1082 | @end menu | |
1083 | ||
1084 | @node Addressing example, , Networks and addressing, Networks and addressing | |
1085 | @subsection Example | |
1086 | @cindex Alice | |
1087 | @cindex Bob | |
1088 | @cindex @code{alice.net} | |
1089 | @cindex @code{bob.com} | |
1090 | @cindex @code{alice.net} | |
1091 | ||
1092 | Alice is the administrator of @code{alice.net}. Internally, she has | |
1093 | allocated IP addresses from the private address range 10.0.1.0/24. She | |
1094 | has an externally facing server @code{anubis.alice.net}, which has an | |
1095 | internal address of 10.0.1.1 and an external address of 192.0.2.1. | |
1096 | ||
1097 | Bob is an administrator at @code{bob.com}. Internally, he's allocated | |
1098 | IP addresses from the private address range 10.0.2.0/24. He has an | |
1099 | externally facing server @code{bast.bob.com}, which has an internal | |
1100 | address of 10.0.2.1 and an external address of 192.0.2.129.@footnote{ | |
1101 | The author would like to apologize for the unrealistic nature of the | |
1102 | external IP addresses in this example. Unfortunately, allocating the | |
1103 | addresses from the private-use space, e.g., 10.0.0.0/8, would be | |
1104 | confusing, since these are normally @emph{internal} addresses only; the | |
1105 | network 192.0.2.0/24 is allocated by IANA for use in examples such as | |
1106 | this, but is rather too small to divide into realistic subnets, as I've | |
1107 | tried to do here.} | |
1108 | ||
1109 | It would be reasonable for Alice and Bob to choose @code{anubis} and | |
1110 | @code{bast} as their respective TrIPE representatives. If, say, | |
1111 | @code{amaterasu.alice.net} was an internal host with address 10.0.1.42, | |
1112 | it would not be a suitable representative, since this is an internal | |
1113 | address and (presumably) the routers between @code{alice.net} and | |
1114 | @code{bob.com} don't know how to send packets there. | |
1115 | ||
1116 | We'll return to Alice and Bob in other examples later. | |
1117 | ||
1118 | @node Tunnels and routing, Connection styles, Networks and addressing, Networking | |
1119 | @section Tunnels and routing | |
1120 | @cindex tunnel | |
1121 | @cindex SLIP | |
1122 | @cindex TUN/TAP | |
1123 | @cindex pty | |
1124 | ||
1125 | A @dfn{tunnel} is a network interface, usually configured as a | |
1126 | point-to-point link, except that rather than sending network packets | |
1127 | through some physical interface, it makes them available to a user-mode | |
1128 | process through a character device; similarly, packets written to the | |
1129 | character device appear to the kernel to have originated in the tunnel | |
1130 | interface. | |
1131 | ||
1132 | A cheesy hack for implementing a `tunnel' interface like this is to open | |
1133 | a @manpage{pty, 7} and configure the slave side of the pty to use the | |
1134 | SLIP line discipline. A user-mode process can now use the master side | |
1135 | of the pty to read and write SLIP-encoded network packets. Linux's | |
1136 | TUN/TAP and BSD's @manpage{tun, 4} interfaces provide a more convenient | |
1137 | and efficient means of achieving the same goal. TrIPE prefers to use | |
1138 | these more refined tunnel interfaces, but is willing to use the cheesy | |
1139 | SLIP hack if necessary. | |
1140 | ||
1141 | For each peer with which it is exchanging secured packets, a TrIPE | |
1142 | representative creates a tunnel interface. Packets being sent through | |
1143 | the interface are encrypted, authenticated, and retransmitted to the | |
1144 | peer's UDP port; packets arriving from a peer are verified, decrypted, | |
1145 | and inserted into the tunnel. | |
1146 | ||
1147 | For this to work, the representative needs to have at least two routes | |
1148 | established. | |
1149 | ||
1150 | @itemize | |
1151 | @item | |
1152 | a route to its peer's external address, so that it can send it encrypted | |
1153 | packets encapsulated in UDP; | |
1154 | ||
1155 | @item | |
1156 | a route to the peer's @emph{internal} address, directed over the tunnel | |
1157 | interface; and possibly | |
1158 | ||
1159 | @item | |
1160 | if the peer is acting as a representative for a network of other hosts, | |
1161 | a route to that network also over the tunnel. | |
1162 | @end itemize | |
1163 | ||
1164 | @menu | |
1165 | * Routing example:: A worked example | |
1166 | @end menu | |
1167 | ||
1168 | @node Routing example, , Tunnels and routing, Tunnels and routing | |
1169 | @subsection Example | |
1170 | @cindex ifconfig | |
1171 | @cindex route | |
1172 | ||
1173 | Continuing the earlier example (@pxref{Addressing example}) | |
1174 | @code{anubis.alice.net} needs to have one route to @code{bast.bob.com} | |
1175 | external address 192.0.2.129. We'll assume that @code{anubis} has a | |
1176 | direct connection to the Internet, and that therefore no special action | |
1177 | needs to be taken here. In order to tunnel traffic to | |
1178 | @code{bast.bob.com}, @code{anubis} has its @code{tripe-bob} interface | |
1179 | configured as follows.@footnote{ | |
1180 | Network configuration commands are system-specific. This manual assumes | |
1181 | a Linux system because that's the author's primary operating system; | |
1182 | consult your system's manual to find out what the equivalent commands | |
1183 | are. Network interface names are also system-specific; Linux lets us | |
1184 | rename network interfaces to make their names meaningful, and these | |
1185 | examples reflect this. Finally, don't worry about the MTU setting. | |
1186 | Usually, TrIPE's ancillary services will work out the correct MTU | |
1187 | automatically.} | |
1188 | ||
1189 | @example | |
1190 | ifconfig tripe-bob 10.0.1.1 pointopoint 10.0.2.1 mtu 1435 | |
1191 | @end example | |
1192 | ||
1193 | Further, in order to communicate with the larger @code{bob.com} internal | |
1194 | network, @code{anubis} has set up an additional route | |
1195 | ||
1196 | @example | |
1197 | route add -net 10.0.2.0/24 gw 10.0.2.1 dev tripe-bob metric 2 | |
1198 | @end example | |
1199 | ||
1200 | Other hosts in Alice's network might need to be told | |
1201 | ||
1202 | @example | |
1203 | route add -net 10.0.2.0/24 gw 10.0.1.1 metric 3 | |
1204 | @end example | |
1205 | ||
1206 | (spot the difference between this and @code{anubis}'s route), though in | |
1207 | many cases it's useful to choose the TrIPE representative as a router | |
1208 | anyway. | |
1209 | ||
1210 | @node Connection styles, Firewall considerations, Tunnels and routing, Networking | |
1211 | @section Connection styles | |
1212 | @cindex static connections | |
1213 | @cindex dynamic connections | |
1214 | @cindex active peer | |
1215 | @cindex passive peer | |
1216 | @cindex peer, active | |
1217 | @cindex peer, passive | |
1218 | ||
1219 | There are essentially two kinds of connections possible between TrIPE | |
1220 | peers. | |
1221 | ||
1222 | @table @dfn | |
1223 | @item Static | |
1224 | Each of the two peers expects to find the other up and running all of | |
1225 | the time. This works well, and is easy to set up and maintain, if the | |
1226 | two peers have stable external IP addresses, have network connectivity, | |
1227 | and are almost always turned on. If one is frequently down, or the | |
1228 | network between them is not always available (e.g., it's a dial-up link) | |
1229 | then the servers will be wasting their time trying to contact each | |
1230 | other: maybe one of the other options will be better. Either or both of | |
1231 | the peers may be providing VPN services for a network of other machines. | |
1232 | ||
1233 | @item Dynamic | |
1234 | One of the peers explicitly establishes a connection with the other when | |
1235 | it wants to communicate. The @dfn{active} peer -- the one making the | |
1236 | connection -- doesn't need a stable static IP address. The | |
1237 | @dfn{passive} peer -- the one connected to -- does need a stable | |
1238 | external IP address, to have reasonable network connectivity, and to be | |
1239 | up most of the time. Dynamic connections are more complicated to | |
1240 | configure and support, but much more flexible. | |
1241 | @end table | |
1242 | ||
1243 | In principle, it might be possible for two hosts, both behind NAT | |
1244 | routers, to make use of, say, STUN to establish a connection; but this | |
1245 | doesn't seem sufficiently useful. | |
1246 | ||
1247 | @node Firewall considerations, , Connection styles, Networking | |
1248 | @section Firewall considerations | |
1249 | ||
1250 | @cindex Firewall | |
1251 | You should be able to write firewall rules for packets travelling over | |
1252 | TrIPE's tunnel interfaces just as for any other interfaces. | |
1253 | Unfortunately, it is hard to predict the name of the tunnel interface | |
1254 | that TrIPE will allocate for any particular peer. There are two basic | |
1255 | solutions to this problem. | |
1256 | ||
1257 | @itemize | |
1258 | @item | |
1259 | Some operating systems allow you to rename network interfaces. You can | |
1260 | use this feature to assign the interface a more useful name, which may | |
1261 | already be known to your firewall. | |
1262 | ||
1263 | @item | |
1264 | You can dynamically modify the firewall rules once you know which | |
1265 | interface has been assigned to the peer. This is probably more | |
1266 | complicated. | |
1267 | @end itemize | |
1268 | ||
1269 | @cindex SSH | |
1270 | TrIPE itself uses only a single UDP socket, by default port 4070. | |
1271 | Establishing dynamic connections may require additional network ports; | |
1272 | for example, if you use @manpage{ssh, 1} then the passive end will need | |
1273 | to be able to accept incoming TCP segments to and send from port 22, and | |
1274 | the active end will need to be able to send to and receive from port 22. | |
1275 | ||
1276 | @c -------------------------------------------------------------------------- | |
1277 | @node Cryptography, Setting up, Networking, Top | |
1278 | @chapter Cryptographic concepts | |
1279 | ||
1280 | The word `cryptography' comes from Greek and literally means `secret | |
1281 | writing'. Modern cryptography has expanded its scope considerably, and | |
1282 | now considers all kinds of mathematical approaches to | |
1283 | information-security problems. | |
1284 | ||
1285 | @section Cryptographic objectives | |
1286 | ||
1287 | @cindex secrecy | |
1288 | @cindex encryption | |
1289 | @cindex decryption | |
1290 | @cindex ciphertext | |
1291 | The earliest cryptographic objective is @emph{secrecy}: transforming a | |
1292 | message into a @emph{ciphertext} which is meaningless to an adversary | |
1293 | but such that an intended recipient can recover the original message. | |
1294 | Particularly when computers are used, the process of transforming a | |
1295 | message into a ciphertext is called @emph{encryption}, and the recovery | |
1296 | of the message from the ciphertext is @emph{decryption}. | |
1297 | ||
1298 | @cindex integrity | |
1299 | @cindex authentication | |
1300 | @cindex forgery | |
1301 | Encrypting a message doesn't prevent an adversary from altering it in | |
1302 | meaningful ways. The ability to distinguish messages from a particular | |
1303 | sender or senders is the objective of @emph{integrity} or | |
1304 | @emph{authenticity}. | |
1305 | ||
1306 | @section Symmetric and asymmetric cryptography | |
1307 | ||
1308 | ||
1309 | @c -------------------------------------------------------------------------- | |
1310 | @node Setting up, Security properties, Cryptography, Top | |
1311 | @chapter Setting TrIPE up | |
1312 | ||
1313 | @section Establishing the certificate authority | |
1314 | ||
1315 | ||
1316 | ||
1317 | @c -------------------------------------------------------------------------- | |
1318 | @node Security properties, Comparison, Setting up, Top | |
1319 | @chapter Security | |
1320 | ||
1321 | Obviously, a VPN system is no good if it's not secure. This chapter | |
1322 | discusses TrIPE's security and the design decisions which affect its | |
1323 | security. | |
1324 | ||
1325 | @menu | |
1326 | * Host security:: Security aspects of running TrIPE on | |
1327 | your host | |
1328 | * Crypto security:: TrIPE's use of cryptography has a | |
1329 | mathematical proof of security | |
1330 | * Not X.509:: TrIPE doesn't use X.509 because X.509 | |
1331 | sucks | |
1332 | @end menu | |
1333 | ||
1334 | @node Host security, Crypto security, Security properties, Security properties | |
1335 | @section Host security | |
1336 | ||
1337 | TrIPE runs entirely in user mode, unlike many IPsec implementations. | |
1338 | The main server, which is written in C, mostly runs as an unprivileged | |
1339 | user. However, a small part of the server runs with @user{root} | |
1340 | privileges because it needs to be able to open new tunnel devices | |
1341 | dynamically. Even this can be avoided, for example by using SLIP | |
1342 | tunnels, allocated by a GNU @manpage{userv, 1} service. If the server | |
1343 | is compromised, an attacker can use it to inject arbitrary network | |
1344 | packets, but little else. | |
1345 | ||
1346 | @c FIXME crossref for watch | |
1347 | The ancillary service @manpage{watch, 8} needs @user{root} privileges in | |
1348 | order to configure new network interfaces. It is written in Python, a | |
1349 | safe interpreted language. In turn, this invokes an external program, | |
1350 | again as @user{root}, to do the actual network interface configuration. | |
1351 | This program is user-selectable, but the default program is a simple | |
1352 | shell script; it does not process untrusted input. | |
1353 | ||
1354 | @node Crypto security, Not X.509, Host security, Security properties | |
1355 | @section Cryptographic security | |
1356 | ||
1357 | The TrIPE protocol is not standards-based. However, it has been | |
1358 | designed by an experienced cryptographer, and has a formal `security | |
1359 | proof' showing that an attack against the protocol can be transformed | |
1360 | into an attack against one of its primitive components. Other VPN | |
1361 | protocols are too complicated to admit such proofs. The guarantees | |
1362 | afforded by security proofs of this kind are @emph{contingent} on the | |
1363 | security of the primitive components rather than absolute, but even such | |
1364 | a contingent proof is much better than no proof at all. | |
1365 | ||
1366 | It's important to understand the limitations of this kind of security | |
1367 | proof. It doesn't guarantee that TrIPE is invulnerable to cryptanalytic | |
1368 | attack: if an adversary can break TrIPE's encryption primitive, for | |
1369 | example, then he'll win. It also doesn't guarantee anything about | |
1370 | TrIPE's non-cryptographic security: there might be exploitable buffer | |
1371 | overrun (or more subtle) vulnerabilities which allow an adversary to | |
1372 | defeat TrIPE's security. But the proof is still useful: it rules out a | |
1373 | substantial class of weaknesses if it's correct -- and there's another | |
1374 | problem: the proof might be wrong. But even with all of these caveats, | |
1375 | the author believes that cryptography with a possibly-wrong proof is | |
1376 | better than security without any kind of proof at all. | |
1377 | ||
1378 | The paper describing the protocol, its security properties, and its | |
1379 | proof, is @cite{The Wrestlers Protocol: A simple, practical, secure, | |
1380 | deniable protocol for key-exchange}, by Mark Wooding, available | |
1381 | electronically as @url{http://eprint.iacr.org/2006/386/}. | |
1382 | ||
1383 | The software allows users a wide selection of primitive components, some | |
1384 | standardized and some not; the author recommends the widely standardized | |
1385 | and well-respected Rijndael (AES) for encryption and SHA256 for hashing | |
1386 | and authentication. | |
1387 | ||
1388 | @node Not X.509, , Crypto security, Security properties | |
1389 | @section Why TrIPE doesn't use X.509 | |
1390 | ||
1391 | The TrIPE protocol does not use X.509 certificates, as deployed (for | |
1392 | example) in TLS and IPsec. X.509 certificates are hard to parse: | |
1393 | software which processes them has a history of vulnerabilities. | |
1394 | ||
1395 | The certification model used by TLS, where the holder of a key pays a | |
1396 | certification authority for his or her certificate, is economically | |
1397 | backwards: the direct beneficiaries of the certificate are those who | |
1398 | rely on it to establish the validity of the public key. The author does | |
1399 | not understand why an external certificate authority is needed in order | |
1400 | to construct a VPN anyway: if Alice has no idea who Bob is, she's | |
1401 | unlikely to want to allow him access to her private network! | |
1402 | ||
1403 | @c FIXME crossref to tripe-keys | |
1404 | The main TrIPE software does not assume any particular certification | |
1405 | model: rather, it considers the issue of establish authenticity of | |
1406 | public keys to be out-of-scope. The supplied @manpage{tripe-keys, 8} | |
1407 | program implements a very simple key-distribution system which avoids | |
1408 | the complexity inherent in X.509. Of course, because public key | |
1409 | distribution is separated from the main system, nothing prevents | |
1410 | swapping in a more sophisticated system where necessary. | |
1411 | ||
1412 | @c -------------------------------------------------------------------------- | |
1413 | @node Comparison, Index, Security properties, Top | |
1414 | @chapter Comparison with other systems | |
1415 | ||
1416 | This chapter compares TrIPE with other VPN protocols. | |
1417 | ||
1418 | @table @b | |
1419 | @item IPsec | |
1420 | @cindex IPsec | |
1421 | IPsec is an IETF standard. It defines two protocols for handling bulk | |
1422 | data. | |
1423 | ||
1424 | The Authentication Header (AH) simply adds cryptographic authentication | |
1425 | to an IP packet, including the header; this causes trouble with NAT | |
1426 | firewalls. The Encapsulating Security Payload (ESP) provides both | |
1427 | encryption and authenticity, and operates in one of two modes: | |
1428 | @emph{transport} mode simply processes the payload data, but not the | |
1429 | header; the @emph{tunnel} mode encapsulates an entire IP packet. Of | |
1430 | these, AH and ESP transport mode need to be supported by all | |
1431 | participating hosts. ESP tunnel mode only needs to be supported by a | |
1432 | single representative (`security gateway') of each network, and provides | |
1433 | header security which works properly with NAT. TrIPE works very | |
1434 | similarly to ESP tunnel mode. | |
1435 | ||
1436 | The IPsec AH and ESP protocols work directly over IP, rather than using | |
1437 | UDP as TrIPE does. This reduces the per-packet overhead, but means that | |
1438 | implementations need to be highly privileged, either running as part of | |
1439 | the kernel or at least with @user{root} privileges. This also causes | |
1440 | trouble when one of the peers is behind a router which performs network | |
1441 | address translation (NAT), since the there's no port number which the | |
1442 | router can use to demultiplex packets from the outside world and work | |
1443 | out which of the hosts behind it to forward the packet to. | |
1444 | ||
1445 | Key exchange in IPsec (IKE) is very complicated, with many options. The | |
1446 | protocol can use a number of different certificate formats, or none at | |
1447 | all. Partly this is due to the fact that IPsec has more ambitious goals | |
1448 | than TrIPE: IPsec aims to allow `opportunistic' security between | |
1449 | previously unrelated entities, whereas TrIPE assumes that all the | |
1450 | participants in its virtual network are administrated in a coordinated | |
1451 | fashion. This means that TrIPE's usefulness is comparatively limited; | |
1452 | of course, it also means that TrIPE is much simpler. | |
1453 | ||
1454 | @item OpenVPN | |
1455 | @cindex OpenVPN | |
1456 | In many respects, OpenVPN is very similar to TrIPE: it runs in userland, | |
1457 | and operates over UDP. OpenVPN uses a variant of the TLS protocol for | |
1458 | its key-exchange. TLS is very complex, and uses X.509 certificates | |
1459 | which bring their own problems. (OpenVPN provides a @strong{tls-auth} | |
1460 | option to mitigate this, though it partially defeats the point of public | |
1461 | key cryptography.) | |
1462 | ||
1463 | OpenVPN can use TAP interfaces in order to simulate an Ethernet rather | |
1464 | than a point-to-point link, which allows Ethernet bridging across the | |
1465 | VPN. TrIPE could do this relatively easily (it's just a matter of | |
1466 | configuring the tunnel interface differently) but it hasn't seemed | |
1467 | useful yet. | |
1468 | ||
1469 | @item SSH- and SSL-based VPNs | |
1470 | @cindex SSH-based VPNs | |
1471 | @cindex SSL-based VPNs | |
1472 | OpenSSH can implement a simple VPN, by opening tunnel devices at each | |
1473 | end and forwarding packets over the SSH connection. This causes | |
1474 | problems: SSH is already running over TCP, and TCP provides congestion | |
1475 | control and reliability. TCP over this tunnel will therefore have two | |
1476 | layers of congestion control and reliability, and the two have a | |
1477 | tendency to interfere. When there is little or no packet loss, | |
1478 | everything will be fine; if the underlying connection becomes flaky, the | |
1479 | VPN will suffer greatly. | |
1480 | ||
1481 | SSL-based VPNs (simply forwarding packets over an SSL or TLS connection) | |
1482 | have the same problem, and all of the problems associated with SSL's use | |
1483 | of X.509 certificates. | |
1484 | @end table | |
1485 | ||
1486 | @c -------------------------------------------------------------------------- | |
1487 | @node Index, , Comparison, Top | |
1488 | @appendix Index | |
1489 | ||
1490 | @printindex cp | |
1491 | ||
1492 | @c -------------------------------------------------------------------------- | |
1493 | @appendix Pay no attention to the man behind the curtain | |
1494 | ||
1495 | Here are nodes which aren't yet written. | |
1496 | ||
1497 | @menu | |
1498 | * Key management:: a section which hasn't been written | |
1499 | @end menu | |
1500 | ||
1501 | @node Key management, , Index, Index | |
1502 | @section FIXME | |
1503 | ||
1504 | @c -------------------------------------------------------------------------- | |
1505 | @bye |