.RB [ \-D ]
.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
.IR pub-keyring ]
.RB [ \-t
.IR key-tag ]
-.br
-
-.RB [ \-a
-.IR socket ]
-.RB [ \-T
-.IR trace-opts ]
.SH "DESCRIPTION"
The
.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
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.
-.PP
-This isn't quite complicated enough. Each of
-.B alice
-and
-.B bob
-needs an extra IP address which we'll use when setting up the
-point-to-point link. These addresses need to be routable, at least
-within the virtual private network: unfortunately, you can't just use
-the same pair everywhere. We'll assign
-.B alice
-the point-to-point address 192.168.0.1, and
-.B bob
-the address 192.168.0.2.
.hP 1.
Install
.B tripe
servers up. Run
.RS
.VS
-tripectl \-slD \-S\-P23169
+tripectl \-slD \-S\-p22003
.VE
on each of
.B alice
and
.BR bob .
(The
-.RB ` \-P23169 '
-forces the server to use UDP port 23169: use some other number if 23169
-is inappropriate for your requirements. I chose it by reducing the
-RIPEMD160 hash of
-.RB ` tripe\-port\-number\e0 '
-modulo 2\*(ss16\*(se.)
+.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
.VS
#! /bin/sh
-tripectl add bob 200.0.2.1 23169
+tripectl add bob 200.0.2.1 22003
ifname=`tripectl ifname bob`
-ifconfig $ifname \e
- 192.168.0.1 \e
- pointopoint 192.168.0.2
+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 192.168.0.2
+ gw 10.0.2.1
.VE
Read
.BR ifconfig (8)
.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 ,
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>