doc/tripe.8: Fix layout of synopsis section.

[tripe] / doc / tripe.8.in

.\" -*-nroff-*-
.\".
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.ie t \{\
.  ds o \(bu
.  ds ss \s8\u
.  ds se \d\s0
.  if \n(.g \{\
.    fam P
.  \}
.\}
.el \{\
.  ds o o
.  ds ss ^
.  ds se
.\}
.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "NAME"
tripe \- a simple VPN daemon
.SH "SYNOPSIS"
.B tripe
.RB [ \-D ]
.RB [ \-d
.IR dir ]
.RB [ \-b
.IR addr ]
.RB [ \-p
.IR port ]
.RB [ \-n
.IR tunnel ]
.br
	\c
.RB [ \-U
.IR user ]
.RB [ \-G
.IR group ]
.RB [ \-a
.IR socket ]
.RB [ \-T
.IR trace-opts ]
.br
	\c
.RB [ \-k
.IR priv-keyring ]
.RB [ \-K
.IR pub-keyring ]
.RB [ \-t
.IR key-tag ]
.SH "DESCRIPTION"
The
.B tripe
program is a server which can provide strong IP-level encryption and
authentication between co-operating hosts.  The program and its protocol
are deliberately very simple, to make analysing them easy and to help
build trust rapidly in the system.
.SS "Overview"
The
.B tripe
server manages a number of secure connections to other `peer' hosts.
Each daemon is given a private key of its own, and a file of public keys
for the peers with which it is meant to communicate.  It is responsible
for negotiating sets of symmetric keys with its peers, and for
encrypting, encapsulating and sending IP packets to its peers, and
decrypting, checking and de-encapsulating packets it receives from
them.
.PP
When the server starts, it creates a Unix-domain socket on which it
listens for administration commands.  It also logs warnings and
diagnostic information to the programs connected to its admin socket.
Clients connected to the socket can add new peers, and remove or find
out about existing peers.  The textual protocol used to give the
.B tripe
server admin commands is described in
.BR tripe\-admin (5).
A client program
.BR tripectl (1)
is provided to allow commands to be sent to the server either
interactively or by simple scripts.
.SS "Command-line arguments"
If not given any command-line arguments,
.B tripe
will initialize by following these steps:
.hP 1.
It sets the directory named by the
.B TRIPEDIR
environment variable (or
.B "@configdir@"
if the variable is unset) as the current directory.
.hP 2.
It acquires a UDP socket with an arbitrary kernel-selected port number.
It will use this socket to send and receive all communications with its
peer servers.  The port chosen may be discovered by means of the
.B PORT
admin command (see
.BR tripe\-admin (5)).
.hP 3.
It loads the private key with the tag or type name
.B tripe\-dh
from the Catacomb-format file
.BR keyring ,
and loads the file
.B keyring.pub
ready for extracting the public keys of peers as they're introduced.
(The format of these files is described in
.BR keyring (5).
They are maintained using the program
.BR key (1)
provided with the Catacomb distribution.)
.hP 4.
It creates and listens to the Unix-domain socket
.BR tripesock .
.PP
Following this, the server enters its main loop, accepting admin
connections and obeying any administrative commands, and communicating
with peers.  It also treats its standard input and standard output
streams as an admin connection, reading commands from standard input and
writing responses and diagnostics messages to standard output.  Finally,
it will reload keys from its keyring files if it notices that they've
changed (it checks inode number and modification time) \- there's no
need to send a signal.
.PP
Much of this behaviour may be altered by giving
.B tripe
suitable command-line options:
.TP
.B "\-h, \-\-help"
Writes a brief description of the command-line options available to
standard output and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes
.BR tripe 's
version number to standard output and exits with status 0.
.TP
.B "\-u, \-\-usage"
Writes a brief usage summary to standard output and exits with status 0.
.TP
.B "\-\-tunnels"
Writes to standard output a list of the configured tunnel drivers, one
per line, and exits with status 0.  This is intended for the use of the
start-up script, so that it can check that it will actually work.
.TP
.B "\-D, \-\-daemon"
Dissociates from its terminal and starts running in the background after
completing the initialization procedure described above.  If running as
a daemon,
.B tripe
will not read commands from standard input or write diagnostics to
standard output.  A better way to start
.B tripe
in the background is with
.BR tripectl (1).
.TP
.BI "\-d, \-\-directory=" dir
Makes
.I dir
the current directory.  The default directory to change to is given by
the environment variable
.BR TRIPEDIR ;
if that's not specified, a default default of
.B "@configdir@"
is used.  Give a current directory of
.B .
if you don't want it to change directory at all.
.TP
.BI "\-b, \-\-bind-address="addr
Bind the UDP socket to IP address
.I addr
rather than the default of
.BR INADDR_ANY .
This is useful if your main globally-routable IP address is one you want
to tunnel through the VPN.
.TP
.BI "\-p, \-\-port=" port
Use the specified UDP port for all communications with peers, rather
than an arbitarary kernel-assigned port.
.TP
.BI "\-n, \-\-tunnel=" tunnel
Use the specified tunnel driver for new peers by default.
.TP
.BI "\-U, \-\-setuid=" user
Set uid to that of
.I user
(either a user name or integer uid) after initialization.  Also set gid
to
.IR user 's
primary group, unless overridden by a
.B \-G
option.
.TP
.BI "\-G, \-\-setgid=" group
Set gid to that of
.I group
(either a group name or integer gid) after initialization.
.TP
.BI "\-k, \-\-priv\-keyring=" file
Reads the private key from
.I file
rather than the default
.BR keyring .
.TP
.BI "\-K, \-\-pub\-keyring=" file
Reads public keys from
.I file
rather than the default
.BR keyring.pub .
This can be the same as the private keyring, but that's not recommended.
.TP
.BI "\-t, \-\-tag=" tag
Uses the private key whose tag or type is
.I tag
rather than the default
.BR tripe\-dh .
.TP
.BI "\-a, \-\-admin\-socket=" socket
Accept admin connections to a Unix-domain socket named
.IR socket .
The default socket, if this option isn't specified, is given by the
environment variable
.BR TRIPESOCK ;
if that's not set either, then a default default of
.B "@socketdir@/tripesock"
is used instead.
.TP
.BI "\-T, \-\-trace=" trace-opts
Allows the enabling or disabling of various internal diagnostics.  See
below for the list of options.
.SS "Setting up a VPN with tripe"
The
.B tripe
server identifies peers by name.  While it's
.I possible
for each host to maintain its own naming system for its peers, this is
likely to lead to confusion, and it's more sensible to organize a naming
system that works everywhere.  How you manage this naming is up to you.
The only restriction on the format of names is that they must be valid
Catacomb key tags, since this is how
.B tripe
identifies which public key to use for a particular peer: they may not
contain whitespace characters, or a colon
.RB ` : '
or dot
.RB ` . ',
.PP
Allocating IP addresses for VPNs can get quite complicated.  I'll
attempt to illustrate with a relatively simple example.  Our objective
will be to set up a virtual private network between two sites of
.BR example.com .
The two sites are using distinct IP address ranges from the private
address space described in RFC1918: site A is using addresses from
10.0.1.0/24 and site B is using 10.0.2.0/24.  Each site has a gateway
host set up with both an address on the site's private network, and an
externally-routable address from the public IP address space.  Site A's
gateway machine,
.BR alice ,
has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
.B bob
and has addresses 10.0.2.1 and 200.0.2.1.
.hP 1.
Install
.B tripe
on both of the gateway hosts.  Create the directory
.BR /var/lib/tripe .
.hP 2.
On
.BR alice ,
make
.B /var/lib/tripe
the current directory and generate a Diffie-Hellman group:
.RS
.VS
key add \-adh\-param \-LS \-b2048 \-B256 \e
	\-eforever \-tparam tripe\-dh\-param
.VE
(See
.BR key (1)
from the Catacomb distribution for details about the
.B key
command.)  Also generate a private key for
.BR alice :
.VS
key add \-adh \-pparam \-talice \e
	\-e"now + 1 year" tripe\-dh
.VE
Extract the group parameters and
.BR alice 's
public key to
.I separate
files, and put the public key in
.BR keyring.pub :
.VS
key extract param param
key extract \-f\-secret alice.pub alice
key \-kkeyring.pub merge alice.pub
.VE
Send the files
.B param
and
.B alice.pub
to
.B bob
in some secure way (e.g., in PGP-signed email, or by using SSH), so that
you can be sure they've not been altered in transit.
.RE
.hP 3.
On
.B bob
now, make
.B /var/lib/tripe
the current directory, and import the key material from
.BR alice :
.RS
.VS
key merge param
key \-kkeyring.pub merge alice.pub
.VE
Generate a private key for
.B bob
and extract the public half, as before:
.VS
key add \-adh \-pparam \-tbob \e
	\-e"now + 1 year" tripe\-dh
key extract \-f\-secret bob.pub bob
key \-kkeyring.pub merge bob.pub
.VE
and send
.B bob.pub
back to
.B alice
using some secure method.
.RE
.hP 4
On
.BR alice ,
merge
.B bob 's
key into the public keyring.  Now, on each host, run
.RS
.VS
key \-kkeyring.pub fingerprint
.VE
and check that the hashes match.  If the two sites have separate
administrators, they should read the hashes to each other over the
telephone (assuming that they can recognize each other's voices).
.RE
.hP 5.
Start the
.B tripe
servers up.  Run
.RS
.VS
tripectl \-slD
.VE
on each of
.B alice
and
.BR bob .
.RE
.hP 6.
To get
.B alice
talking to
.BR bob ,
run this shell script (or one like it):
.RS
.VS
#! /bin/sh

tripectl add bob 200.0.2.1 4070
ifname=`tripectl ifname bob`
ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1
route add -net \e
	10.0.2.0 netmask 255.255.255.0 \e
	gw 10.0.2.1
.VE
Read
.BR ifconfig (8)
and
.BR route (8)
to find out about your system's variants of these commands.  The
versions shown above assume a Linux system.
Run a similar script on
.BR bob ,
to tell its
.B tripe
server to talk to
.BR alice .
.RE
.hP 7.
Congratulations.  The two servers will exchange keys and begin sending
packets almost immediately.  You've set up a virtual private network.
.SS "Using elliptic curve keys"
The
.B tripe
server can use elliptic curve Diffie-Hellman for key exchange, rather
than traditional integer Diffie-Hellman.  Given current public
knowledge, elliptic curves can provide similar or better security to
systems based on integer discrete log problems, faster, and with less
transmitted data.  It's a matter of controversy whether this will
continue to be the case.  The author uses elliptic curves.
.PP
The server works out which it
should be doing based on the key type, which is either
.B tripe\-dh
for standard Diffie-Hellman, or
.B tripe\-ec
for elliptic curves.  To create elliptic curve keys, say something like
.VS
key add \-aec\-param \-Cnist-p192 \-eforever \e
	\-tparam tripe\-ec\-param
.VE
to construct a parameters key, using your preferred elliptic curve in
the
.B \-C
option (see
.BR key (1)
for details); and create the private keys by
.VS
key add \-aec \-pparam \-talice \e
	\-e"now + 1 year" tripe\-ec
.VE
Now start
.B tripe
with the
.B \-ttripe\-ec
option, and all should be well.
.SS "Using other symmetric algorithms"
The default symmetric algorithms
.B tripe
uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
mode, designed by Bellare, Canetti and Krawczyk).  These can all be
overridden by setting attributes on your private key, as follows.
.TP
.B cipher
Names the symmetric encryption scheme to use.  The default is
.BR blowfish\-cbc .
.TP
.B hash
Names the hash function to use.  The default is
.BR rmd160 .
.TP
.B mac
Names the message authentication code to use.  The name of the MAC may
be followed by a
.RB ` / '
and the desired tag length in bits.  The default is
.IB hash \-hmac
at half the underlying hash function's output length.
.TP
.B mgf
A `mask-generation function', used in the key-exchange.  The default is
.IB hash \-mgf
and there's no good reason to change it.
.SS "Using SLIP interfaces"
Though not for the faint of heart, it is possible to get
.B tripe
to read and write network packets to a pair of file descriptors using
SLIP encapsulation.  No fancy header compression of any kind is
supported.
.PP
Two usage modes are supported: a preallocation system, whereby SLIP
interfaces are created and passed to the
.B tripe
server at startup; and a dynamic system, where the server runs a script
to allocate a new SLIP interface when it needs one.  It is possible to
use a mixture of these two modes, starting
.B tripe
with a few preallocated interfaces and having it allocate more
dynamically as it needs them.
.PP
The behaviour of
.BR tripe 's
SLIP driver is controlled by the
.B TRIPE_SLIPIF
environment variable.  The server will not create SLIP tunnels if this
variable is not defined.  The variable's value is a colon-delimited list
of preallocated interfaces, followed optionally by the filename of a
script to run to dynamically allocate more interfaces.
.PP
A static allocation entry has the form
.IR infd [ \c
.BI , outfd \c
.RB ] \c
.BI = \c
.IR ifname ,
If the
.I outfd
is omitted, the same file descriptor is used for input and output.
.PP
The dynamic allocation script must be named by an absolute or relative
pathname, beginning with
.RB ` / '
or
.RB ` . '.
The server will pass the script an argument, which is the name of the
peer for which the interface is being created.  The script should
allocate a new SLIP interface (presumably by creating a pty pair),
configure it appropriately, and write the interface's name to its
standard output, followed by a newline.  It should then read and write
SLIP packets on its stdin and stdout.  The script's stdin will be closed
when the interface is no longer needed, and the server will attempt to
send it a
.B SIGTERM
signal (though this may fail if the script runs with higher privileges
than the server).
.PP
The output file descriptor should not block unless it really needs to:
the
.B tripe
daemon assumes that it won't, and will get wedged waiting for it to
accept output.
.SS "About the name"
The program's name is
.BR tripe ,
all in lower-case.  The name of the protocol it uses is `TrIPE', with
four capital letters and one lower-case.  The name stands for `Trivial
IP Encryption'.
.SH "BUGS"
The code hasn't been audited.  It may contain security bugs.  If you
find one, please inform the author
.IR immediately .
.SH "SEE ALSO"
.BR key (1),
.BR tripectl (1),
.BR tripe\-admin (5).
.PP
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>