5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
32 .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
34 tripe \- a simple VPN daemon
67 program is a server which can provide strong IP-level encryption and
68 authentication between co-operating hosts. The program and its protocol
69 are deliberately very simple, to make analysing them easy and to help
70 build trust rapidly in the system.
74 server manages a number of secure connections to other `peer' hosts.
75 Each daemon is given a private key of its own, and a file of public keys
76 for the peers with which it is meant to communicate. It is responsible
77 for negotiating sets of symmetric keys with its peers, and for
78 encrypting, encapsulating and sending IP packets to its peers, and
79 decrypting, checking and de-encapsulating packets it receives from
82 When the server starts, it creates a Unix-domain socket on which it
83 listens for administration commands. It also logs warnings and
84 diagnostic information to the programs connected to its admin socket.
85 Clients connected to the socket can add new peers, and remove or find
86 out about existing peers. The textual protocol used to give the
88 server admin commands is described in
92 is provided to allow commands to be sent to the server either
93 interactively or by simple scripts.
94 .SS "Command-line arguments"
95 If not given any command-line arguments,
97 will initialize by following these steps:
99 It sets the directory named by the
101 environment variable (or
103 if the variable is unset) as the current directory.
105 It acquires a UDP socket with an arbitrary kernel-selected port number.
106 It will use this socket to send and receive all communications with its
107 peer servers. The port chosen may be discovered by means of the
110 .BR tripe\-admin (5)).
112 It loads the private key with the tag or type name
114 from the Catacomb-format file
118 ready for extracting the public keys of peers as they're introduced.
119 (The format of these files is described in
121 They are maintained using the program
123 provided with the Catacomb distribution.)
125 It creates and listens to the Unix-domain socket
128 Following this, the server enters its main loop, accepting admin
129 connections and obeying any administrative commands, and communicating
130 with peers. It also treats its standard input and standard output
131 streams as an admin connection, reading commands from standard input and
132 writing responses and diagnostics messages to standard output. Finally,
133 it will reload keys from its keyring files if it notices that they've
134 changed (it checks inode number and modification time) \- there's no
135 need to send a signal.
137 Much of this behaviour may be altered by giving
139 suitable command-line options:
142 Writes a brief description of the command-line options available to
143 standard output and exits with status 0.
145 .B "\-v, \-\-version"
148 version number to standard output and exits with status 0.
151 Writes a brief usage summary to standard output and exits with status 0.
154 Writes to standard output a list of the configured tunnel drivers, one
155 per line, and exits with status 0. This is intended for the use of the
156 start-up script, so that it can check that it will actually work.
159 Dissociates from its terminal and starts running in the background after
160 completing the initialization procedure described above. If running as
163 will not read commands from standard input or write diagnostics to
164 standard output. A better way to start
166 in the background is with
169 .BI "\-d, \-\-directory=" dir
172 the current directory. The default directory to change to is given by
173 the environment variable
175 if that's not specified, a default default of
177 is used. Give a current directory of
179 if you don't want it to change directory at all.
181 .BI "\-b, \-\-bind-address="addr
182 Bind the UDP socket to IP address
184 rather than the default of
186 This is useful if your main globally-routable IP address is one you want
187 to tunnel through the VPN.
189 .BI "\-p, \-\-port=" port
190 Use the specified UDP port for all communications with peers, rather
191 than an arbitarary kernel-assigned port.
193 .BI "\-n, \-\-tunnel=" tunnel
194 Use the specified tunnel driver for new peers by default.
196 .BI "\-U, \-\-setuid=" user
199 (either a user name or integer uid) after initialization. Also set gid
202 primary group, unless overridden by a
206 .BI "\-G, \-\-setgid=" group
209 (either a group name or integer gid) after initialization.
211 .BI "\-k, \-\-priv\-keyring=" file
212 Reads the private key from
214 rather than the default
217 .BI "\-K, \-\-pub\-keyring=" file
218 Reads public keys from
220 rather than the default
222 This can be the same as the private keyring, but that's not recommended.
224 .BI "\-t, \-\-tag=" tag
225 Uses the private key whose tag or type is
227 rather than the default
230 .BI "\-a, \-\-admin\-socket=" socket
231 Accept admin connections to a Unix-domain socket named
233 The default socket, if this option isn't specified, is given by the
236 if that's not set either, then a default default of
237 .B "@socketdir@/tripesock"
240 .BI "\-T, \-\-trace=" trace-opts
241 Allows the enabling or disabling of various internal diagnostics. See
242 below for the list of options.
243 .SS "Setting up a VPN with tripe"
246 server identifies peers by name. While it's
248 for each host to maintain its own naming system for its peers, this is
249 likely to lead to confusion, and it's more sensible to organize a naming
250 system that works everywhere. How you manage this naming is up to you.
251 The only restriction on the format of names is that they must be valid
252 Catacomb key tags, since this is how
254 identifies which public key to use for a particular peer: they may not
255 contain whitespace characters, or a colon
260 Allocating IP addresses for VPNs can get quite complicated. I'll
261 attempt to illustrate with a relatively simple example. Our objective
262 will be to set up a virtual private network between two sites of
264 The two sites are using distinct IP address ranges from the private
265 address space described in RFC1918: site A is using addresses from
266 10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
267 host set up with both an address on the site's private network, and an
268 externally-routable address from the public IP address space. Site A's
271 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
273 and has addresses 10.0.2.1 and 200.0.2.1.
277 on both of the gateway hosts. Create the directory
284 the current directory and generate a Diffie-Hellman group:
287 key add \-adh\-param \-LS \-b2048 \-B256 \e
288 \-eforever \-tparam tripe\-dh\-param
292 from the Catacomb distribution for details about the
294 command.) Also generate a private key for
297 key add \-adh \-pparam \-talice \e
298 \-e"now + 1 year" tripe\-dh
300 Extract the group parameters and
304 files, and put the public key in
307 key extract param param
308 key extract \-f\-secret alice.pub alice
309 key \-kkeyring.pub merge alice.pub
317 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
318 you can be sure they've not been altered in transit.
325 the current directory, and import the key material from
330 key \-kkeyring.pub merge alice.pub
332 Generate a private key for
334 and extract the public half, as before:
336 key add \-adh \-pparam \-tbob \e
337 \-e"now + 1 year" tripe\-dh
338 key extract \-f\-secret bob.pub bob
339 key \-kkeyring.pub merge bob.pub
345 using some secure method.
352 key into the public keyring. Now, on each host, run
355 key \-kkeyring.pub fingerprint
357 and check that the hashes match. If the two sites have separate
358 administrators, they should read the hashes to each other over the
359 telephone (assuming that they can recognize each other's voices).
379 run this shell script (or one like it):
384 tripectl add bob 200.0.2.1 4070
385 ifname=`tripectl ifname bob`
386 ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1
388 10.0.2.0 netmask 255.255.255.0 \e
395 to find out about your system's variants of these commands. The
396 versions shown above assume a Linux system.
397 Run a similar script on
405 Congratulations. The two servers will exchange keys and begin sending
406 packets almost immediately. You've set up a virtual private network.
407 .SS "Using elliptic curve keys"
410 server can use elliptic curve Diffie-Hellman for key exchange, rather
411 than traditional integer Diffie-Hellman. Given current public
412 knowledge, elliptic curves can provide similar or better security to
413 systems based on integer discrete log problems, faster, and with less
414 transmitted data. It's a matter of controversy whether this will
415 continue to be the case. The author uses elliptic curves.
417 The server works out which it
418 should be doing based on the key type, which is either
420 for standard Diffie-Hellman, or
422 for elliptic curves. To create elliptic curve keys, say something like
424 key add \-aec\-param \-Cnist-p192 \-eforever \e
425 \-tparam tripe\-ec\-param
427 to construct a parameters key, using your preferred elliptic curve in
432 for details); and create the private keys by
434 key add \-aec \-pparam \-talice \e
435 \-e"now + 1 year" tripe\-ec
441 option, and all should be well.
442 .SS "Using other symmetric algorithms"
443 The default symmetric algorithms
445 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
446 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
447 mode, designed by Bellare, Canetti and Krawczyk). These can all be
448 overridden by setting attributes on your private key, as follows.
451 Names the symmetric encryption scheme to use. The default is
455 Names the hash function to use. The default is
459 Names the message authentication code to use. The name of the MAC may
462 and the desired tag length in bits. The default is
464 at half the underlying hash function's output length.
467 A `mask-generation function', used in the key-exchange. The default is
469 and there's no good reason to change it.
470 .SS "Using SLIP interfaces"
471 Though not for the faint of heart, it is possible to get
473 to read and write network packets to a pair of file descriptors using
474 SLIP encapsulation. No fancy header compression of any kind is
477 Two usage modes are supported: a preallocation system, whereby SLIP
478 interfaces are created and passed to the
480 server at startup; and a dynamic system, where the server runs a script
481 to allocate a new SLIP interface when it needs one. It is possible to
482 use a mixture of these two modes, starting
484 with a few preallocated interfaces and having it allocate more
485 dynamically as it needs them.
489 SLIP driver is controlled by the
491 environment variable. The server will not create SLIP tunnels if this
492 variable is not defined. The variable's value is a colon-delimited list
493 of preallocated interfaces, followed optionally by the filename of a
494 script to run to dynamically allocate more interfaces.
496 A static allocation entry has the form
504 is omitted, the same file descriptor is used for input and output.
506 The dynamic allocation script must be named by an absolute or relative
507 pathname, beginning with
511 The server will pass the script an argument, which is the name of the
512 peer for which the interface is being created. The script should
513 allocate a new SLIP interface (presumably by creating a pty pair),
514 configure it appropriately, and write the interface's name to its
515 standard output, followed by a newline. It should then read and write
516 SLIP packets on its stdin and stdout. The script's stdin will be closed
517 when the interface is no longer needed, and the server will attempt to
520 signal (though this may fail if the script runs with higher privileges
523 The output file descriptor should not block unless it really needs to:
526 daemon assumes that it won't, and will get wedged waiting for it to
529 The program's name is
531 all in lower-case. The name of the protocol it uses is `TrIPE', with
532 four capital letters and one lower-case. The name stands for `Trivial
535 The code hasn't been audited. It may contain security bugs. If you
536 find one, please inform the author
541 .BR tripe\-admin (5).
543 .IR "The Trivial IP Encryption Protocol" ,
544 .IR "The Wrestlers Protocol" .
546 Mark Wooding, <mdw@distorted.org.uk>