--- /dev/null
+\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
--- /dev/null
+.\" -*-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, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / tripe / commitdiff