.el \{\
. ds o o
. ds ss ^
-. ds se _
+. ds se
.\}
.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "NAME"
.SH "SYNOPSIS"
.B tripe
.RB [ \-D ]
-.RB [ \-p
-.IR port ]
-.RB [ \-T
-.IR trace-opts ]
.RB [ \-d
.IR dir ]
+.RB [ \-b
+.IR addr ]
+.RB [ \-p
+.IR port ]
+.RB [ \-n
+.IR tunnel ]
+.br
+
+.RB [ \-U
+.IR user ]
+.RB [ \-G
+.IR group ]
.RB [ \-a
.IR socket ]
+.RB [ \-T
+.IR trace-opts ]
.br
.RB [ \-k
The
.B tripe
program is a server which can provide strong IP-level encryption and
-authentication between two 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.
+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
If not given any command-line arguments,
.B tripe
will initialize by following these steps:
-.hP \*o
-It changes directory to
-.BR /var/lib/tripe .
-.hP \*o
+.hP 1.
+It sets the directory named by the
+.B TRIPEDIR
+environment variable (or
+.B /var/lib/tripe
+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 \*o
+.hP 3.
It loads the private key with the tag or type name
.B tripe\-dh
from the Catacomb-format file
They are maintained using the program
.BR key (1)
provided with the Catacomb distribution.)
-.hP \*o
+.hP 4.
It creates and listens to the Unix-domain socket
.BR tripesock .
.PP
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.
+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
.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
.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
.BI "\-T, \-\-trace=" trace-opts
Allows the enabling or disabling of various internal diagnostics. See
below for the list of options.
-.SS "Key management"
-The TrIPE protocol requires all cooperating hosts to be using keys
-with the same group parameters. A suitable group may be created with the
-command:
+.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
-This creates a `parameters' key labelled
-.B param
-in your keyring file: it doesn't contain any secrets. You may vary the
-security parameters
-.B \-b
-and
-.B \-B
-to taste: the ones given provide good security, at the expense of
-performance. Even so, from a cryptographic point of view, these keys
-will be the weak point in the security of the system. Generation of the
-group parameters can take a few minutes.
-.PP
-You should extract the parameters from your keyring and distribute them
-(securely) to the other administrators. The parameters may be extracted
-from your keyring with the command:
+(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
-This may be merged into a keyring with:
+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
-Once your keyring contains the parameters, a suitable key can be created
-with the command:
+Generate a private key for
+.B bob
+and extract the public half, as before:
.VS
-key add \-adh \-pparam \-e"now + 1 year" tripe\-dh
+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
-This creates a Diffie-Hellman key using the parameters from key
-.B param
-which expires in one year. The new key has type
-.BR tripe\-dh .
+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 \-S\-p22003
+.VE
+on each of
+.B alice
+and
+.BR bob .
+(The
+.RB ` \-p22003 '
+forces the server to use UDP port 22003: use some other number if 22003
+is inappropriate for your requirements. I chose it by taking the first
+16 bits of the RIPEMD160 hash of
+.RB ` TrIPE '.
+.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 22003
+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 ,
four capital letters and one lower-case. The name stands for `Trivial
IP Encryption'.
.SH "BUGS"
-It's too easy to deny service during key exchange. If both ends are
-honest, they'll notice any interference and resend their packets, but
-it's possible to delay successful negotation for as long as desired by
-sending bogus key exchange messages.
-.PP
The code hasn't been audited. It may contain security bugs. If you
find one, please inform the author
.IR immediately .
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blobdiff