Documentation restructuring: provide a useful overview.

[tripe] / manual / tripe.texi

\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