+++ /dev/null
-.\" -*-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>
~mdw / tripe / blobdiff