chiark / gitweb /
General overhaul of tunnelling: allow multiple tunnel drivers in one daemon,
[tripe] / doc / tripe.8
74eb47db 1.\" -*-nroff-*-
2.\". hP
5\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
6.. VS
8.sp 1
11.ft B
12.. VE
14.ft R
17.sp 1
18.. t \{\
20. ds o \(bu
21. ds ss \s8\u
22. ds se \d\s0
23. if \n(.g \{\
24. fam P
25. \}
27.el \{\
28. ds o o
29. ds ss ^
d6623498 30. ds se
74eb47db 31.\}
32.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
33.SH "NAME"
34tripe \- a simple VPN daemon
36.B tripe
37.RB [ \-D ]
74eb47db 38.RB [ \-d
39.IR dir ]
d13e5724 40.RB [ \-b
41.IR addr ]
33ced0d3 42.RB [ \-p
43.IR port ]
42da2a58 44.RB [ \-n
45.IR tunnel ]
33ced0d3 48.RB [ \-U
49.IR user ]
50.RB [ \-G
51.IR group ]
d13e5724 52.RB [ \-a
53.IR socket ]
54.RB [ \-T
55.IR trace-opts ]
58.RB [ \-k
59.IR priv-keyring ]
60.RB [ \-K
61.IR pub-keyring ]
62.RB [ \-t
63.IR key-tag ]
66.B tripe
67program is a server which can provide strong IP-level encryption and
1a19f865 68authentication between co-operating hosts. The program and its protocol
69are deliberately very simple, to make analysing them easy and to help
70build trust rapidly in the system.
74eb47db 71.SS "Overview"
73.B tripe
74server manages a number of secure connections to other `peer' hosts.
75Each daemon is given a private key of its own, and a file of public keys
76for the peers with which it is meant to communicate. It is responsible
77for negotiating sets of symmetric keys with its peers, and for
78encrypting, encapsulating and sending IP packets to its peers, and
79decrypting, checking and de-encapsulating packets it receives from
82When the server starts, it creates a Unix-domain socket on which it
83listens for administration commands. It also logs warnings and
84diagnostic information to the programs connected to its admin socket.
85Clients connected to the socket can add new peers, and remove or find
86out about existing peers. The textual protocol used to give the
87.B tripe
88server admin commands is described in
89.BR tripe\-admin (5).
90A client program
91.BR tripectl (1)
92is provided to allow commands to be sent to the server either
93interactively or by simple scripts.
94.SS "Command-line arguments"
95If not given any command-line arguments,
96.B tripe
97will initialize by following these steps:
1a19f865 98.hP 1.
99It sets the directory named by the
101environment variable (or
102.B /var/lib/tripe
103if the variable is unset) as the current directory.
104.hP 2.
74eb47db 105It acquires a UDP socket with an arbitrary kernel-selected port number.
106It will use this socket to send and receive all communications with its
107peer servers. The port chosen may be discovered by means of the
108.B PORT
109admin command (see
110.BR tripe\-admin (5)).
1a19f865 111.hP 3.
74eb47db 112It loads the private key with the tag or type name
113.B tripe\-dh
114from the Catacomb-format file
115.BR keyring ,
116and loads the file
118ready for extracting the public keys of peers as they're introduced.
119(The format of these files is described in
120.BR keyring (5).
121They are maintained using the program
122.BR key (1)
123provided with the Catacomb distribution.)
1a19f865 124.hP 4.
74eb47db 125It creates and listens to the Unix-domain socket
126.BR tripesock .
128Following this, the server enters its main loop, accepting admin
129connections and obeying any administrative commands, and communicating
130with peers. It also treats its standard input and standard output
131streams as an admin connection, reading commands from standard input and
33ced0d3 132writing responses and diagnostics messages to standard output. Finally,
133it will reload keys from its keyring files if it notices that they've
134changed (it checks inode number and modification time) \- there's no
135need to send a signal.
74eb47db 136.PP
137Much of this behaviour may be altered by giving
138.B tripe
139suitable command-line options:
141.B "\-h, \-\-help"
142Writes a brief description of the command-line options available to
143standard output and exits with status 0.
145.B "\-v, \-\-version"
147.BR tripe 's
148version number to standard output and exits with status 0.
150.B "\-u, \-\-usage"
151Writes a brief usage summary to standard output and exits with status 0.
42da2a58 153.B "\-\-tunnels"
154Writes to standard output a list of the configured tunnel drivers, one
155per line, and exits with status 0. This is intended for the use of the
3cdc3f3a 156start-up script, so that it can check that it will actually work.
74eb47db 158.B "\-D, \-\-daemon"
159Dissociates from its terminal and starts running in the background after
160completing the initialization procedure described above. If running as
161a daemon,
162.B tripe
163will not read commands from standard input or write diagnostics to
164standard output. A better way to start
165.B tripe
166in the background is with
167.BR tripectl (1).
169.BI "\-d, \-\-directory=" dir
171.I dir
172the current directory, instead of
173.BR /var/lib/tripe .
174Give a current directory of
175.B .
176if you don't want it to change directory at all.
d13e5724 178.BI "\-b, \-\-bind-address="addr
179Bind the UDP socket to IP address
180.I addr
181rather than the default of
183This is useful if your main globally-routable IP address is one you want
184to tunnel through the VPN.
74eb47db 186.BI "\-p, \-\-port=" port
187Use the specified UDP port for all communications with peers, rather
188than an arbitarary kernel-assigned port.
42da2a58 190.BI "\-n, \-\-tunnel=" tunnel
191Use the specified tunnel driver for new peers by default.
33ced0d3 193.BI "\-U, \-\-setuid=" user
194Set uid to that of
195.I user
196(either a user name or integer uid) after initialization. Also set gid
198.IR user 's
199primary group, unless overridden by a
200.B \-G
203.BI "\-G, \-\-setgid=" group
204Set gid to that of
205.I group
206(either a group name or integer gid) after initialization.
74eb47db 208.BI "\-k, \-\-priv\-keyring=" file
209Reads the private key from
210.I file
211rather than the default
212.BR keyring .
214.BI "\-K, \-\-pub\-keyring=" file
215Reads public keys from
216.I file
217rather than the default
218.BR .
219This can be the same as the private keyring, but that's not recommended.
221.BI "\-t, \-\-tag=" tag
222Uses the private key whose tag or type is
223.I tag
224rather than the default
225.BR tripe\-dh .
227.BI "\-a, \-\-admin\-socket=" socket
228Accept admin connections to a Unix-domain socket named
229.I socket
230rather than the default
231.BR tripesock .
233.BI "\-T, \-\-trace=" trace-opts
234Allows the enabling or disabling of various internal diagnostics. See
235below for the list of options.
d6623498 236.SS "Setting up a VPN with tripe"
238.B tripe
239server identifies peers by name. While it's
240.I possible
241for each host to maintain its own naming system for its peers, this is
242likely to lead to confusion, and it's more sensible to organize a naming
243system that works everywhere. How you manage this naming is up to you.
244The only restriction on the format of names is that they must be valid
245Catacomb key tags, since this is how
246.B tripe
247identifies which public key to use for a particular peer: they may not
248contain whitespace characters, or a colon
249.RB ` : '
250or dot
251.RB ` . ',
253Allocating IP addresses for VPNs can get quite complicated. I'll
254attempt to illustrate with a relatively simple example. Our objective
255will be to set up a virtual private network between two sites of
256.BR .
257The two sites are using distinct IP address ranges from the private
258address space described in RFC1918: site A is using addresses from
25910.0.1.0/24 and site B is using Each site has a gateway
260host set up with both an address on the site's private network, and an
261externally-routable address from the public IP address space. Site A's
262gateway machine,
263.BR alice ,
264has the addresses and; site B's gateway is
265.B bob
266and has addresses and
268This isn't quite complicated enough. Each of
269.B alice
271.B bob
272needs an extra IP address which we'll use when setting up the
273point-to-point link. These addresses need to be routable, at least
274within the virtual private network: unfortunately, you can't just use
275the same pair everywhere. We'll assign
276.B alice
277the point-to-point address, and
278.B bob
279the address
280.hP 1.
282.B tripe
283on both of the gateway hosts. Create the directory
284.BR /var/lib/tripe .
285.hP 2.
287.BR alice ,
289.B /var/lib/tripe
290the current directory and generate a Diffie-Hellman group:
74eb47db 292.VS
293key add \-adh\-param \-LS \-b2048 \-B256 \e
294 \-eforever \-tparam tripe\-dh\-param
d6623498 296(See
297.BR key (1)
298from the Catacomb distribution for details about the
299.B key
300command.) Also generate a private key for
301.BR alice :
303key add \-adh \-pparam \-talice \e
304 \-e"now + 1 year" tripe\-dh
306Extract the group parameters and
307.BR alice 's
308public key to
309.I separate
310files, and put the public key in
311.BR :
74eb47db 312.VS
313key extract param param
37075862 314key extract \-f\-secret alice
d6623498 315key \ merge
74eb47db 316.VE
d6623498 317Send the files
318.B param
322.B bob
323in some secure way (e.g., in PGP-signed email, or by using SSH), so that
324you can be sure they've not been altered in transit.
326.hP 3.
328.B bob
329now, make
330.B /var/lib/tripe
331the current directory, and import the key material from
332.BR alice :
74eb47db 334.VS
335key merge param
d6623498 336key \ merge
74eb47db 337.VE
d6623498 338Generate a private key for
339.B bob
340and extract the public half, as before:
74eb47db 341.VS
d6623498 342key add \-adh \-pparam \-tbob \e
343 \-e"now + 1 year" tripe\-dh
383f2a0b 344key extract \-f\-secret bob
d6623498 345key \ merge
74eb47db 346.VE
d6623498 347and send
349back to
350.B alice
351using some secure method.
353.hP 4
355.BR alice ,
357.B bob 's
358key into the public keyring. Now, on each host, run
361key \ fingerprint
363and check that the hashes match. If the two sites have separate
364administrators, they should read the hashes to each other over the
365telephone (assuming that they can recognize each other's voices).
367.hP 5.
368Start the
369.B tripe
370servers up. Run
373tripectl \-slD \-S\-P23169
375on each of
376.B alice
378.BR bob .
380.RB ` \-P23169 '
381forces the server to use UDP port 23169: use some other number if 23169
382is inappropriate for your requirements. I chose it by reducing the
383RIPEMD160 hash of
384.RB ` tripe\-port\-number\e0 '
385modulo 2\*(ss16\*(se.)
387.hP 6.
388To get
389.B alice
390talking to
391.BR bob ,
392run this shell script (or one like it):
395#! /bin/sh
74eb47db 396
d6623498 397tripectl add bob 23169
398ifname=`tripectl ifname bob`
399ifconfig $ifname \e
400 \e
401 pointopoint
402route add -net \e
403 netmask \e
404 gw
407.BR ifconfig (8)
409.BR route (8)
410to find out about your system's variants of these commands. The
411versions shown above assume a Linux system.
412Run a similar script on
413.BR bob ,
414to tell its
415.B tripe
416server to talk to
417.BR alice .
419.hP 7.
420Congratulations. The two servers will exchange keys and begin sending
421packets almost immediately. You've set up a virtual private network.
52c03a2a 422.SS "Using elliptic curve keys"
424.B tripe
425server can use elliptic curve Diffie-Hellman for key exchange, rather
426than traditional integer Diffie-Hellman. Given current public
427knowledge, elliptic curves can provide similar or better security to
428systems based on integer discrete log problems, faster, and with less
429transmitted data. It's a matter of controversy whether this will
430continue to be the case. The author uses elliptic curves.
432The server works out which it
433should be doing based on the key type, which is either
434.B tripe\-dh
435for standard Diffie-Hellman, or
436.B tripe\-ec
437for elliptic curves. To create elliptic curve keys, say something like
439key add \-aec\-param \-Cnist-p192 \-eforever \e
440 \-tparam tripe\-ec\-param
442to construct a parameters key, using your preferred elliptic curve in
444.B \-C
445option (see
446.BR key (1)
447for details); and create the private keys by
449key add \-aec \-pparam \-talice \e
450 \-e"now + 1 year" tripe\-ec
452Now start
453.B tripe
454with the
455.B \-ttripe\-ec
456option, and all should be well.
b5c45da1 457.SS "Using other symmetric algorithms"
458The default symmetric algorithms
459.B tripe
460uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
461(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
462mode, designed by Bellare, Canetti and Krawczyk). These can all be
463overridden by setting attributes on your private key, as follows.
465.B cipher
466Names the symmetric encryption scheme to use. The default is
467.BR blowfish\-cbc .
469.B hash
470Names the hash function to use. The default is
471.BR rmd160 .
473.B mac
474Names the message authentication code to use. The name of the MAC may
475be followed by a
476.RB ` / '
477and the desired tag length in bits. The default is
478.IB hash \-hmac
479at half the underlying hash function's output length.
481.B mgf
482A `mask-generation function', used in the key-exchange. The default is
483.IB hash \-mgf
484and there's no good reason to change it.
b9066fbb 485.SS "Using SLIP interfaces"
486Though not for the faint of heart, it is possible to get
487.B tripe
488to read and write network packets to a pair of file descriptors using
489SLIP encapsulation. No fancy header compression of any kind is
98fdb08d 490supported.
492Two usage modes are supported: a preallocation system, whereby SLIP
493interfaces are created and passed to the
494.B tripe
495server at startup; and a dynamic system, where the server runs a script
496to allocate a new SLIP interface when it needs one. It is possible to
497use a mixture of these two modes, starting
b9066fbb 498.B tripe
98fdb08d 499with a few preallocated interfaces and having it allocate more
500dynamically as it needs them.
502The behaviour of
503.BR tripe 's
504SLIP driver is controlled by the
506environment variable. The server will fail to start if this variable is
507not defined. The variable's value is a colon-delimited list of
508preallocated interfaces, followed optionally by the filename of a script
509to run to dynamically allocate more interfaces.
b9066fbb 510.PP
98fdb08d 511A static allocation entry has the form
b9066fbb 512.IR infd [ \c
513.BI , outfd \c
514.RB ] \c
515.BI = \c
98fdb08d 516.IR ifname ,
b9066fbb 517If the
518.I outfd
519is omitted, the same file descriptor is used for input and output.
98fdb08d 521The dynamic allocation script must be named by an absolute or relative
522pathname, beginning with
523.RB ` / '
525.RB ` . '.
526The server will pass the script an argument, which is the name of the
527peer for which the interface is being created. The script should
528allocate a new SLIP interface (presumably by creating a pty pair),
529configure it appropriately, and write the interface's name to its
530standard output, followed by a newline. It should then read and write
531SLIP packets on its stdin and stdout. The script's stdin will be closed
532when the interface is no longer needed, and the server will attempt to
533send it a
535signal (though this may fail if the script runs with higher privileges
536than the server).
b9066fbb 538The output file descriptor should not block unless it really needs to:
540.B tripe
541daemon assumes that it won't, and will get wait for it to accept output.
74eb47db 542.SS "About the name"
543The program's name is
544.BR tripe ,
545all in lower-case. The name of the protocol it uses is `TrIPE', with
546four capital letters and one lower-case. The name stands for `Trivial
547IP Encryption'.
548.SH "BUGS"
74eb47db 549The code hasn't been audited. It may contain security bugs. If you
550find one, please inform the author
551.IR immediately .
553.BR key (1),
554.BR tripectl (1),
555.BR tripe\-admin (5).
557.IR "The Trivial IP Encryption Protocol" ,
558.IR "The Wrestlers Protocol" .
d36eda2a 560Mark Wooding, <>