     [file version.texi not included]

This file documents the TrIPE VPN suite version VERSION.

Copyright © 2009 Straylight/Edgeware

     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.

     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.

TrIPE: Trivial IP Encryption
****************************

The GNU General Public License
******************************

     [file gpl.texi not included]

Introduction
************

This chapter explains very briefly what TrIPE is and what this manual aims to tell you about it.

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.

About this manual
=================

This manual provides an overview of the TrIPE software suite.  The individual components are described in their respective reference manual pages.  This page exists to provide a picture for how the various pieces fit together and how to use them effectively.  It presents a number of worked examples, but it's not intended to be used as a `cookbook'; TrIPE is a complicated system, and the author believes that you're less likely to become confused by it if you understand how its various bits fit together rather than following canned recipes which don't quite match your particular circumstances.

This manual is intended for network administrators who are comfortable with the fundamentals of IP networking and routing.  It assumes a reasonable level of knowledge of how to configure network interfaces and routing.  It doesn't assume a strong background in cryptography, though a good grounding won't hurt; the author recommends the Handbook of Applied Cryptography by Alfred Menezes, Paul van Oorschott and Scott Vanstone, which is published by CRC Press, or available online at 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.

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.

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.

mLib, at least version 2.1.0
     A library of C utilities.

Catacomb, at least version 2.1.1
     A cryptographic library.

Python, at least version 2.4
     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.

mLib-python
     Python bindings for mLib; necessary for the connect and watch services which make dynamic connections work (see Connection styles), and the graphical monitor tripemon.

catacomb-python
     Python bindings for Catacomb; necessary for the tripe-keys key-distribution utility: see Key management.

python-cdb, at least version 0.32
     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 libowfat and D. J. Bernstein's public-domain CDB implementation.  CDB is required by the connect and watch services.

GTK+ and pygtk, at least version 2.12
     GTK+ is a user-interface library, originally written by Peter Mattis, Spencer Kimball and Josh MacDonald; it is used by various desktops including GNOME.  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 tripemon.

It may also be useful to have the following items.

The Codespeak py library
     The Codespeak 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 py isn't available.

Building from a source distribution
===================================

If you have a source tarball for TrIPE, you can build the software suite as follows.

 1. Unpack the sources.  The tarball should have a name like tripe-VERSION.tar.gz.  Type

          gzip -dc tripe-VERSION.tar.gz | tar xvf -

     to unpack the sources.  This will create a subdirectory (the source directory) of your current working directory called tripe-VERSION and containing the sources.

 2. Create a directory (the build directory) for the built files to go.  I usually create a subdirectory 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.

 3. Run

          SOURCE-DIRECTORY/configure

     to set up the build directory.  (Here, 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 ../configure.

     You can provide the configure script with command-line options. The most important options are as follows.

     --prefix=PREFIX
          Arranges to install the software under the directory PREFIX -- so executables will end up in PREFIX/bin and so on.  The default is /usr/local.

     --with-configdir=CONFIGDIR
          Arranges to store and look for configuration data in CONFIGDIR. The default is LOCALSTATEDIR/tripe, where LOCALSTATEDIR is itself set by the --localstatedir option and defaults to PREFIX/var.

     See Installation dirs, for a table of installation directories used by TrIPE and the configure options for setting them; run

          SOURCE-DIRECTORY/configure --help

     for a full list of options you can set.

 4. Run

          make

     This will build everything you need.

 5. (Optional, but recommended.)  Run

          make check

     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!)

 6. Run

          make install

     (probably as root) to install most things into their proper places.

 7. The TrIPE suite comes with a script to be run at boot time (see Startup script).  Because systems vary so much in their startup behaviour, TrIPE doesn't attempt to install this anywhere.  This script ends up in init/tripe-init in the build directory.

     On many systems, you should copy it to /etc/init.d (maybe /etc/rc.d/init.d on Red Hat systems; maybe /sbin/init.d on some proprietary Unix systems) and place symbolic links in the /etc/rc?.d (maybe /etc/rc.d/rc?.d or /sbin/rc?.d) directories.

     On traditional BSD systems, it's probably best to copy the script to prefix/sbin/tripe-init, and run

          PREFIX/tripe-init start

     from your /etc/rc.local script.

How to build TrIPE from the sources under version control
=========================================================

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

     git clone git://git.distorted.org.uk/~mdw/tripe

This won't have a configure script or the Makefile.in files provided in the source bundle.  You'll need a number of additional tools.

GNU Autoconf, at least version 2.61
     GNU Autoconf builds configure scripts from m4 descriptions.

GNU Automake, at least version 1.8
     GNU Automake builds Makefile.in files from a high-level declarative description of what needs building.

GNU Libtool, at least version 2.2
     GNU Libtool assists with the complex and messy business of dealing with shared libraries on many different platforms.

Autoconf archive, from 2007--05--12 or later
     A collection of useful Autoconf macros.  You must ensure that the aclocal command can find these macros, e.g., by adding the archive installation directory to the file /usr/share/aclocal/dirlist.  See Macro search path (GNU Automake).

Common Files Distribution, at least version 1.3.4
     The Common Files Distribution collects together a number of files which need to be included in many projects, and provides tools for managing them.

If you have these properly installed, it should be sufficient to run

     mdw-setup

in the source tree before following the instructions for building from a source distribution: see Building.

Where everything is installed
=============================

This section provides a handy description of where files are placed by TrIPE's installation system.

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 configure-script arguments to modify them.

Directory name
Default
Debian
Option

PREFIX
/usr/local
/usr
--prefix

EXEC-PREFIX
PREFIX
/usr
--exec-prefix

BINDIR
EXEC-PREFIX/bin
/usr/bin
--bindir

SBINDIR
EXEC-PREFIX/sbin
/usr/sbin
--sbindir

LIBDIR
EXEC-PREFIX/lib
/usr/lib
--libdir

LIBEXECDIR
EXEC-PREFIX/libexec
/usr/lib
--libexecdir

DATAROOTDIR
PREFIX/share
/usr/share
--datarootdir

DATADIR
DATAROOTDIR
/usr/share
--datadir

SYSCONFDIR
PREFIX/etc
/etc
--sysconfdir

CONFIGDIR
PREFIX/var/tripe
/etc/tripe
--with-configdir

MANDIR
DATAROOTDIR/man
/usr/share/man
--mandir

INFODIR
DATAROOTDIR/info
/usr/share/info
--infodir

DOCDIR
DATAROOTDIR/doc/tripe
/usr/share/doc/tripe
--docdir

SOCKETDIR
.
/var/run
--with-socketdir

PYTHONDIR
Depends on Python installation
/usr/lib/pythonVER/site-packages
None

WIRESHARKDIR
Depends on Wireshark installation
/usr/lib/wireshark/plugins
--with-wireshark

In addition, there are some configure-time settings which affect the locations of individual files.  These are as follows.

Directory name
Default
Debian
Option

LOGFILE
./tripe.log
/var/log/tripe.log
--with-logfile

PIDFILE
./tripectl.pid
/var/run/tripectl.pid
--with-pidfile

INITCONFIG
SYSCONFDIR/tripe.conf
/etc/default/tripe
--with-initconfig

The relative pathnames shown above are relative to the working directory of the process.  Most TrIPE programs set their working directory to CONFIGDIR when they start up, unless a different directory is specified on the command line.

File locations
--------------

The following table shows the locations of all the files in the distribution.

INFODIR
     tripe.info -- this manual, in GNU Info format.

     (There may possibly be other files, depending on whether makeinfo decided to split it into parts).  Prebuilt binary packages may have compressed the info manual.

MANDIR
     The various manual pages.  Manual pages are placed into sections (following the Linux numbering convention).  Manual pages in section N are placed in MANDIR/manN.  Prebuilt binary packages may have compressed the manual pages.

DOCDIR
     tripe.pdf -- this manual, in Adobe PDF.

     tripe.html/index.html (and others) -- this manual, in HTML.

     Prebuilt binary packages may have compressed the PDF file.

BINDIR
     pkstream -- a utility for transporting UDP packets over streams

     tripe-uslip -- a utility for testing the tripe(8) server

     tripemon -- a graphical monitor program for TrIPE

     pathmtu -- a utility for determining the path-MTU to a given host

     tripe-mitm -- a hostile proxy for the TrIPE protocol

     tripectl -- a client program for communicating with the tripe(8) server

     Some of these programs may be missing from your distribution.  The tripe-uslip and tripe-mitm programs aren't particularly useful in day-to-day operations, and aren't considered further in this manual.

SBINDIR
     tripe -- the main server

     tripe-newpeers -- build the peer database from text configuration

     tripe-keys -- a utility for generating and distributing keys

     tripe-ifup -- a script for configuring network interfaces

LIBEXECDIR/tripe
     tripe-privhelper -- a program used internally by the tripe(8) server to open network-tunnel devices.  The server drops root privileges early on during its initialization; before doing so, it starts a tripe-privhelper process.

     services/connect and services/watch -- ancillary peer-management services described later.

LIBDIR/pkgconfig
     tripe.pc -- a pkg-config(1) file, which allows other packages to find out how TrIPE has been installed.

PYTHONDIR
     tripe.py -- Python module for communicating with tripe(8) server

     rmcr.py -- Python module implementing coroutines in terms of threads

     There may also be .pyc and .pyo files installed here.

WIRESHARKDIR
     tripe.so -- Wireshark plugin for dissecting TrIPE protocol traces

     There may also be .a and .la files installed here.

CONFIGDIR
     peers.d/10base -- base configuration for peers database.

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.

The main server
===============

The server 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 keyrings.  There are two keyrings: the private keyring contains the server's private key, which it uses to prove its identity to its peers; and the 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 key(1) program included in the Catacomb distribution: detailed information about the attributes TrIPE expects on its keys is provided in the tripe(8) manpage.  But it's easier to use the tripe-keys(8) system (see Key management) to maintain the keyrings.

Apart from the two keyrings, the server obtains configuration data from two sources.

 1. 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: see Startup script.  The server command line is described in full in tripe(8).

 2. It provides an interactive administration interface through which other processes can issue commands and read status information dynamically.  You can use the tripectl(1) program to issue administrative commands; see tripe-admin(5) for full details about the commands available.

Key management utility
======================

Key management and distribution is a complicated topic, dealt with fully in its own chapter.

The 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 tripe-keys.master.

From this master file, tripe-keys(8) constructs a 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 tripe-keys(8) utility assists with key generation and secure distribution of public keys.

For full details, see Key management.

The startup 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 /etc/init.d/tripe; other possible locations are /etc/rc.d/init.d/tripe (e.g., Red Hat, AIX), /sbin/init.d/tripe (e.g., SuSE, HP-UX) or /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 configure script is /etc/tripe.conf; however, the Debian package places it in /etc/default/tripe.

The startup script invokes tripe via the 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 CONFIGDIR/services and CONFIGDIR/peers directories.  The services scripts are invoked as

     SCRIPT --daemon --startup

while the peers scripts are not passed arguments.

The intent is that symbolic links to programs providing useful services can be placed in CONFIGDIR/services so that they'll start automatically when tripe(8) starts.  The options --daemon and --startup are common to all service providers (see tripe-service(7) for details).

The CONFIGDIR/peers directory is intended for scripts which establish connections with specific peers.  A simple example script might be something like this.

     #! /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

Stashing this file as CONFIGDIR/peers/vampire would cause the server to establish a connection with vampire on startup, and configure the tunnel interface accordingly.  Configuration using peers scripts is fairly versatile but tedious; the peer services provide a better approach.  This manual won't discuss peers scripts any further.

Peer services
=============

As mentioned earlier (see Server), the main server provides an administration interface which accepts configuration commands and provides status information.  This interface can be extended by ancillary 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.

connect
     A fairly simple service for requesting the setup of new connections.

watch
     A more complex service, which reacts to connections being established and terminated (e.g., by configuring network interfaces).

In addition, there is a shell script 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 peer database, stored in CONFIGDIR/peers.cdb.  This database is constructed from textual input files by a program tripe-newpeers(8).  The services and script obtain all of their configuration from the database, and don't examine the source files at all.

Managing TrIPE configuration using GNU Make
===========================================

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 peers.d, and use GNU Make's wildcard function to keep track of them: see The Function wildcard (GNU make).

My Makefile is as follows.

     ### 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

It's intended to be placed into the CONFIGDIR directory and invoked by root.  It assumes that a tripe-keys.conf file has been placed alongside.  Now I can run

     make

after changing or adding peers, and

     make update

to update my public keyring.  The tripe(8) server and the various peer services will notice the new keyring and peer database and reload them automatically.

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, see Networking.

Port number
===========

The 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 port variable in the startup script configuration file: see 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 getservbyname(3), with protocol name udp, so you'll probably need to edit /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.

Users and groups
================

The tripe() server doesn't have to run with full root privileges.  However, it does need to be able to open `tunnel interfaces', and this usually requires special privilege.

Networking concepts
*******************

This chapter explains how TrIPE thinks about networks, and how to go about fitting TrIPE into your network design.

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 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 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 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.

Example
-------

Alice is the administrator of alice.net.  Internally, she has allocated IP addresses from the private address range 10.0.1.0/24.  She has an externally facing server 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 bob.com.  Internally, he's allocated IP addresses from the private address range 10.0.2.0/24.  He has an externally facing server bast.bob.com, which has an internal address of 10.0.2.1 and an external address of 192.0.2.129. (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 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 anubis and bast as their respective TrIPE representatives.  If, say, 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 alice.net and bob.com don't know how to send packets there.

We'll return to Alice and Bob in other examples later.

Tunnels and routing
===================

A 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 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 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.

  * a route to its peer's external address, so that it can send it encrypted packets encapsulated in UDP;

  * a route to the peer's internal address, directed over the tunnel interface; and possibly

  * if the peer is acting as a representative for a network of other hosts, a route to that network also over the tunnel.

Example
-------

Continuing the earlier example (see Addressing example) anubis.alice.net needs to have one route to bast.bob.com external address 192.0.2.129.  We'll assume that 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 bast.bob.com, anubis has its tripe-bob interface configured as follows. (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.)

     ifconfig tripe-bob 10.0.1.1 pointopoint 10.0.2.1 mtu 1435

Further, in order to communicate with the larger bob.com internal network, anubis has set up an additional route

     route add -net 10.0.2.0/24 gw 10.0.2.1 dev tripe-bob metric 2

Other hosts in Alice's network might need to be told

     route add -net 10.0.2.0/24 gw 10.0.1.1 metric 3

(spot the difference between this and anubis's route), though in many cases it's useful to choose the TrIPE representative as a router anyway.

Connection styles
=================

There are essentially two kinds of connections possible between TrIPE peers.

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.

Dynamic
     One of the peers explicitly establishes a connection with the other when it wants to communicate.  The active peer -- the one making the connection -- doesn't need a stable static IP address.  The 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.

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.

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.

  * 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.

  * You can dynamically modify the firewall rules once you know which interface has been assigned to the peer.  This is probably more complicated.

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 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.

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.

Cryptographic objectives
========================

The earliest cryptographic objective is secrecy: transforming a message into a 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 encryption, and the recovery of the message from the ciphertext is decryption.

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 integrity or authenticity.

Symmetric and asymmetric cryptography
=====================================

Setting TrIPE up
****************

Establishing the certificate authority
======================================

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.

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 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 userv(1) service.  If the server is compromised, an attacker can use it to inject arbitrary network packets, but little else.

The ancillary service 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 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.

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 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 The Wrestlers Protocol: A simple, practical, secure, deniable protocol for key-exchange, by Mark Wooding, available electronically as 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.

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!

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 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.

Comparison with other systems
*****************************

This chapter compares TrIPE with other VPN protocols.

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: transport mode simply processes the payload data, but not the header; the 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 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.

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 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.

SSH- and 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.

Pay no attention to the man behind the curtain
**********************************************

Here are nodes which aren't yet written.

FIXME
=====