From 2c1261e5fc64f82c53339c6e6e6261cb2d81d6eb Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Mon, 19 Apr 2010 22:42:57 +0100 Subject: [PATCH] Documentation restructuring: provide a useful overview. TrIPE has become very complicated to think about. Provide a useful overview of the system, with worked examples. --- .links | 2 + Makefile.am | 13 + configure.ac | 3 +- debian/rules | 4 + debian/tripe.docs | 1 + debian/tripe.info | 1 + manual/.gitignore | 16 + manual/Makefile.am | 37 ++ manual/intro.texi | 79 +++ manual/tripe.texi | 1505 ++++++++++++++++++++++++++++++++++++++++++++++++++++ tripe.7.in | 1111 ++++++++++++++++++++++++++++++++++++++ 11 files changed, 2771 insertions(+), 1 deletion(-) create mode 100644 debian/tripe.docs create mode 100644 debian/tripe.info create mode 100644 manual/.gitignore create mode 100644 manual/Makefile.am create mode 100644 manual/intro.texi create mode 100644 manual/tripe.texi create mode 100644 tripe.7.in diff --git a/.links b/.links index 098ccb8c..ec2bbfab 100644 --- a/.links +++ b/.links @@ -3,3 +3,5 @@ config/confsubst t/autotest.am t/testsuite.at config/auto-version +manual/texinice.tex +manual/gpl.texi diff --git a/Makefile.am b/Makefile.am index 3984556b..cdcc3a39 100644 --- a/Makefile.am +++ b/Makefile.am @@ -26,6 +26,7 @@ include $(top_srcdir)/vars.am SUBDIRS = +man_MANS = ###-------------------------------------------------------------------------- ### Subdirectories. @@ -70,6 +71,16 @@ endif ## Testing. SUBDIRS += t +## Manual. +SUBDIRS += manual + +###-------------------------------------------------------------------------- +### Main manual page. + +man_MANS += tripe.7 +EXTRA_DIST += tripe.7.in +CLEANFILES += tripe.7 + ###-------------------------------------------------------------------------- ### The pkg-config file. @@ -121,6 +132,8 @@ EXTRA_DIST += debian/pathmtu.install EXTRA_DIST += debian/tripe.README EXTRA_DIST += debian/tripe.dirs EXTRA_DIST += debian/tripe.install +EXTRA_DIST += debian/tripe.docs +EXTRA_DIST += debian/tripe.info EXTRA_DIST += debian/tripe.postinst EXTRA_DIST += debian/tripe.logrotate diff --git a/configure.ac b/configure.ac index 54caf9d1..4b9b21e6 100644 --- a/configure.ac +++ b/configure.ac @@ -327,7 +327,8 @@ AC_CONFIG_FILES( [keys/Makefile] [svc/Makefile] [mon/Makefile] - [t/Makefile t/atlocal]) + [t/Makefile t/atlocal] + [manual/Makefile]) AC_OUTPUT dnl ----- That's all, folks ------------------------------------------------- diff --git a/debian/rules b/debian/rules index b902fb6c..f404ae62 100755 --- a/debian/rules +++ b/debian/rules @@ -9,6 +9,10 @@ include $(CDBS)/class/autotools.mk ### General settings. DEB_BUILDDIR = $(CURDIR)/build +DEB_MAKE_BUILD_TARGET = all html pdf +DEB_MAKE_INSTALL_TARGET = \ + install install-html install-pdf \ + DESTDIR=$(CURDIR)/debian/tmp/ DEB_MAKE_CHECK_TARGET = check ###-------------------------------------------------------------------------- diff --git a/debian/tripe.docs b/debian/tripe.docs new file mode 100644 index 00000000..ecb058b3 --- /dev/null +++ b/debian/tripe.docs @@ -0,0 +1 @@ +debian/tmp/usr/share/doc/tripe/* diff --git a/debian/tripe.info b/debian/tripe.info new file mode 100644 index 00000000..96d8aedf --- /dev/null +++ b/debian/tripe.info @@ -0,0 +1 @@ +debian/tmp/usr/share/info/* diff --git a/manual/.gitignore b/manual/.gitignore new file mode 100644 index 00000000..e64cc7d6 --- /dev/null +++ b/manual/.gitignore @@ -0,0 +1,16 @@ +*.info +*.aux +*.cp +*.fn +*.ky +*.pdf +*.ps +*.dvi +*.pg +*.toc +*.tp +*.vr +gpl.texi +texinice.tex +version.texi +stamp-* diff --git a/manual/Makefile.am b/manual/Makefile.am new file mode 100644 index 00000000..7b0cb14e --- /dev/null +++ b/manual/Makefile.am @@ -0,0 +1,37 @@ +### -*-makefile-*- +### +### Build script for manual +### +### (c) 2009 Straylight/Edgeware +### + +###----- Licensing notice --------------------------------------------------- +### +### This file is part of Trivial IP Encryption (TrIPE). +### +### TrIPE is free software; you can redistribute it and/or modify +### it under the terms of the GNU General Public License as published by +### the Free Software Foundation; either version 2 of the License, or +### (at your option) any later version. +### +### TrIPE is distributed in the hope that it will be useful, +### but WITHOUT ANY WARRANTY; without even the implied warranty of +### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +### GNU General Public License for more details. +### +### You should have received a copy of the GNU General Public License +### along with TrIPE; if not, write to the Free Software Foundation, +### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +include $(top_srcdir)/vars.am + +###-------------------------------------------------------------------------- +### Manual. + +info_TEXINFOS = tripe.texi +tripe_TEXINFOS = + +tripe_TEXINFOS += gpl.texi +tripe_TEXINFOS += texinice.tex + +###----- That's all, folks -------------------------------------------------- diff --git a/manual/intro.texi b/manual/intro.texi new file mode 100644 index 00000000..f55fbec1 --- /dev/null +++ b/manual/intro.texi @@ -0,0 +1,79 @@ +@c +@c Introduction to TrIPE +@c +@c (c) 2009 Straylight/Edgeware +@c + +@c -------------------------------------------------------------------------- +@node Introduction, hack +@unnumbered Introduction + +This chapter explains very briefly what TrIPE is and what this manual +aims to tell you about it. + +@menu +* About TrIPE:: What TrIPE is and what it does +* About this manual:: What this manual tries to do, and who + should read it +@end menu + +@node About TrIPE, About this manual, Introduction, Introduction +@unnumberedsec About TrIPE + +TrIPE is a TrIPE is a Virtual Private Network (VPN) implementation. It uses +cryptography to protect network packets from being read or tampered with +as they travel over hostile networks (e.g., the Internet). The effect +of this is that you can connect together geographically-separated +networks of machines and use network protocols which would be unsafe to +use over public networks. + +The name `TrIPE' stands for `Trivial IP Encryption'. Unfortunately, +while the TrIPE network protocol is still fairly simple (and this is one +of TrIPE's conspicuous advantages over other VPN systems), the software +suite which implements it is not. Over time, the original single server +has acquired strangely-shaped extensions and add-on-services in order to +solve various problems, and even given fairly detailed descriptions of +all of the individual pieces it can be difficult to see how to fit them +together in order to actually do anything useful. + +The TrIPE software runs entirely in user mode. It does not require any +kernel modifications. + +@node About this manual, , About TrIPE, Introduction +@unnumberedsec About this manual + +This manual provides an overview of the TrIPE software suite. The +individual components are described in their respective reference manual +pages. This page exists to provide a picture for how the various pieces +fit together and how to use them effectively. It presents a number of +worked examples, but it's not intended to be used as a `cookbook'; TrIPE +is a complicated system, and the author believes that you're less likely +to become confused by it if you understand how its various bits fit +together rather than following canned recipes which don't quite match +your particular circumstances. + +This manual is intended for network administrators who are comfortable +with the fundamentals of IP networking and routing. It assumes a +reasonable level of knowledge of how to configure network interfaces and +routing. It doesn't assume a strong background in cryptography, though +a good grounding won't hurt; the author recommends the @cite{Handbook of +Applied Cryptography} by Alfred Menezes, Paul van Oorschott and Scott +Vanstone, which is published by CRC Press, or available online at +@url{http://FIXME}. + +Unlike other Info manuals, this one isn't intended to be a complete +reference to the system. That information is provided in traditional +Unix-style manual pages, which are easier to consult quickly. Instead, +it provides a conceptual overview of the system together with examples +to help you get started. + +@node hack, , Introduction +@chapter magic + +@c ----- That's all, folks -------------------------------------------------- + +@c Local variables: +@c mode: Texinfo +@c TeX-PDF-mode: t +@c TeX-master: "tripe" +@c End: diff --git a/manual/tripe.texi b/manual/tripe.texi new file mode 100644 index 00000000..58f5f354 --- /dev/null +++ b/manual/tripe.texi @@ -0,0 +1,1505 @@ +\input texinfo @c -*- mode: texinfo; TeX-PDF-mode: t -*- +@c +@c Manual for TrIPE +@c +@c (c) 2009 Straylight/Edgeware +@c + +@c ----- Standard boilerplate ----------------------------------------------- + +@c %**start of header +@setfilename tripe.info +@settitle TrIPE: Trivial IP Encryption +@setchapternewpage odd +@footnotestyle end +@paragraphindent 0 +@iftex +@input texinice +@afourpaper +@end iftex + +@definfoenclose dfn,`,' + +@macro manpage{NAME, SECTION} +@b{\NAME\}(\SECTION\) +@end macro + +@macro user{NAME} +@b{\NAME\} +@end macro +@c %**end of header + +@include version.texi + +@dircategory Internet applications +@direntry +* TrIPE: (tripe). Trivial IP Encryption: a VPN system +@end direntry + +@c ----- Copyright matters -------------------------------------------------- + +@copying +This file documents the TrIPE VPN suite version @value{VERSION}. + +Copyright @copyright{} 2009 Straylight/Edgeware + +@quotation +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled `Copying' and `GNU General Public License' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the copyright holder. +@end quotation +@end copying + +@c -------------------------------------------------------------------------- +@titlepage + +@title TrIPE: Trivial IP Encryption +@subtitle A moderately simple virtual private network +@subtitle (version @value{EDITION}) +@author Straylight/Edgeware +@page + +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@iftex +@contents +@end iftex + +@c -------------------------------------------------------------------------- +@ifnottex +@node Top, Copying, (dir), (dir) +@top TrIPE: Trivial IP Encryption + +@menu +* Copying:: TrIPE is free software! +* Introduction:: What TrIPE is, and what this manual has + to say about it + +* Installing:: Installing TrIPE +* Tour:: Whistle-stop tour of the various bits +* System configuration:: Integrating TrIPE with the rest of your OS +* Networking:: How TrIPE fits into your network +* Cryptography:: Key management and cryptography +* Setting up:: How to install TrIPE and make it run + +Other useful information +* Security properties:: TrIPE is secure, honest; here's why +* Comparison:: How TrIPE compares to other VPN systems + +* Index:: Index of interesting things + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About TrIPE:: What TrIPE is and what it does +* About this manual:: What this manual tries to do, and who + should read it + +Installation + +* Prerequisites:: What you need before you can start +* Building:: How to compile it from the source code +* From Git:: How to build directly from + version-controlled sources +* What goes where:: Where everything gets installed + +Where everything is installed + +* Installation dirs:: Directories in which files are installed +* File locations:: Which files are put where + +A quick tour of TrIPE + +* Server:: The main VPN server +* Key utility:: Generating and distributing keys +* Startup script:: Starting the server and its little friends +* Peer services:: Establishing and configuring connections +* Config Makefile:: Using GNU Make to make life easier + +System configuration + +* Port:: +* Users:: + +Networking concepts + +* Networks and addressing:: How TrIPE thinks networks are structured +* Tunnels and routing:: How networks are joined together +* Connection styles:: Ways of setting up connections +* Firewall considerations:: How TrIPE affects your firewall + +Network structure and addressing + +* Addressing example:: A worked example + +Tunnels and routing + +* Routing example:: A worked example + +Security + +* Host security:: Security aspects of running TrIPE on + your host +* Crypto security:: TrIPE's use of cryptography has a + mathematical proof of security +* Not X.509:: TrIPE doesn't use X.509 because X.509 + sucks + +Pay no attention to the man behind the curtain + +* Key management:: a section which hasn't been written + +@end detailmenu +@end menu + +@end ifnottex + +@c -------------------------------------------------------------------------- +@node Copying, Introduction, Top, Top +@unnumbered The GNU General Public License + +@include gpl.texi + +@node Introduction, Installing, Copying, Top +@unnumbered Introduction + +This chapter explains very briefly what TrIPE is and what this manual +aims to tell you about it. + +@menu +* About TrIPE:: What TrIPE is and what it does +* About this manual:: What this manual tries to do, and who + should read it +@end menu + +@node About TrIPE, About this manual, Introduction, Introduction +@unnumberedsec About TrIPE + +TrIPE is a TrIPE is a Virtual Private Network (VPN) implementation. It uses +cryptography to protect network packets from being read or tampered with +as they travel over hostile networks (e.g., the Internet). The effect +of this is that you can connect together geographically-separated +networks of machines and use network protocols which would be unsafe to +use over public networks. + +The name `TrIPE' stands for `Trivial IP Encryption'. Unfortunately, +while the TrIPE network protocol is still fairly simple (and this is one +of TrIPE's conspicuous advantages over other VPN systems), the software +suite which implements it is not. Over time, the original single server +has acquired various strangely-shaped extensions and add-on-services in +order to solve various problems, and even given fairly detailed +descriptions of all of the individual pieces it can be difficult to see +how to fit them together in order to actually do anything useful. + +The TrIPE software runs entirely in user mode. It does not require any +kernel modifications. + +@node About this manual, , About TrIPE, Introduction +@unnumberedsec About this manual +@cindex Menezes, Alfred J. +@cindex van Oorschott, Paul C. +@cindex Vanstone, Scott A. + +This manual provides an overview of the TrIPE software suite. The +individual components are described in their respective reference manual +pages. This page exists to provide a picture for how the various pieces +fit together and how to use them effectively. It presents a number of +worked examples, but it's not intended to be used as a `cookbook'; TrIPE +is a complicated system, and the author believes that you're less likely +to become confused by it if you understand how its various bits fit +together rather than following canned recipes which don't quite match +your particular circumstances. + +This manual is intended for network administrators who are comfortable +with the fundamentals of IP networking and routing. It assumes a +reasonable level of knowledge of how to configure network interfaces and +routing. It doesn't assume a strong background in cryptography, though +a good grounding won't hurt; the author recommends the @cite{Handbook of +Applied Cryptography} by Alfred Menezes, Paul van Oorschott and Scott +Vanstone, which is published by CRC Press, or available online at +@url{http://www.cacr.math.uwaterloo.ca/hac/}. + +Unlike other Info manuals, this one isn't intended to be a complete +reference to the system. That information is provided in traditional +Unix-style manual pages, which are easier to consult quickly. Instead, +it provides a conceptual overview of the system together with examples +to help you get started. + +@c -------------------------------------------------------------------------- +@node Installing, Tour, Introduction, Top +@chapter Installation + +This chapter describes how to install TrIPE. You should probably read +it even if you obtained TrIPE as a binary package, say as part of a +Linux distribution. + +@menu +* Prerequisites:: What you need before you can start +* Building:: How to compile it from the source code +* From Git:: How to build directly from + version-controlled sources +* What goes where:: Where everything gets installed +@end menu + +@node Prerequisites, Building, Installing, Installing +@section Prerequisites +@cindex prerequisites + +There are a number of other pieces of software you'll need to be able to +build and run the TrIPE suite. Some of them are, strictly speaking, +optional, in the sense that only part of the suite depends on them and +the rest will continue functioning properly. But the various parts of +TrIPE are intended to work together, and you'll have an easier time of +it if they're all fully operational. In particular, most of this manual +assumes that the whole suite is available: you will have to read the +individual manpages to find out how to configure the system properly if +you want to be clever. + +Anyway, in order to be able to use TrIPE, you'll need the following. + +@table @asis +@item @strong{mLib}, at least version 2.1.0 +@cindex mLib +A library of C utilities. + +@item @strong{Catacomb}, at least version 2.1.1 +@cindex Catacomb +A cryptographic library. + +@item @strong{Python}, at least version 2.4 +@cindex van Rossum, Guido +@cindex Python +Python is a popular high-level language designed by and under the +lifelong benevolent dictatorship of Guido van Rossum; many of the +peripheral parts of TrIPE are written in Python. + +@item @strong{mLib-python} +Python bindings for mLib; necessary for the @strong{connect} and +@strong{watch} services which make dynamic connections work +(@pxref{Connection styles}), and the graphical monitor +@strong{tripemon}. + +@item @strong{catacomb-python} +Python bindings for Catacomb; necessary for the @strong{tripe-keys} +key-distribution utility: @pxref{Key management}. + +@item @strong{python-cdb}, at least version 0.32 +@cindex Bernstein, Daniel J. +@cindex CDB +@cindex Pomraning, M. J. +@cindex von Leitner, Felix +@cindex @strong{libowfat} +A Python interface for constructing and using constant databases (CDB). +CDB provides fast lookup and atomic updates, at the cost of having to +rebuild databases from scratch in order to make changes. The CDB format +was designed by D. J. Bernstein; the Python interface was written by +M. J. Pomraning using code from Felix von Leitner's @strong{libowfat} +and D. J. Bernstein's public-domain CDB implementation. CDB is required +by the @strong{connect} and @strong{watch} services. + +@item @strong{GTK+} and @strong{pygtk}, at least version 2.12 +@cindex GTK+ +@cindex Mattis, Peter +@cindex Kimball, Spencer +@cindex MacDonald, Josh +@cindex GNOME +@cindex @strong{pygtk} +@cindex Henstridge, James +@cindex Dahlin, Johan +GTK+ is a user-interface library, originally written by Peter Mattis, +Spencer Kimball and Josh MacDonald; it is used by various desktops +including GNOME. @strong{pygtk} is a set of Python bindings for GTK+ +originally created by James Henstridge and now maintained by Johan +Dahlin. These are needed by the graphical monitor @strong{tripemon}. +@end table + +It may also be useful to have the following items. + +@table @asis +@item The Codespeak @strong{py} library +@cindex Codespeak +@cindex py +@cindex greenlet +@cindex coroutine +@c FIXME: need attribution +The Codespeak @strong{py} library contains an implementation of +coroutines, which it calls `greenlets'. Coroutines are used by various +parts of the suite, though they will make use of an inefficient +implementation in terms of threads if @strong{py} isn't available. +@end table + +@node Building, From Git, Prerequisites, Installing +@section Building from a source distribution +@cindex tarball +@cindex building from source +@cindex @var{configdir} + +If you have a source tarball for TrIPE, you can build the software suite +as follows. + +@enumerate +@item +Unpack the sources. The tarball should have a name like +@file{tripe-@var{version}.tar.gz}. Type + +@example +gzip -dc tripe-@var{version}.tar.gz | tar xvf - +@end example + +to unpack the sources. This will create a subdirectory (the @dfn{source +directory}) of your current working directory called +@file{tripe-@var{version}} and containing the sources. + +@item +Create a directory (the @dfn{build directory}) for the built files to +go. I usually create a subdirectory @file{build} of the source +directory, though it needn't even be part of the same filesystem as the +source directory. You can have the build directory be the same as the +source directory if you like, but I don't really recommend it. Make the +build directory be your working directory. + +@item +Run + +@example +@var{source-directory}/configure +@end example + +to set up the build directory. (Here, @var{source-directory} is a +(possibly relative) path to the source directory from your chosen build +directory; for example, with my usual choice of build directory, I can +just type @samp{../configure}. + +You can provide the @file{configure} script with command-line options. +The most important options are as follows. + +@table @code +@item --prefix=@var{prefix} +Arranges to install the software under the directory @var{prefix} -- so +executables will end up in @file{@var{prefix}/bin} and so on. The +default is @file{/usr/local}. + +@item --with-configdir=@var{configdir} +Arranges to store and look for configuration data in @var{configdir}. +The default is @var{localstatedir}/tripe, where @var{localstatedir} is +itself set by the @option{--localstatedir} option and defaults to +@file{@var{prefix}/var}. +@end table + +@xref{Installation dirs}, for a table of installation directories used +by TrIPE and the @file{configure} options for setting them; run + +@example +@var{source-directory}/configure --help +@end example + +for a full list of options you can set. + +@item +Run + +@example +make +@end example + +This will build everything you need. + +@item +(Optional, but recommended.) Run + +@example +make check +@end example + +to test that what you've just built actually works. The test suite +isn't anywhere near as comprehensive as I'd like it to be, but it's a +start. (Contributions are welcome!) + +@item +Run + +@example +make install +@end example + +(probably as @user{root}) to install most things into their proper +places. + +@item +The TrIPE suite comes with a script to be run at boot time +(@pxref{Startup script}). Because systems vary so much in their startup +behaviour, TrIPE doesn't attempt to install this anywhere. This script +ends up in @file{init/tripe-init} in the build directory. + +On many systems, you should copy it to @file{/etc/init.d} (maybe +@file{/etc/rc.d/init.d} on Red Hat systems; maybe @file{/sbin/init.d} on +some proprietary Unix systems) and place symbolic links in the +@file{/etc/rc@var{?}.d} (maybe @file{/etc/rc.d/rc@var{?}.d} or +@file{/sbin/rc@var{?}.d}) directories. + +On traditional BSD systems, it's probably best to copy the script to +@file{prefix}/sbin/tripe-init, and run + +@example +@var{prefix}/tripe-init start +@end example + +from your @file{/etc/rc.local} script. +@end enumerate + +@node From Git, What goes where, Building, Installing +@section How to build TrIPE from the sources under version control +@cindex Git +@cindex Torvalds, Linus +@cindex Hamano, Junio + +The author maintains the TrIPE sources using Git, a distributed version +control system originally designed and implemented by Linus Torvalds and +now maintained by a community under the guidance of Junio Hamano. + +You can obtain a copy of the project history by running + +@example +git clone git://git.distorted.org.uk/~mdw/tripe +@end example + +This won't have a @file{configure} script or the @file{Makefile.in} +files provided in the source bundle. You'll need a number of additional +tools. + +@table @asis +@item GNU Autoconf, at least version 2.61 +@cindex Autoconf +GNU Autoconf builds @file{configure} scripts from @strong{m4} +descriptions. + +@item GNU Automake, at least version 1.8 +@cindex Automake +GNU Automake builds @file{Makefile.in} files from a high-level +declarative description of what needs building. + +@item GNU Libtool, at least version 2.2 +@cindex Libtool +GNU Libtool assists with the complex and messy business of dealing with +shared libraries on many different platforms. + +@item Autoconf archive, from 2007--05--12 or later +@cindex Autoconf archive +A collection of useful Autoconf macros. You must ensure that the +@command{aclocal} command can find these macros, e.g., by adding the +archive installation directory to the file +@file{/usr/share/aclocal/dirlist}. @xref{Macro search path,,, automake, +GNU Automake}. + +@item Common Files Distribution, at least version 1.3.4 +@cindex cfd +@cindex Common Files Distribution +The Common Files Distribution collects together a number of files which +need to be included in many projects, and provides tools for managing +them. +@end table + +@cindex mdw-setup +If you have these properly installed, it should be sufficient to run + +@example +mdw-setup +@end example + +in the source tree before following the instructions for building from a +source distribution: @pxref{Building}. + +@node What goes where, , From Git, Installing +@section Where everything is installed + +This section provides a handy description of where files are placed by +TrIPE's installation system. + +@menu +* Installation dirs:: Directories in which files are installed +* File locations:: Which files are put where +@end menu + +@node Installation dirs, File locations, What goes where, What goes where +@subsection Installation directories +As is usual with the GNU build system, the layout of the installed files +is highly configurable. The following table describes all of the +installation directories, and the @file{configure}-script arguments to +modify them. + +@multitable @columnfractions 0.16 0.29 0.3 0.23 +@headitem Directory name +@tab Default +@tab Debian +@tab Option + +@item @t{@var{prefix}} +@tab @t{/usr/local} +@tab @t{/usr} +@tab @t{-@w{}-prefix} + +@item @t{@var{exec-prefix}} +@tab @t{@var{prefix}} +@tab @t{/usr} +@tab @t{-@w{}-exec-prefix} + +@item @t{@var{bindir}} +@tab @t{@var{exec-prefix}/bin} +@tab @t{/usr/bin} +@tab @t{-@w{}-bindir} + +@item @t{@var{sbindir}} +@tab @t{@var{exec-prefix}/sbin} +@tab @t{/usr/sbin} +@tab @t{-@w{}-sbindir} + +@item @t{@var{libdir}} +@tab @t{@var{exec-prefix}/lib} +@tab @t{/usr/lib} +@tab @t{-@w{}-libdir} + +@item @t{@var{libexecdir}} +@tab @t{@var{exec-prefix}/libexec} +@tab @t{/usr/lib} +@tab @t{-@w{}-libexecdir} + +@item @t{@var{datarootdir}} +@tab @t{@var{prefix}/share} +@tab @t{/usr/share} +@tab @t{-@w{}-datarootdir} + +@item @t{@var{datadir}} +@tab @t{@var{datarootdir}} +@tab @t{/usr/share} +@tab @t{-@w{}-datadir} + +@item @t{@var{sysconfdir}} +@tab @t{@var{prefix}/etc} +@tab @t{/etc} +@tab @t{-@w{}-sysconfdir} + +@item @t{@var{configdir}} +@tab @t{@var{prefix}/var/tripe} +@tab @t{/etc/tripe} +@tab @t{-@w{}-with-configdir} + +@item @t{@var{mandir}} +@tab @t{@var{datarootdir}/man} +@tab @t{/usr/share/man} +@tab @t{-@w{}-mandir} + +@item @t{@var{infodir}} +@tab @t{@var{datarootdir}/info} +@tab @t{/usr/share/info} +@tab @t{-@w{}-infodir} + +@item @t{@var{docdir}} +@tab @t{@var{datarootdir}/doc/@/tripe} +@tab @t{/usr/share/doc/tripe} +@tab @t{-@w{}-docdir} + +@item @t{@var{socketdir}} +@tab @t{.} +@tab @t{/var/run} +@tab @t{-@w{}-with-socketdir} + +@item @t{@var{pythondir}} +@tab Depends on Python installation +@tab @t{/usr/lib/@/python@var{ver}/@/site-packages} +@tab None + +@item @t{@var{wiresharkdir}} +@tab Depends on Wireshark installation +@tab @t{/usr/lib/@/wireshark/@/plugins} +@tab @t{-@w{}-with-wireshark} +@end multitable + +In addition, there are some configure-time settings which affect the +locations of individual files. These are as follows. + +@multitable @columnfractions 0.2 0.3 0.27 0.23 +@headitem Directory name +@tab Default +@tab Debian +@tab Option + +@item @t{@var{logfile}} +@tab @t{./tripe.log} +@tab @t{/var/log/tripe.log} +@tab @t{-@w{}-with-logfile} + +@item @t{@var{pidfile}} +@tab @t{./tripectl.pid} +@tab @t{/var/run/tripectl.pid} +@tab @t{-@w{}-with-pidfile} + +@item @t{@var{initconfig}} +@tab @t{@var{sysconfdir}/tripe.conf} +@tab @t{/etc/default/tripe} +@tab @t{-@w{}-with-initconfig} +@end multitable + +The relative pathnames shown above are relative to the working directory +of the process. Most TrIPE programs set their working directory to +@file{@var{configdir}} when they start up, unless a different directory +is specified on the command line. + +@node File locations, , Installation dirs, What goes where +@subsection File locations + +The following table shows the locations of all the files in the +distribution. + +@table @t +@item @var{infodir} +@t{tripe.info} -- this manual, in GNU Info format. + +(There may possibly be other files, depending on whether +@command{makeinfo} decided to split it into parts). Prebuilt binary +packages may have compressed the info manual. + +@item @var{mandir} +The various manual pages. Manual pages are placed into sections +(following the Linux numbering convention). Manual pages in section +@var{n} are placed in @file{@var{mandir}/man@var{n}}. Prebuilt binary +packages may have compressed the manual pages. + +@item @var{docdir} +@t{tripe.pdf} -- this manual, in Adobe PDF. @* +@t{tripe.html/index.html} (and others) -- this manual, in HTML. + +Prebuilt binary packages may have compressed the PDF file. + +@item @var{bindir} +@t{pkstream} -- a utility for transporting UDP packets over streams @* +@t{tripe-uslip} -- a utility for testing the @manpage{tripe, 8} server@* +@t{tripemon} -- a graphical monitor program for TrIPE @* +@t{pathmtu} -- a utility for determining the path-MTU to a given host @* +@t{tripe-mitm} -- a hostile proxy for the TrIPE protocol @* +@t{tripectl} -- a client program for communicating with the +@manpage{tripe, 8} server + +Some of these programs may be missing from your distribution. The +@file{tripe-uslip} and @file{tripe-mitm} programs aren't particularly +useful in day-to-day operations, and aren't considered further in this +manual. + +@item @var{sbindir} +@t{tripe} -- the main server @* +@t{tripe-newpeers} -- build the peer database from text configuration @* +@t{tripe-keys} -- a utility for generating and distributing keys @* +@t{tripe-ifup} -- a script for configuring network interfaces + +@item @var{libexecdir}/tripe +@t{tripe-privhelper} -- a program used internally by the +@manpage{tripe, 8} server to open network-tunnel devices. The server +drops @user{root} privileges early on during its initialization; before +doing so, it starts a @t{tripe-privhelper} process. + +@t{services/connect} and @t{services/watch} -- ancillary +peer-management services described later. +@c FIXME want a cross-reference + +@item @var{libdir}/pkgconfig +@t{tripe.pc} -- a @manpage{pkg-config, 1} file, which allows other +packages to find out how TrIPE has been installed. + +@item @var{pythondir} +@t{tripe.py} -- Python module for communicating with @manpage{tripe, +8} server @* +@t{rmcr.py} -- Python module implementing coroutines in terms of +threads + +There may also be @file{.pyc} and @file{.pyo} files installed here. + +@item @var{wiresharkdir} +@t{tripe.so} -- Wireshark plugin for dissecting TrIPE protocol traces + +There may also be @file{.a} and @file{.la} files installed here. + +@item @var{configdir} +@t{peers.d/10base} -- base configuration for peers database. +@c FIXME want a cross-reference +@end table + +@c -------------------------------------------------------------------------- +@node Tour, System configuration, Installing, Top +@chapter A quick tour of TrIPE + +The TrIPE suite consists of a number of separate programs, each of which +is configured separately. This chapter provides a brief tour of the +various components, with particular emphasis on the various +configuration files they read. + +@menu +* Server:: The main VPN server +* Key utility:: Generating and distributing keys +* Startup script:: Starting the server and its little friends +* Peer services:: Establishing and configuring connections +* Config Makefile:: Using GNU Make to make life easier +@end menu + +@node Server, Key utility, Tour, Tour +@section The main server +@cindex @manpage{tripe, 8} server +@cindex keyring + +The server @manpage{tripe, 8} is the heart of the TrIPE system. It is +responsible for exchanging encrypted network packets with other hosts. +As part of this, it authenticates its peers (to ensure that it's +communicating with the right ones), agrees session keys, and performs +various other administrative tasks. + +The server has very little in the way of long-term configuration. + +The only external files it reads are its @dfn{keyrings}. There are two +keyrings: the @dfn{private keyring} contains the server's private key, +which it uses to prove its identity to its peers; and the @dfn{public +keyring} contains other servers' public keys, which are used to verify +their identities. The keyrings also contain a small quantity of +configuration information, in particular specifying which cryptographic +algorithms the server should use. You can maintain the keyrings +manually if you like, using the @manpage{key, 1} program included in the +Catacomb distribution: detailed information about the attributes TrIPE +expects on its keys is provided in the @manpage{tripe, 8} manpage. But +it's easier to use the @manpage{tripe-keys, 8} system (@pxref{Key +management}) to maintain the keyrings. + +Apart from the two keyrings, the server obtains configuration data from +two sources. + +@enumerate +@item +It accepts a number of switches on its command line. If you start the +server manually, you can provide command-line options then. However, +the server is usually started by the startup script script, which has its own +configuration file: @pxref{Startup script}. The server command line is +described in full in @manpage{tripe, 8}. + +@item +It provides an interactive @emph{administration interface} through which +other processes can issue commands and read status information +dynamically. You can use the @manpage{tripectl, 1} program to issue +administrative commands; see @manpage{tripe-admin, 5} for full details +about the commands available. +@end enumerate + +@node Key utility, Startup script, Server, Tour +@section Key management utility +@cindex @manpage{tripe-keys, 8} utility +@cindex @file{tripe-keys.master} +@cindex @file{tripe-keys.conf} +@cindex key generation +@cindex key distribution + +Key management and distribution is a complicated topic, dealt with fully +in its own chapter. + +The @manpage{tripe-keys, 8} utility implements a simple key distribution +system. It works like this. A trusted individual or group maintains a +master configuration file, typically called @file{tripe-keys.master}. + +From this master file, @manpage{tripe-keys, 8} constructs a file +@file{tripe-keys.conf} which can be distributed (e.g., by making it +available via HTTP or FTP) to the maintainers of the other participating +peers. The @manpage{tripe-keys, 8} utility assists with key generation +and secure distribution of public keys. + +For full details, @pxref{Key management}. + +@node Startup script, Peer services, Key utility, Tour +@section The startup script +@cindex peer script + +The startup script's name and location is system specific. If you built +the suite from source, then installing it appropriately is left to you. +The Debian GNU/Linux package places the script in +@file{/etc/init.d/tripe}; other possible locations are +@file{/etc/rc.d/init.d/tripe} (e.g., Red Hat, AIX), +@file{/sbin/init.d/tripe} (e.g., SuSE, HP-UX) or +@file{/usr/local/sbin/tripe-init} (BSD, recommended). + +The startup script is a Bourne shell script. It sources a configuration +file when it runs; this file's location is also somewhat variable. The +default location chosen by the @file{configure} script is +@file{/etc/tripe.conf}; however, the Debian package places it in +@file{/etc/default/tripe}. + +The startup script invokes @file{tripe} via the @file{tripectl} client, +which writes messages from the server to a logfile, and provides some +other useful services. + +As well as starting the server, the startup script also runs all of the +scripts found in the @file{@var{configdir}/services} and +@file{@var{configdir}/peers} directories. The @file{services} scripts +are invoked as +@example +@var{script} --daemon --startup +@end example +while the @file{peers} scripts are not passed arguments. + +The intent is that symbolic links to programs providing useful services +can be placed in @file{@var{configdir}/services} so that they'll start +automatically when @manpage{tripe, 8} starts. The options +@option{--daemon} and @option{--startup} are common to all service +providers (see @manpage{tripe-service, 7} for details). + +The @file{@var{configdir}/peers} directory is intended for scripts which +establish connections with specific peers. A simple example script +might be something like this. + +@example +#! /bin/sh +set -e + +tripectl ADD vampire INET 172.29.198.1 4070 +ifname=$(tripectl IFNAME vampire) +ifconfig $ifname 172.29.199.129 pointopoint 172.29.199.4 +route add -net 172.29.199.0/24 gw 172.29.199.4 dev $ifname +@end example + +Stashing this file as @file{@var{configdir}/peers/vampire} would cause +the server to establish a connection with @code{vampire} on startup, and +configure the tunnel interface accordingly. Configuration using +@file{peers} scripts is fairly versatile but tedious; the peer services +provide a better approach. This manual won't discuss @file{peers} +scripts any further. + +@node Peer services, Config Makefile, Startup script, Tour +@section Peer services +@cindex service +@cindex ancillary service +@cindex @manpage{connect, 8} +@cindex @manpage{watch, 8} +@cindex @manpage{tripe-ifup, 8} +@cindex peer database +@cindex @manpage{tripe-newpeers, 8} + +As mentioned earlier (@pxref{Server}), the main server provides an +administration interface which accepts configuration commands and +provides status information. This interface can be extended by +ancillary @emph{services} which can implement additional commands and +react to changes in the server's status. + +There are two services for managing connections with other peers. + +@table @command +@item connect +A fairly simple service for requesting the setup of new connections. + +@item watch +A more complex service, which reacts to connections being +established and terminated (e.g., by configuring network interfaces). +@end table + +In addition, there is a shell script @manpage{tripe-ifup, 8} which +actually does the job of configuring network interfaces. Currently, +this script only works on Linux; I'll add versions for other systems as +they're contributed. + +These services obtain information about the available peers and how to +establish and maintain connections to them from a @dfn{peer database}, +stored in @file{@var{configdir}/peers.cdb}. This database is +constructed from textual input files by a program +@manpage{tripe-newpeers, 8}. The services and script obtain all of +their configuration from the database, and don't examine the source +files at all. + +@node Config Makefile, , Peer services, Tour +@section Managing TrIPE configuration using GNU Make +@cindex makefile + +I use a simple Makefile to update my TrIPE configuration after making +changes. I've found it easiest to put configuration data for individual +peers in separate files under @file{peers.d}, and use GNU Make's +@code{wildcard} function to keep track of them: @xref{Wildcard +Function,, The Function @code{wildcard}, make, GNU @code{make}}. + +My Makefile is as follows. + +@example +### Makefile for tripe stuff + +TARGETS = peers.cdb +all: $(TARGETS) + +clean::; rm -f $(TARGETS) +.PHONY: clean + +## The peers database +peers.cdb: $(wildcard peers.d/[!@@]*[!~#]) + tripe-newpeers -c $@@ $^ + +## Keyring stuff +update: + tripe-keys update + chgrp tripe keyring keyring.pub + chmod 640 keyring keyring.pub + +.PHONY: update +@end example + +It's intended to be placed into the @file{@var{configdir}} directory and +invoked by @user{root}. It assumes that a @file{tripe-keys.conf} file +has been placed alongside. Now I can run + +@example +make +@end example + +after changing or adding peers, and + +@example +make update +@end example + +to update my public keyring. The @manpage{tripe, 8} server and the +various peer services will notice the new keyring and peer database and +reload them automatically. + +@c -------------------------------------------------------------------------- +@node System configuration, Networking, Tour, Top +@chapter System configuration + +This chapter explains how to fit TrIPE into the rest of your host's +operating system. It won't go into serious network configuration: +that's covered by the next chapter, @pxref{Networking}. + +@menu +* Port:: +* Users:: +@end menu + +@node Port, Users, System configuration, System configuration +@section Port number + +@cindex Spotify +The @manpage{tripe, 8} server uses a single UDP port. By default, this +is port 4070, which has been allocated to TrIPE by the IANA -- so, in +theory, there shouldn't be any conflicts. (TCP port 4070 is also +allocated to TrIPE, though it makes no use of TCP whatsoever. This is +probably a good thing, since TCP port 4070 is used by the Spotify audio +network. This doesn't cause any conflict with TrIPE, though it may +incline some over-zealous network administrators to close off TrIPE's +UDP port unnecessarily.) + +It's possible to use a different port number. This might be reasonable +if you know that port 4070 is being used by some other server, or is +being filtered by a firewall, or you're running multiple servers on a +single host. Prior to obtaining an official port number, TrIPE used to +use port 22003; if you started using TrIPE back then, you may not want +to change, for the sake of compatibility or tradition. + +To change the port number used by the server, simply set the @code{port} +variable in the startup script configuration file: @pxref{Startup +script}. The value of this variable should be a port number. However, +it's permitted for it to be a service name, which will looked up using +@manpage{getservbyname, 3}, with protocol name @samp{udp}, so you'll +probably need to edit @file{/etc/services} or your YP map or something. + +The TrIPE server uses this UDP port for both sending and receiving. If +you're using the default port, then it's sufficient that your firewall +allows incoming UDP packets with destination port 4070 and outgoing +packets with source port 4070. You might want to do further filtering +based on the remote address and port as well, but that seems fairly +pointless: the server has been designed and implemented carefully in +order to resist network-borne attacks, and since with UDP it's pretty +easy to spoof source addresses, the firewall won't keep out malicious +packets from a determined adversary anyway. + +@node Users, , Port, System configuration +@section Users and groups + +The @manpage{tripe} server doesn't have to run with full @user{root} +privileges. However, it does need to be able to open `tunnel +interfaces', and this usually requires special privilege. + +@c -------------------------------------------------------------------------- +@node Networking, Cryptography, System configuration, Top +@chapter Networking concepts + +This chapter explains how TrIPE thinks about networks, and how to go +about fitting TrIPE into your network design. + +@menu +* Networks and addressing:: How TrIPE thinks networks are structured +* Tunnels and routing:: How networks are joined together +* Connection styles:: Ways of setting up connections +* Firewall considerations:: How TrIPE affects your firewall +@end menu + +@node Networks and addressing, Tunnels and routing, Networking, Networking +@section Network structure and addressing +@cindex network representative +@cindex representative, network +@cindex peer +@cindex internal address +@cindex external address + +In TrIPE's model, a virtual network consists of a number of physical +networks joined together. Each physical network needs a +@dfn{representative} (at least one, though more may be useful) which +actually speaks the TrIPE protocol. The representative establishes +secure point-to-point links with representatives of other physical +networks over the Internet (or at least over some larger physical +network). These links are strictly pairwise: they carry packets back +and forth between precisely two endpoints. The two endpoints of such a +link are @dfn{peers}: the link is, as far as TrIPE is concerned, utterly +symmetrical. + +Most of the hosts in the physical networks only need `internal' +addresses, i.e., their addresses need only be unique @emph{within} the +virtual network -- and, if NAT is in use, even that needn't hold, though +NAT is at best a necessary evil and not to be used lightly. Obviously, +in order to be useful, the representatives need external addresses, so +that they can send each other IP packets over the wider Internet. + +@menu +* Addressing example:: A worked example +@end menu + +@node Addressing example, , Networks and addressing, Networks and addressing +@subsection Example +@cindex Alice +@cindex Bob +@cindex @code{alice.net} +@cindex @code{bob.com} +@cindex @code{alice.net} + +Alice is the administrator of @code{alice.net}. Internally, she has +allocated IP addresses from the private address range 10.0.1.0/24. She +has an externally facing server @code{anubis.alice.net}, which has an +internal address of 10.0.1.1 and an external address of 192.0.2.1. + +Bob is an administrator at @code{bob.com}. Internally, he's allocated +IP addresses from the private address range 10.0.2.0/24. He has an +externally facing server @code{bast.bob.com}, which has an internal +address of 10.0.2.1 and an external address of 192.0.2.129.@footnote{ +The author would like to apologize for the unrealistic nature of the +external IP addresses in this example. Unfortunately, allocating the +addresses from the private-use space, e.g., 10.0.0.0/8, would be +confusing, since these are normally @emph{internal} addresses only; the +network 192.0.2.0/24 is allocated by IANA for use in examples such as +this, but is rather too small to divide into realistic subnets, as I've +tried to do here.} + +It would be reasonable for Alice and Bob to choose @code{anubis} and +@code{bast} as their respective TrIPE representatives. If, say, +@code{amaterasu.alice.net} was an internal host with address 10.0.1.42, +it would not be a suitable representative, since this is an internal +address and (presumably) the routers between @code{alice.net} and +@code{bob.com} don't know how to send packets there. + +We'll return to Alice and Bob in other examples later. + +@node Tunnels and routing, Connection styles, Networks and addressing, Networking +@section Tunnels and routing +@cindex tunnel +@cindex SLIP +@cindex TUN/TAP +@cindex pty + +A @dfn{tunnel} is a network interface, usually configured as a +point-to-point link, except that rather than sending network packets +through some physical interface, it makes them available to a user-mode +process through a character device; similarly, packets written to the +character device appear to the kernel to have originated in the tunnel +interface. + +A cheesy hack for implementing a `tunnel' interface like this is to open +a @manpage{pty, 7} and configure the slave side of the pty to use the +SLIP line discipline. A user-mode process can now use the master side +of the pty to read and write SLIP-encoded network packets. Linux's +TUN/TAP and BSD's @manpage{tun, 4} interfaces provide a more convenient +and efficient means of achieving the same goal. TrIPE prefers to use +these more refined tunnel interfaces, but is willing to use the cheesy +SLIP hack if necessary. + +For each peer with which it is exchanging secured packets, a TrIPE +representative creates a tunnel interface. Packets being sent through +the interface are encrypted, authenticated, and retransmitted to the +peer's UDP port; packets arriving from a peer are verified, decrypted, +and inserted into the tunnel. + +For this to work, the representative needs to have at least two routes +established. + +@itemize +@item +a route to its peer's external address, so that it can send it encrypted +packets encapsulated in UDP; + +@item +a route to the peer's @emph{internal} address, directed over the tunnel +interface; and possibly + +@item +if the peer is acting as a representative for a network of other hosts, +a route to that network also over the tunnel. +@end itemize + +@menu +* Routing example:: A worked example +@end menu + +@node Routing example, , Tunnels and routing, Tunnels and routing +@subsection Example +@cindex ifconfig +@cindex route + +Continuing the earlier example (@pxref{Addressing example}) +@code{anubis.alice.net} needs to have one route to @code{bast.bob.com} +external address 192.0.2.129. We'll assume that @code{anubis} has a +direct connection to the Internet, and that therefore no special action +needs to be taken here. In order to tunnel traffic to +@code{bast.bob.com}, @code{anubis} has its @code{tripe-bob} interface +configured as follows.@footnote{ +Network configuration commands are system-specific. This manual assumes +a Linux system because that's the author's primary operating system; +consult your system's manual to find out what the equivalent commands +are. Network interface names are also system-specific; Linux lets us +rename network interfaces to make their names meaningful, and these +examples reflect this. Finally, don't worry about the MTU setting. +Usually, TrIPE's ancillary services will work out the correct MTU +automatically.} + +@example +ifconfig tripe-bob 10.0.1.1 pointopoint 10.0.2.1 mtu 1435 +@end example + +Further, in order to communicate with the larger @code{bob.com} internal +network, @code{anubis} has set up an additional route + +@example +route add -net 10.0.2.0/24 gw 10.0.2.1 dev tripe-bob metric 2 +@end example + +Other hosts in Alice's network might need to be told + +@example +route add -net 10.0.2.0/24 gw 10.0.1.1 metric 3 +@end example + +(spot the difference between this and @code{anubis}'s route), though in +many cases it's useful to choose the TrIPE representative as a router +anyway. + +@node Connection styles, Firewall considerations, Tunnels and routing, Networking +@section Connection styles +@cindex static connections +@cindex dynamic connections +@cindex active peer +@cindex passive peer +@cindex peer, active +@cindex peer, passive + +There are essentially two kinds of connections possible between TrIPE +peers. + +@table @dfn +@item Static +Each of the two peers expects to find the other up and running all of +the time. This works well, and is easy to set up and maintain, if the +two peers have stable external IP addresses, have network connectivity, +and are almost always turned on. If one is frequently down, or the +network between them is not always available (e.g., it's a dial-up link) +then the servers will be wasting their time trying to contact each +other: maybe one of the other options will be better. Either or both of +the peers may be providing VPN services for a network of other machines. + +@item Dynamic +One of the peers explicitly establishes a connection with the other when +it wants to communicate. The @dfn{active} peer -- the one making the +connection -- doesn't need a stable static IP address. The +@dfn{passive} peer -- the one connected to -- does need a stable +external IP address, to have reasonable network connectivity, and to be +up most of the time. Dynamic connections are more complicated to +configure and support, but much more flexible. +@end table + +In principle, it might be possible for two hosts, both behind NAT +routers, to make use of, say, STUN to establish a connection; but this +doesn't seem sufficiently useful. + +@node Firewall considerations, , Connection styles, Networking +@section Firewall considerations + +@cindex Firewall +You should be able to write firewall rules for packets travelling over +TrIPE's tunnel interfaces just as for any other interfaces. +Unfortunately, it is hard to predict the name of the tunnel interface +that TrIPE will allocate for any particular peer. There are two basic +solutions to this problem. + +@itemize +@item +Some operating systems allow you to rename network interfaces. You can +use this feature to assign the interface a more useful name, which may +already be known to your firewall. + +@item +You can dynamically modify the firewall rules once you know which +interface has been assigned to the peer. This is probably more +complicated. +@end itemize + +@cindex SSH +TrIPE itself uses only a single UDP socket, by default port 4070. +Establishing dynamic connections may require additional network ports; +for example, if you use @manpage{ssh, 1} then the passive end will need +to be able to accept incoming TCP segments to and send from port 22, and +the active end will need to be able to send to and receive from port 22. + +@c -------------------------------------------------------------------------- +@node Cryptography, Setting up, Networking, Top +@chapter Cryptographic concepts + +The word `cryptography' comes from Greek and literally means `secret +writing'. Modern cryptography has expanded its scope considerably, and +now considers all kinds of mathematical approaches to +information-security problems. + +@section Cryptographic objectives + +@cindex secrecy +@cindex encryption +@cindex decryption +@cindex ciphertext +The earliest cryptographic objective is @emph{secrecy}: transforming a +message into a @emph{ciphertext} which is meaningless to an adversary +but such that an intended recipient can recover the original message. +Particularly when computers are used, the process of transforming a +message into a ciphertext is called @emph{encryption}, and the recovery +of the message from the ciphertext is @emph{decryption}. + +@cindex integrity +@cindex authentication +@cindex forgery +Encrypting a message doesn't prevent an adversary from altering it in +meaningful ways. The ability to distinguish messages from a particular +sender or senders is the objective of @emph{integrity} or +@emph{authenticity}. + +@section Symmetric and asymmetric cryptography + + +@c -------------------------------------------------------------------------- +@node Setting up, Security properties, Cryptography, Top +@chapter Setting TrIPE up + +@section Establishing the certificate authority + + + +@c -------------------------------------------------------------------------- +@node Security properties, Comparison, Setting up, Top +@chapter Security + +Obviously, a VPN system is no good if it's not secure. This chapter +discusses TrIPE's security and the design decisions which affect its +security. + +@menu +* Host security:: Security aspects of running TrIPE on + your host +* Crypto security:: TrIPE's use of cryptography has a + mathematical proof of security +* Not X.509:: TrIPE doesn't use X.509 because X.509 + sucks +@end menu + +@node Host security, Crypto security, Security properties, Security properties +@section Host security + +TrIPE runs entirely in user mode, unlike many IPsec implementations. +The main server, which is written in C, mostly runs as an unprivileged +user. However, a small part of the server runs with @user{root} +privileges because it needs to be able to open new tunnel devices +dynamically. Even this can be avoided, for example by using SLIP +tunnels, allocated by a GNU @manpage{userv, 1} service. If the server +is compromised, an attacker can use it to inject arbitrary network +packets, but little else. + +@c FIXME crossref for watch +The ancillary service @manpage{watch, 8} needs @user{root} privileges in +order to configure new network interfaces. It is written in Python, a +safe interpreted language. In turn, this invokes an external program, +again as @user{root}, to do the actual network interface configuration. +This program is user-selectable, but the default program is a simple +shell script; it does not process untrusted input. + +@node Crypto security, Not X.509, Host security, Security properties +@section Cryptographic security + +The TrIPE protocol is not standards-based. However, it has been +designed by an experienced cryptographer, and has a formal `security +proof' showing that an attack against the protocol can be transformed +into an attack against one of its primitive components. Other VPN +protocols are too complicated to admit such proofs. The guarantees +afforded by security proofs of this kind are @emph{contingent} on the +security of the primitive components rather than absolute, but even such +a contingent proof is much better than no proof at all. + +It's important to understand the limitations of this kind of security +proof. It doesn't guarantee that TrIPE is invulnerable to cryptanalytic +attack: if an adversary can break TrIPE's encryption primitive, for +example, then he'll win. It also doesn't guarantee anything about +TrIPE's non-cryptographic security: there might be exploitable buffer +overrun (or more subtle) vulnerabilities which allow an adversary to +defeat TrIPE's security. But the proof is still useful: it rules out a +substantial class of weaknesses if it's correct -- and there's another +problem: the proof might be wrong. But even with all of these caveats, +the author believes that cryptography with a possibly-wrong proof is +better than security without any kind of proof at all. + +The paper describing the protocol, its security properties, and its +proof, is @cite{The Wrestlers Protocol: A simple, practical, secure, +deniable protocol for key-exchange}, by Mark Wooding, available +electronically as @url{http://eprint.iacr.org/2006/386/}. + +The software allows users a wide selection of primitive components, some +standardized and some not; the author recommends the widely standardized +and well-respected Rijndael (AES) for encryption and SHA256 for hashing +and authentication. + +@node Not X.509, , Crypto security, Security properties +@section Why TrIPE doesn't use X.509 + +The TrIPE protocol does not use X.509 certificates, as deployed (for +example) in TLS and IPsec. X.509 certificates are hard to parse: +software which processes them has a history of vulnerabilities. + +The certification model used by TLS, where the holder of a key pays a +certification authority for his or her certificate, is economically +backwards: the direct beneficiaries of the certificate are those who +rely on it to establish the validity of the public key. The author does +not understand why an external certificate authority is needed in order +to construct a VPN anyway: if Alice has no idea who Bob is, she's +unlikely to want to allow him access to her private network! + +@c FIXME crossref to tripe-keys +The main TrIPE software does not assume any particular certification +model: rather, it considers the issue of establish authenticity of +public keys to be out-of-scope. The supplied @manpage{tripe-keys, 8} +program implements a very simple key-distribution system which avoids +the complexity inherent in X.509. Of course, because public key +distribution is separated from the main system, nothing prevents +swapping in a more sophisticated system where necessary. + +@c -------------------------------------------------------------------------- +@node Comparison, Index, Security properties, Top +@chapter Comparison with other systems + +This chapter compares TrIPE with other VPN protocols. + +@table @b +@item IPsec +@cindex IPsec +IPsec is an IETF standard. It defines two protocols for handling bulk +data. + +The Authentication Header (AH) simply adds cryptographic authentication +to an IP packet, including the header; this causes trouble with NAT +firewalls. The Encapsulating Security Payload (ESP) provides both +encryption and authenticity, and operates in one of two modes: +@emph{transport} mode simply processes the payload data, but not the +header; the @emph{tunnel} mode encapsulates an entire IP packet. Of +these, AH and ESP transport mode need to be supported by all +participating hosts. ESP tunnel mode only needs to be supported by a +single representative (`security gateway') of each network, and provides +header security which works properly with NAT. TrIPE works very +similarly to ESP tunnel mode. + +The IPsec AH and ESP protocols work directly over IP, rather than using +UDP as TrIPE does. This reduces the per-packet overhead, but means that +implementations need to be highly privileged, either running as part of +the kernel or at least with @user{root} privileges. This also causes +trouble when one of the peers is behind a router which performs network +address translation (NAT), since the there's no port number which the +router can use to demultiplex packets from the outside world and work +out which of the hosts behind it to forward the packet to. + +Key exchange in IPsec (IKE) is very complicated, with many options. The +protocol can use a number of different certificate formats, or none at +all. Partly this is due to the fact that IPsec has more ambitious goals +than TrIPE: IPsec aims to allow `opportunistic' security between +previously unrelated entities, whereas TrIPE assumes that all the +participants in its virtual network are administrated in a coordinated +fashion. This means that TrIPE's usefulness is comparatively limited; +of course, it also means that TrIPE is much simpler. + +@item OpenVPN +@cindex OpenVPN +In many respects, OpenVPN is very similar to TrIPE: it runs in userland, +and operates over UDP. OpenVPN uses a variant of the TLS protocol for +its key-exchange. TLS is very complex, and uses X.509 certificates +which bring their own problems. (OpenVPN provides a @strong{tls-auth} +option to mitigate this, though it partially defeats the point of public +key cryptography.) + +OpenVPN can use TAP interfaces in order to simulate an Ethernet rather +than a point-to-point link, which allows Ethernet bridging across the +VPN. TrIPE could do this relatively easily (it's just a matter of +configuring the tunnel interface differently) but it hasn't seemed +useful yet. + +@item SSH- and SSL-based VPNs +@cindex SSH-based VPNs +@cindex SSL-based VPNs +OpenSSH can implement a simple VPN, by opening tunnel devices at each +end and forwarding packets over the SSH connection. This causes +problems: SSH is already running over TCP, and TCP provides congestion +control and reliability. TCP over this tunnel will therefore have two +layers of congestion control and reliability, and the two have a +tendency to interfere. When there is little or no packet loss, +everything will be fine; if the underlying connection becomes flaky, the +VPN will suffer greatly. + +SSL-based VPNs (simply forwarding packets over an SSL or TLS connection) +have the same problem, and all of the problems associated with SSL's use +of X.509 certificates. +@end table + +@c -------------------------------------------------------------------------- +@node Index, , Comparison, Top +@appendix Index + +@printindex cp + +@c -------------------------------------------------------------------------- +@appendix Pay no attention to the man behind the curtain + +Here are nodes which aren't yet written. + +@menu +* Key management:: a section which hasn't been written +@end menu + +@node Key management, , Index, Index +@section FIXME + +@c -------------------------------------------------------------------------- +@bye diff --git a/tripe.7.in b/tripe.7.in new file mode 100644 index 00000000..f089e101 --- /dev/null +++ b/tripe.7.in @@ -0,0 +1,1111 @@ +.\" -*-nroff-*- +.\". +.\" Overview of the whole system +.\" +.\" (c) 2008 Straylight/Edgeware +.\" +. +.\"----- Licensing notice --------------------------------------------------- +.\" +.\" This file is part of Trivial IP Encryption (TrIPE). +.\" +.\" TrIPE is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" TrIPE is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with TrIPE; if not, write to the Free Software Foundation, +.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +. +.so common/defs.man \" @@@PRE@@@ +. +.\"-------------------------------------------------------------------------- +.TH tripe 7 "28 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +. +.\"-------------------------------------------------------------------------- +.SH "NAME" +tripe \- overview of the TrIPE suite +. +.\"-------------------------------------------------------------------------- +.SH "NOTES TO THE AUTHOR" +. +.SS "What do we actually need to cover?" +.hP \*o +Key management. +.hP \*o +Setting up peer connections. +.hP \*o +Choosing algorithm suites? +. +.\"-------------------------------------------------------------------------- +.SH "DESCRIPTION" +. +TrIPE is a Virtual Private Network (VPN) implementation. It uses +cryptography to protect network packets from being read or tampered with +as they travel over hostile networks (e.g., the Internet). The effect +of this is that you can connect together geographically-separated +networks of machines and use network protocols which would be unsafe to +use over public networks. +.PP +The name `TrIPE' stands for `Trivial IP Encryption'. Unfortunately, +while the TrIPE network protocol is still fairly simple (and this is one +of TrIPE's conspicuous advantages over other VPN systems), the software +suite which implements it is not. Over time, the original single server +has acquired various strangely-shaped extensions and add-on-services in +order to solve various problems, and even given fairly detailed +descriptions of all of the individual pieces it can be difficult to see +how to fit them together in order to actually do anything useful. +.PP +This manual page provides an overview of the TrIPE software suite. The +individual components are described in their respective reference manual +pages. This page exists to provide a picture for how the various pieces +fit together and how to use them effectively. It presents a number of +worked examples, but it's not intended to be used as a `cookbook'; TrIPE +is a complicated system, and the author believes that you're less likely +to become confused by it if you understand how its various bits fit +together rather than following canned recipes which don't quite match +your particular circumstances. +.PP +The TrIPE software runs entirely in user mode. It does not require any +kernel modifications. +. +.SS "Who this documentation is for" +This document is intended for network administrators who are comfortable +with the fundamentals of IP networking and routing. It assumes +knowledge of how to configure network interfaces and routing. It +doesn't assume a strong background in cryptography, though a good +grounding won't hurt; the author recommends the +.I "Handbook of Applied Cryptography" +by Alfred Menezes, Paul van Oorschott and Scott Vanstone, which is +published by CRC Press, or available online. +. +.\"-------------------------------------------------------------------------- +.SH "HOW TrIPE WORKS" +. +The TrIPE protocol is a simple packet-based protocol transmitted over +UDP (RFC768). TrIPE has been allocated port 4070 by the IANA, but you +can use other ports if you like. +. +.SS "Network structure and addressing" +In TrIPE's model, a virtual network consists of a number of physical +networks joined together. Each physical network needs a +.I representative +(at least one, though more may be useful) which actually speaks the +TrIPE protocol. The representative establishes secure point-to-point +links with representatives of other physical networks over the Internet +(or at least over some larger physical network). These links are +strictly pairwise: they carry packets back and forth between precisely +two endpoints. The two endpoints of such a link are +.IR peers : +the link is, as far as TrIPE is concerned, utterly symmetrical. +.PP +Most of the hosts in the physical networks only need `internal' +addresses, i.e., their addresses need only be unique +.I within +the virtual network \(en and, if NAT is in use, even that needn't hold, +though NAT is at best a necessary evil and not to be used lightly. +Obviously, in order to be useful, the representatives need +.I external +addresses, so that they can send each other IP packets over the wider +Internet. +.TP +.B Example +.RS +Alice is the administrator of +.BR alice.net . +Internally, she has allocated IP addresses from the private address +range 10.0.1.0/24. She has an externally facing server +.BR anubis.alice.net , +which has an internal address of 10.0.1.1 and an external address of +192.0.2.1. +.PP +Bob is an administrator at +.BR bob.com . +Internally, he's allocated IP addresses from the private address range +10.0.2.0/24. He has an externally facing server +.BR bast.bob.com , +which has an internal address of 10.0.2.1 and an external address of +192.0.2.129. +.PP +(At this point, the author would like to apologize for the unrealistic +nature of the external IP addresses in this example. Unfortunately, +allocating the addresses from the private-use space, e.g., 10.0.0.0/8, +would be confusing, since these are normally +.I internal +addresses only; the network 192.0.2.0/24 is allocated by IANA for use in +examples such as this, but is rather too small to divide into realistic +subnets, as I've tried to do here.) +.PP +It would be reasonable for Alice and Bob to choose +.B anubis +and +.B bast +as their respective TrIPE representatives. If, say, +.B amaterasu.alice.net +was an internal host with address 10.0.1.42, it would not be a suitable +representative, since this is an internal address and (presumably) the +routers between +.B alice.net +and +.B bob.com +don't know how to send packets there. +.PP +We'll return to Alice and Bob in other examples later. +.RE +. +.SS "Tunnels and routing" +A +.I tunnel +is a network interface, usually configured as a point-to-point link, +except that rather than sending network packets through some physical +interface, it makes them available to a user-mode process through a +character device; similarly, packets written to the character device +appear to the kernel to have originated in the tunnel interface. +.PP +A cheesy hack for implementing a `tunnel' interface like this is to +open a +.BR pty (7) +and configure the slave side of the pty to use the SLIP line discipline. +A user-mode process can now use the master side of the pty to read and +write SLIP-encoded network packets. Linux's TUN/TAP and BSD's +.BR tun (4) +interfaces provide a more convenient and efficient means of achieving +the same goal. TrIPE prefers to use these more refined tunnel +interfaces, but is willing to use the cheesy SLIP hack if necessary. +.PP +For each peer with which it is exchanging secured packets, a TrIPE +representative creates a tunnel interface. Packets being sent through +the interface are encrypted, authenticated, and retransmitted to the +peer's UDP port; packets arriving from a peer are verified, decrypted, +and inserted into the tunnel. +.PP +For this to work, the representative needs to have at least two routes +established: +.hP \*o +a route to its peer's external address, so that it can send it encrypted +packets encapsulated in UDP; +.hP \*o +a route to the peer's +.I internal +address, directed over the tunnel interface; and possibly +.hP \*o +if the peer is acting as a representative for a network of other hosts, +a route to that network also over the tunnel. +.PP +.TP +.B Example +.RS +Continuing the earlier example, +.B anubis.alice.net +needs to have one route to +.BR bast.bob.com 's +external address 192.0.2.129. We'll assume that +.B anubis +has a direct connection to the Internet, and that therefore no special +action needs to be taken here. In order to tunnel traffic to +.BR bast.bob.com , +.B anubis +has its +.B tripe-bob +interface configured as follows. +.IP +.B "ifconfig tripe-bob 10.0.1.1 pointopoint 10.0.2.1 mtu 1435" +.PP +(Network configuration commands are system-specific. This manual page +assumes a Linux system because that's the author's primary operating +system; consult your system's manual to find out what the equivalent +commands are. Network interface names are also system-specific; Linux +lets us rename network interfaces to make their names meaningful, and +these examples reflect this. Finally, don't worry about the MTU +setting. Usually, TrIPE's ancillary services will work out the correct +MTU automatically.) +.PP +Further, in order to communicate with the larger +.B bob.com +internal network, +.B anubis +has set up an additional route +.IP +.B "route add -net 10.0.2.0/24 gw 10.0.2.1 dev tripe-bob metric 2" +.PP +Other hosts in Alice's network might need to be told +.IP +.B "route add -net 10.0.2.0/24 gw 10.0.1.1 metric 3" +.PP +(spot the difference between this and +.BR anubis 's +route), though in many cases it's useful to choose the TrIPE +representative as a router anyway. +.RE +. +.SS "Connection styles" +There are essentially two kinds of connections possible between TrIPE +peers.b +.hP 1. +.B "Always up." +Each of the two peers expects to find the other up and running all of +the time. This works well, and is easy to set up and maintain, if the +two peers have stable external IP addresses, have network connectivity, +and are almost always turned on. If one is frequently down, or the +network between them is not always available (e.g., it's a dial-up link) +then the servers will be wasting their time trying to contact each +other: maybe one of the other options will be better. Either or both of +the peers may be providing VPN services for a network of other machines. +.hP 2. +.B "Dynamically established." +One of the peers explicitly establishes a connection with the other when +it wants to communicate. The +.I active +peer \(en the one making the connection \(en doesn't need a stable +static IP address. The +.I passive +peer \(en the one connected to \(en does need a stable external IP +address, to have reasonable network connectivity, and to be up most of +the time. Dynamic connections are more complicated to configure and +support, but much more flexible. +.PP +(In principle, it might be possible for two hosts, both behind NAT +routers, to make use of, say, STUN to establish a connection; but this +doesn't seem sufficiently useful.) +. + + + + + + + + + + + + + + + + + +.\"-------------------------------------------------------------------------- +.SH "CRYPTOGRAPHY AND KEY MANAGEMENT" +. +.SS "A very quick introduction to modern cryptography" +This isn't really the place for a full survey of modern cryptography, +but I'll try to provide a little background. +.PP +Cryptography is the use of mathematics in order to achieve security +objectives. There are two main objectives of modern cryptography. +.TP +.I Secrecy +Preventing an adversary from learning anything about a message (except +its length), even though the adversary is responsible for delivering +it. The original message is called the +.IR plaintext ; +an +.I encryption +process converts the plaintext into a +.IR ciphertext ; +a recipient +.I decrypts +the ciphertext in order to recover the original plaintext. +.TP +.IR Integrity " or " authenticity +Preventing an adversary from creating +.IR forgeries : +i.e., messages which appear to have been sent by a particular person or +group of people. The sender +.I tags +or +.I signs +a message (tags are symmetric, signatures asymmetric, as explained +below); the recipient +.I verifies +the tag or signature. +.PP +In order to be able to do this, the recipient (in the case of secrecy) +or the sender (for integrity) need to know a +.I key +unknown to the adversary. We can now distinguish two important cases. +.TP +.IR "Symmetric" " or " "secret-key cryptography" +Both participants know the same key (or at least they can easily compute +each others' keys). Somehow, the two participants must agree on the +same key without letting it fall into the hands of the adversary. +Before 1976, all publicly-known cryptographic schemes were symmetric. +.TP +.IR "Asymmetric" " or " "public-key cryptography" +In the case of secrecy, the sender knows only a +.I public key +which is sufficient to encrypt a message so that it can only be +decrypted by the holder of the corresponding +.IR private key , +but insufficient to decrypt messages sent by others using the same +public key. In the case of integrity, the sender holds a secret key +with which he can make signatures; the public key allows others to +verify existing signatures but not to make new signatures. The holder +of the private key needs to convey an +.I authentic +copy of the corresponding public key to other participants, but the +public key doesn't need to be kept secret. Asymmetric cryptography was +first described to the public in 1976 by Whitfield Diffie and Martin +Hellman, though it had been known to governments (e.g., the British +CESG) for a number of years. +.PP +The advantage of symmetric cryptography is efficiency: symmetric +techniques for secrecy and integrity require smaller keys, less memory, +and much less time, than asymmetric techniques. The disadvantage is +that key distribution is much harder: symmetric keys must be known to +all participants, but kept secret from adversaries; public keys need not +be kept secret. It's therefore common to use asymmetric methods to +distribute short symmetric keys, and use the latter for ensuring the +secrecy and integrity of longer messages. +.PP +Asymmetric cryptography makes key distribution easier, but doesn't +eliminate the problem entirely. In particular, the problem of ensuring +that the participants have a correct copy of each others' keys remains. +There are a number of (partial) solutions to this problem, but they all +use the same basic idea: if (say) Alice knows Bob's public key, and Bob +knows Carol's public key, then Bob can send Alice a message saying +`Carol's public key is +.IR mumble ': +now, if Alice is willing to take Bob's word for this, then she now knows +Carol's key. +.PP +A signed message binding together a public key and some facts about the +corresponding private key is often called a +.IR certificate , +and a +.I certificate authority +(or CA) is an organization which issues certificates. Internet +certificate authorities are organizations whose public keys are well +known (e.g., included with web browsers) and which are generally +believed to be careful to issue only correct certificates. However, the +economics of this arrangement are strange: CAs are usually paid by the +holders of private keys, so they get their money whether or not the +certificates are actually true. +.PP +The famous +.BR pgp (1) +program and its successors (e.g., +.BR gpg (1)) +use a more sophisticated approach called the +.IR "web of trust" , +which allows Alice to collect certificates from a number of different +signers, compare them, and decide based on how much she trusts each of +them how likely their claims are. This can be complicated to manage. +. +.SS "Cryptography in TrIPE" +The long-term keys in TrIPE are all asymmetric. There are no +`pre-shared keys'. If two peers are to establish a link between them, +it is essential that each has a correct copy of the other's public key. +In principle, this ought to be easier than arranging for each to know a +common secret; pre-shared keys are easier to deal with only if they're +memorable, and memorable keys are not likely to be difficult to guess. +.PP +The TrIPE server, and its ancillary services, simply assume that you've +already acquired genuine copies of other peers' public keys and put them +in the right place; exactly how you go about this is up to you, and +tools such as CAs or PGP can help. However, the TrIPE distribution +contains a simple tool +.BR tripe-keys (8) +for dealing with public key distribution. This is described in more +detail below. +.PP +The TrIPE suite's primary author is a cryptographer, and he enjoys +having fine control over the cryptographic primitives involved. +Fortunately it's not that difficult to + + + + + + + + +.\"-------------------------------------------------------------------------- +.SH "SECURITY" +. +.SS "Host security" +TrIPE runs entirely in user mode, unlike many IPsec implementations. +The main server, which is written in C, mostly runs as an unprivileged +user. However, a small part of the server runs with +.B root +privileges because it needs to be able to open new tunnel devices +dynamically. Even this can be avoided, for example by using SLIP +tunnels, allocated by a GNU +.BR userv (1) +service. If the server is compromised, an attacker can use it to inject +arbitrary network packets, but little else. +.PP +The ancillary service +.BR watch (8) +needs root privileges in order to configure new network interfaces. It +is written in Python, a safe interpreted language. In turn, this +invokes an external program, again as +.BR root , +to do the actual network interface configuration. This program is +user-selectable, but the default program is a simple shell script; it +does not process untrusted input. +. +.SS "Cryptographic security" +The TrIPE protocol is not standards-based. However, it has been +designed by an experienced cryptographer, and has a formal `security +proof' showing that an attack against the protocol can be transformed +into an attack against one of its primitive components. Other VPN +protocols are too complicated to admit such proofs. The guarantees +afforded by security proofs of this kind are +.I contingent +on the security of the primitive components rather than absolute, but +even such a contingent proof is much better than no proof at all. +.PP +The software allows users a wide selection of primitive components, some +standardized and some not; the author recommends the widely standardized +and well-respected Rijndael (AES) for encryption and SHA256 for hashing +and authentication. +. +.SS "Why TrIPE doesn't use X.509" +The TrIPE protocol does not use X.509 certificates, as deployed in TLS and +IPsec. X.509 certificates are hard to parse: software which processes +them has a history of vulnerabilities. The certification model used by +TLS, where the holder of a key pays a certification authority for his or +her certificate, is economically backwards: the direct beneficiaries of +the certificate are those who rely on it to establish the validity of +the public key. The author does not understand why an external +certificate authority is needed in order to construct a VPN anyway: if +Alice has no idea who Bob is, she's unlikely to want to allow him access +to her private network! +.PP +The main TrIPE software does not assume any particular certification +model: rather, it considers the issue of establish authenticity of +public keys to be out-of-scope. The supplied +.BR tripe-keys (8) +program implements a very simple key-distribution system which avoids +the complexity inherent in X.509. Of course, because public key +distribution is separated from the main system, nothing prevents +swapping in a more sophisticated system where necessary. +. +.SS "Comparison with other systems" +This section compares TrIPE with other VPN protocols. +.TP +.B IPsec +.RS +IPsec is an IETF standard. It defines two protocols for handling bulk +data. The Authentication Header (AH) simply adds cryptographic +authentication to an IP packet, including the header; this causes +trouble with NAT firewalls. The Encapsulating Security Payload (ESP) +provides both encryption and authenticity, and operates in one of two +modes: +.I transport +mode simply processes the payload data, but not the header; the +.I tunnel +mode encapsulates an entire IP packet. Of these, AH and ESP transport +mode need to be supported by all participating hosts. ESP tunnel mode +only needs to be supported by a single representative (`security +gateway') of each network, and provides header security which works +properly with NAT. TrIPE works very similarly to ESP tunnel mode. +The IPsec AH and ESP protocols work directly over IP, rather than using +UDP as TrIPE does. This reduces the per-packet overhead, but means that +implementations need to be highly privileged, either running as part of +the kernel or at least with +.B root +privileges. +.PP +Key exchange in IPsec (IKE) is very complicated, with many options. The +protocol can use a number of different certificate formats, or none at +all. Partly this is due to the fact that IPsec has more ambitious goals +than TrIPE: IPsec aims to allow `opportunistic' security between +previously unrelated entities, whereas TrIPE assumes that all the +participants in its virtual network are administrated in a coordinated +fashion. This means that TrIPE's usefulness is comparatively limited; +of course, it also means that TrIPE is much simpler. +.RE +.TP +.B OpenVPN +.RS +In many respects, OpenVPN is very similar to TrIPE: it runs in userland, +and operates over UDP. OpenVPN uses a variant of the TLS protocol for +its key-exchange. TLS is very complex, and uses X.509 certificates +which bring their own problems. (OpenVPN provides a +.B tls-auth +option to mitigate this, though it partially defeats the point of +public key cryptography.) +.PP +OpenVPN can use TAP interfaces in order to simulate an Ethernet rather +than a point-to-point link, which allows Ethernet bridging across the +VPN. TrIPE could do this relatively easily (it's just a matter of +configuring the tunnel interface differently) but it hasn't seemed +useful yet. +.RE +.TP +.B "SSH- and SSL-based VPNs" +.RS +OpenSSH can implement a simple VPN, by opening tunnel devices at each +end and forwarding packets over the SSH connection. This causes +problems: SSH is already running over TCP, and TCP provides congestion +control and reliability. TCP over this tunnel will therefore have two +layers of congestion control and reliability, and the two have a +tendency to interfere. When there is little or no packet loss, +everything will be fine; if the underlying connection becomes flaky, the +VPN will suffer greatly. +.PP +SSL-based VPNs (simply forwarding packets over an SSL or TLS connection) +have the same problem, and all of the problems associated with SSL's use +of X.509 certificates. +.RE +. +.SS "Firewall considerations" +You should be able to write firewall rules for packets travelling over +TrIPE's tunnel interfaces just as for any other interfaces. +Unfortunately, it is hard to predict the name of the tunnel interface +that TrIPE will allocate for any particular peer. There are two basic +solutions to this problem. +.hP \*o +Some operating systems allow you to rename network interfaces. You can +use this feature to assign the interface a more useful name, which may +already be known to your firewall. +.hP \*o +You can dynamically modify the firewall rules once you know which +interface has been assigned to the peer. This is probably more +complicated. + + + + + + + + + + + + + + + + +. +.SS "Structure of the system" +The TrIPE system consists of a number of components. +.hP \*o +The +.BR tripe (8) +daemon itself. The daemon runs continually in the background. At any +given moment, the daemon knows of a number of +.IR peers : +other servers with which it is meant to interact. It accepts network +packets from the kernel, encrypts them, and sends them to appropriate +peers; it also receives encrypted packets from peers, decrypts them, and +hands them to the kernel. It also provides an administration interface +through which the daemon can be told about new peers, and old ones +removed. +.hP \*o +A number of ancillary services which run alongside the daemon and +provide additional functionality. The +.BR connect (8) +service accepts requests to attach new peers and makes the necessary +arrangements. The +.BR watch (8) +service notices peers being added and removed; it configures network +interfaces; when necessary it attempts to `wake up' remote peers to +inform them of its presence; and it can time out old peers which aren't +responding. This is useful in environments where peers appear and +disappear dynamically. +.hP \*o +The +.BR tripe-keys (8) +utility. The TrIPE system uses asymmetric (`public-key') cryptography. +Therefore it's necessary to ensure that the participants in the VPN have +authentic copies of each others' public keys. This is nontrivial, but +easier than the traditional key-distribution problem, which additionally +involves keeping all of the keys secret. The +.BR tripe-keys (8) +program helps maintain a +.I "certificate authority" +(CA) which can distribute public keys in a secure way. +. +.SS "The basic model" +As far as the TrIPE protocol goes, there is no distinction between +clients and servers, or between initiators and responders. The protocol +treats all participants equally; we call them peers. Each peer knows +about a number of other peers. It establishes point-to-point +communications separately with each peer it knows about. +.PP +Each peer refers to the other peers with whom it communicates by name. +Theoretically, these names are only for the individual peer's (and its +administrator's) convenience, and a single peer may be assigned +completely different names by all of the other peers with which it +communicates. In practise, this would be very confusing, and all peers +use the same, or very similar, names for each other. +.PP +When a daemon is informed about a new peer \(en its name, and an IP +address and port number \(en it creates a new network interface for the +peer and attempts to initiate a key-exchange. If both ends have been +informed of each other's presence, and they have each other's correct +public keys, they will successfully negotiate symmetric keys and be able +to transmit and receive network packets. +.PP +By this point, the daemon has indeed created a network interface, but no +network traffic will actually be carried because the interface is not +configured. The +.BR tripe (8) +daemon leaves the messy details of configuring interfaces to other +programs. If the +.BR watch (8) +service is running, it will notice the new peer, look up its details in +a database, and invoke a script, usually +.BR tripe-ifup (8), +to configure the interface correctly. +. +.SS "Addressing concepts" +Virtual private networks make addressing complicated. This +documentation isn't going to make that complexity go away, but it might +shed some light on it. In particular, each peer involved needs at least +two distinct addresses. +.PP + + + + + + + +.PP +The TrIPE VPN isn't magic. It runs over standard IP, so the machines +you want to participate in the VPN need to be able to send each other IP +packets. + + + + + + In particular, each needs to have an address and port number +\(en its +.I "external address" +(and port) \(en on which it can send and receive packets to/from the +others. +.PP +Additionally, each needs to be able to send packets to the others +.I through +the VPN. The addresses which are routed over the VPN are +.IR "internal addresses" . +Clearly, the internal addresses need to be distinct from the external +addresses if the machines involved are to be able + + +.I "external addresses" +.P +TrIPE has the port number 4070 allocated to it by IANA, so it shouldn't +interfere with anything else. But some firewalls may block TrIPE +traffic, or you may just not want to advertise your use of TrIPE, so you +can use any port you like. + + + +. +.SS "Establishing connections" + + + + +.PP +.PP +The server itself maintains no persistent configuration other than a +simple database of public keys for its various peers. + +.\"-------------------------------------------------------------------------- +.SH "EXAMPLES" +. +This section contains a number of worked examples for configuring and +running TrIPE. +.PP +We'll start with the case of Alice and Bob, who both administer +networks +.B alice.net +and +.B bob.com +respectively, and want them to be able to communicate with each other +securely over the wild Internet. Later we'll deal with Carol, who has a +laptop and wants to be able to connect to the VPN from fleapit hotels +all around the world. +. +.SS "Alice sets herself up as a certificate authority" +Everyone participating in a TrIPE network needs to have a private key +and an +.I authentic +copy of everyone else's public keys. If Bob's copy of Alice's public +key is wrong, then someone else, say Dave, might be able to pretend to +Bob that he's really Alice. +.PP +The easiest way to cope, at least in small networks, is for one person +to be designated as a +.IR "certificate authority" . +The certificate authority's job is to collect authentic copies of +everyone's public keys and make them available to the participants, +signed by the CA's master key. Now all people need to get them started +is a copy of the CA's public key. +.PP +A simple version of this model is supported by the +.BR tripe-keys (8) +program. If you have a large network then the simple single-CA model +won't work for you: see the manual pages for +.BR tripe (8) +and +.BR key (1) +for the details on what you need to do. +.PP +Alice will be the certificate authority in our example. The CA's files +will be stored on +.BR thoth.alice.net , +owned by a dedicated user +.BR tripe-ca , +and stored in +.BR /home/tripe-ca . +To set up the CA, she first creates a configuration file +.B tripe-keys.master +with the contents +.VS +## File locations. +base-url = http://www.alice.net/tripe-keys/ +base-dir = /home/tripe-ca/dist/ +upload-hook = rsync \-az ${base-dir} www.alice.com:/var/www/tripe-keys/ + +## Cryptographic parameters. +kx-expire = now + 1 year +sig-fresh = 1 month ago +sig-expire now + 1 year + +## Master key integrity. +master-sequence = @MASTER-SEQUENCE@ +hk-master = @HK-MASTER@ +.VE +She then runs +.B tripe-keys setup +which runs for a fair while, printing lots of dots to keep her amused. +Eventually it asks her for a passphrase, so she types in a good, strong +passphrase that'll be hard for anyone to guess. It'll ask her to verify +the passphrase, so she types it in again: +.IS +.IC $ "tripe-keys setup" ++ key \-krepos/param add \-adh-param \-LS \-b2048 \-B256 \-eforever +\h'8n'\-tparam tripe-dh-param cipher=blowfish-cbc hash=sha256 +\h'8n'mac=sha256-hmac/128 mgf=sha256-mgf +Searching for p: ...........++ ok +Searching for g: + ok ++ key -kmaster add \-adsa \-b2048 \-B256 \-enow + 1 year \-l +\h'8n'\-tmaster-0 tripe-keys-master sig=dsa hash=sha256 +Searching for q: ..++++++++++++ ok +Searching for p: .................................++ ok +Searching for g: + ok +.IC "New passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase +.IC "Verify passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase ++ key \-kmaster extract \-f\-secret repos/master.pub +.IE +(The lines beginning with +.RB ` + ' +indicate commands that Alice could have run by hand. The +.B tripe-keys +program does a lot of work figuring out sensible defaults to apply.) +.PP +She now has an empty +.I key repository +in the directory +.BR repos , +and a master CA key in the file +.BR master . +(There are also a bunch of +.B .old +files lying around for the sake of paranoia. You can ignore these, or +even delete them if you like.) +.PP +She publishes the empty repository on her webserver by running +.BR "tripe-keys upload" . +This will create a signed copy of her repository and install it on her +webserver. It will need to ask her for her passphrase again. (If she's +running the passphrase pixie +.BR pixie (8) +and she's fairly quick about this, then the pixie will remember the +passphrase and she won't need to type it again.) +.IS +.IC $ "tripe-keys upload" ++ tar chozf /tmp/mdw/tripe-ca/dist/tripe-keys.tar.gz.new . ++ catsign \-kmaster sign \-abdC \-kmaster-0 +\h'8n'\-o/home/tripe-ca/dist/tripe-keys.sig-0.new +\h'8n'/home/tripe-ca/dist/tripe-keys.tar.gz.new +.IC "Passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase ++ sh \-c rsync \-az /tmp/mdw/tripe-ca/dist/ www.alice.net:/var/www/tripe-keys/ +.IE +Alice's CA is now ready! +. +.SS "Alice generates a server key" +She'll need a key for herself, obviously, so she generates one. This +also serves as a sanity check that she's set up the CA properly. +.PP +She's going to run her +.BR tripe (8) +server on a machine called +.BR anubis.alice.net . +She creates +.BR tripe 's +configuration directory +.B \*(c/ +if it doesn't already exist, and makes it current. +.IS +.IC $ "mkdir -p \*(/c" +.IC $ "cd \*(/c" +.IE +The first thing she needs to do is to get a copy of +.B tripe-keys.conf +from her webserver: +.IS +.IC $ "curl \-sS \-O http://www.alice.net/tripe-keys/tripe-keys.conf" +.IE +She must ensure that the copy is authentic. Since she can log into +.B thoth +directly using +.BR ssh (1) +she can use that to check. (She could just have fetched the file from +.B thoth +directly, but that wouldn't test that the webserver was set up properly.) +.IS +.IC $ "hashsum \-armd160 tripe-keys.conf" +#hash rmd160 +0033d67c45027643c43577ff6bd188deb15fa65a tripe-keys.conf +.IC $ "ssh thoth cat /home/tripe-ca/dist/tripe-keys.conf | hashsum \-armd160" +0033d67c45027643c43577ff6bd188deb15fa65a +.IE +Good! Now she can fetch the copy of the empty repository. +.IS +.IC $ "tripe-keys update" ++ curl \-s \-o tripe-keys.tar.gz http://www.alice.net/tripe-keys/tripe-keys.tar.gz ++ curl \-s \-o tripe-keys.sig http://www.alice.net/tripe-keys/tripe-keys.sig-0 ++ tar xfz tripe-keys.tar.gz ++ catsign \-krepos/master.pub verify \-avC \-kmaster-0 \-t1 month ago +\h'8n'tripe-keys.sig tripe-keys.tar.gz +INFO good-signature e3f32b86:tripe-keys-master:master-0 +INFO date 2008-04-09 18:25:39 BST +OK verified successfully +.IE +Joy. Now Alice can actually generate her key. +.IS +.IC $ "tripe-keys generate alice" ++ key \-kkeyring merge repos/param ++ key \-kkeyring add \-adh \-pparam -enow + 1 year \-talice tripe-dh ++ key \-kkeyring extract \-f\-secret peer-alice.pub alice +.IE +At this point, Alice must get her public key, conveniently placed in +.BR peer-alice.pub , +back to her master repository on +.BR thoth . +The easiest way is to log back into +.B thoth +and run +.IS +.IC $ "scp anubis:\*(/c/peer-alice.pub repos/" +.IE +Then all she needs to do is republish the change +.RB ( "tripe-keys upload" +on +.BR thoth ) +and fetch the new version +.RB ( "tripe-keys update" +on +.BR anubis ). +. +.SS "Bob generates his key" +If Alice's and Bob's networks are going to communicate then Bob needs to +generate a key too. The first thing he needs is an +.I authentic +copy of Alice's +.BR tripe-keys.conf . +Fetching it from +.B www.alice.net +using +.BR curl (1) +won't cut it. (Well, maybe if he uses HTTPS and already knows that he +has an authentic copy of the webserver's public key certificate he can +use that.) +.PP +Bob has several options. +.hP \*o +If he knows Alice's voice he can phone her up and get her to +read out the +.BR hashsum (1) +of the file to him. He can compare this to the hash he computed on the +file he got with +.BR curl (1). +.hP \*o +If Alice is geographically close, he can just meet her and she can hand +him either a copy of the hash or the file itself (on some suitable +read-only medium like a CD-R). +.hP \*o +Alternatively, they can use +.BR gnupg (1): +Alice signs her copy of the file and sends it to Bob who verifies it. +Of course, this assumes that he's somehow managed to get an authentic +copy of Alice's OpenPGP key. +.PP +Bob's going to run +.BR tripe (8) +on +.BR bast.bob.com . +He makes +.B \*(/c +be his current directory, and puts his copy of +.B tripe-keys.conf +there. Once he's done that, he runs +.B "tripe-keys update" +to fetch the repository (now with Alice's public key in it), and then +generates his key. +.IC $ "tripe-keys generate bob" ++ key \-kkeyring merge repos/param ++ key \-kkeyring add \-adh \-pparam -enow + 1 year \-tbob tripe-dh ++ key \-kkeyring extract \-f\-secret peer-bob.pub bob +.IE +He now needs to send the file +.B peer-bob.pub +back to Alice, and again they need to ensure the authenticity of the +file that Alice receives. They can use the same methods as they did +before for the configuration file. +.PP +However they manage it, Alice puts her authentic copy of Bob's public +key in +.B /home/tripe-ca/repos/ +on +.B thoth +and runs +.B "tripe-keys upload" +again. +.PP +Finally, both she and Bob need to run +.B "tripe-keys update" +on +.B anubis +and +.B bast +respectively, to install the new collection of public keys. (Actually, +Bob probably needn't bother, but it means that he can check that his +public key is included.) +. +.SS "Alice and Bob set up their servers" +The crypto setup is now done: we move on to the network administration +part. The two networks in question are: +.TP +.B alice.net +uses IP addresses 10.1.0.0/16. The main gateway to the outside world is +.B apophis.alice.net +(10.1.0.1 and 192.0.2.1). +.TP +.B bob.com +uses IP addresses 10.2.0.0/16. The main gateway to the outside world is +.B bast.bob.com +(10.2.0.1 and 192.0.2.65). +.PP +(The internal addresses can, but don't need, to be allocated from the +RFC1918 space. The addresses of the gateway machines, on which +.BR tripe (8) +is running, and which the example has drawn from 192.0.2.0/24, need to +be publicly routable \(en or at least, routable with respect to whatever +networks physically connect them.) +.PP + + +. +.\"-------------------------------------------------------------------------- +.SH "GLOSSARY" +. +In the following entries, terms which are themselves defined in the +glossary are written in +.BR "bold face" . +. +.TP +.B "External address" +The IP address (and port number) used to contact a +.BR peer 's +instance of the +.BR tripe (8) +server. External addresses must usually be proper, publically routable +IP address, i.e., not RFC1918 address. Compare with +.BR "tunnel address" . +.TP +.B "Key exchange" +The process by which two +.BR peer s +verify each other's identity and agree cryptographic keys for securing +the +.B tunnel +between them. +.TP +.B "Peer" +An instance of the +.BR tripe (8) +server running on a remote host. The local server maintains secure +.BR tunnel s +with each of the peers it knows about. +.TP +.B "Private key" +A secret, used by a +.BR tripe (8) +server to prove its identity to its +.BR peer s, +who know the corresponding +.BR "public key" . +.TP +.B "Public key" +A value used by the +.BR tripe (8) +server to verify the identity of its +.BR peer s. +See also +.BR "private key" . +.TP +.B "Tunnel" +The secure virtual network link between two +.BR peer s. +.TP +.B "Tunnel address" +The (possibly private) IP address associated with a particular +.BR peer 's +end of a +.BR tunnel . +Tunnel addresses need not be publically routable, and might reasonably +be allocated from the private-use space defined in RFC1918. Compare +with +.BR "external address" . +. +.\"-------------------------------------------------------------------------- +.SH "SEE ALSO" +. +.SS "Documents provided in the distribution" +.TP +.BR tripe (8) +The main TrIPE server. +.TP +.BR tripectl (1) +Client program for administering the server. +.TP +.BR tripe-admin (5) +Description of the server administration protocol. +.TP +.BR tripe-keys "(8), " tripe-keys.conf (5) +Tool for managing TrIPE public keys. +.TP +.BR tripemon (1) +Graphical monitor program for the TrIPE server. +. +.SS "Other documents" +.TP +.I "The Wrestlers Protocol: A simple, practical, secure, deniable protocol for key-exchange" +Research paper on the protocol TrIPE uses for key exchange. Available +electronically as +.BR http://eprint.iacr.org/2006/386/ . +. +.\"-------------------------------------------------------------------------- +.SH "AUTHOR" +Mark Wooding, +. +.\"----- That's all, folks -------------------------------------------------- -- 2.11.0