chiark / gitweb /
New environment variable TRIPESOCK.
[tripe] / doc /
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
797cf76b 102.B "@configdir@"
1a19f865 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. The default directory to change to is given by
173the environment variable
175if that's not specified, a default default of
176.B "@configdir@"
177is used. Give a current directory of
74eb47db 178.B .
179if you don't want it to change directory at all.
d13e5724 181.BI "\-b, \-\-bind-address="addr
182Bind the UDP socket to IP address
183.I addr
184rather than the default of
186This is useful if your main globally-routable IP address is one you want
187to tunnel through the VPN.
74eb47db 189.BI "\-p, \-\-port=" port
190Use the specified UDP port for all communications with peers, rather
191than an arbitarary kernel-assigned port.
42da2a58 193.BI "\-n, \-\-tunnel=" tunnel
194Use the specified tunnel driver for new peers by default.
33ced0d3 196.BI "\-U, \-\-setuid=" user
197Set uid to that of
198.I user
199(either a user name or integer uid) after initialization. Also set gid
201.IR user 's
202primary group, unless overridden by a
203.B \-G
206.BI "\-G, \-\-setgid=" group
207Set gid to that of
208.I group
209(either a group name or integer gid) after initialization.
74eb47db 211.BI "\-k, \-\-priv\-keyring=" file
212Reads the private key from
213.I file
214rather than the default
215.BR keyring .
217.BI "\-K, \-\-pub\-keyring=" file
218Reads public keys from
219.I file
220rather than the default
221.BR .
222This can be the same as the private keyring, but that's not recommended.
224.BI "\-t, \-\-tag=" tag
225Uses the private key whose tag or type is
226.I tag
227rather than the default
228.BR tripe\-dh .
230.BI "\-a, \-\-admin\-socket=" socket
231Accept admin connections to a Unix-domain socket named
232.IR socket .
233The default socket, if this option isn't specified, is given by the
234environment variable
236if that's not set either, then a default default of
237.B "@socketdir@/tripesock"
238is used instead.
74eb47db 239.TP
240.BI "\-T, \-\-trace=" trace-opts
241Allows the enabling or disabling of various internal diagnostics. See
242below for the list of options.
d6623498 243.SS "Setting up a VPN with tripe"
245.B tripe
246server identifies peers by name. While it's
247.I possible
248for each host to maintain its own naming system for its peers, this is
249likely to lead to confusion, and it's more sensible to organize a naming
250system that works everywhere. How you manage this naming is up to you.
251The only restriction on the format of names is that they must be valid
252Catacomb key tags, since this is how
253.B tripe
254identifies which public key to use for a particular peer: they may not
255contain whitespace characters, or a colon
256.RB ` : '
257or dot
258.RB ` . ',
260Allocating IP addresses for VPNs can get quite complicated. I'll
261attempt to illustrate with a relatively simple example. Our objective
262will be to set up a virtual private network between two sites of
263.BR .
264The two sites are using distinct IP address ranges from the private
265address space described in RFC1918: site A is using addresses from
26610.0.1.0/24 and site B is using Each site has a gateway
267host set up with both an address on the site's private network, and an
268externally-routable address from the public IP address space. Site A's
269gateway machine,
270.BR alice ,
271has the addresses and; site B's gateway is
272.B bob
273and has addresses and
d6623498 274.hP 1.
276.B tripe
277on both of the gateway hosts. Create the directory
278.BR /var/lib/tripe .
279.hP 2.
281.BR alice ,
283.B /var/lib/tripe
284the current directory and generate a Diffie-Hellman group:
74eb47db 286.VS
287key add \-adh\-param \-LS \-b2048 \-B256 \e
288 \-eforever \-tparam tripe\-dh\-param
d6623498 290(See
291.BR key (1)
292from the Catacomb distribution for details about the
293.B key
294command.) Also generate a private key for
295.BR alice :
297key add \-adh \-pparam \-talice \e
298 \-e"now + 1 year" tripe\-dh
300Extract the group parameters and
301.BR alice 's
302public key to
303.I separate
304files, and put the public key in
305.BR :
74eb47db 306.VS
307key extract param param
37075862 308key extract \-f\-secret alice
d6623498 309key \ merge
74eb47db 310.VE
d6623498 311Send the files
312.B param
316.B bob
317in some secure way (e.g., in PGP-signed email, or by using SSH), so that
318you can be sure they've not been altered in transit.
320.hP 3.
322.B bob
323now, make
324.B /var/lib/tripe
325the current directory, and import the key material from
326.BR alice :
74eb47db 328.VS
329key merge param
d6623498 330key \ merge
74eb47db 331.VE
d6623498 332Generate a private key for
333.B bob
334and extract the public half, as before:
74eb47db 335.VS
d6623498 336key add \-adh \-pparam \-tbob \e
337 \-e"now + 1 year" tripe\-dh
383f2a0b 338key extract \-f\-secret bob
d6623498 339key \ merge
74eb47db 340.VE
d6623498 341and send
343back to
344.B alice
345using some secure method.
347.hP 4
349.BR alice ,
351.B bob 's
352key into the public keyring. Now, on each host, run
355key \ fingerprint
357and check that the hashes match. If the two sites have separate
358administrators, they should read the hashes to each other over the
359telephone (assuming that they can recognize each other's voices).
361.hP 5.
362Start the
363.B tripe
364servers up. Run
1f68dfc5 367tripectl \-slD \-S\-p22003
d6623498 368.VE
369on each of
370.B alice
372.BR bob .
1f68dfc5 374.RB ` \-p22003 '
375forces the server to use UDP port 22003: use some other number if 22003
376is inappropriate for your requirements. I chose it by taking the first
37716 bits of the RIPEMD160 hash of
378.RB ` TrIPE '.
d6623498 379.RE
380.hP 6.
381To get
382.B alice
383talking to
384.BR bob ,
385run this shell script (or one like it):
388#! /bin/sh
74eb47db 389
1f68dfc5 390tripectl add bob 22003
d6623498 391ifname=`tripectl ifname bob`
1f68dfc5 392ifconfig $ifname pointopoint
d6623498 393route add -net \e
394 netmask \e
1f68dfc5 395 gw
d6623498 396.VE
398.BR ifconfig (8)
400.BR route (8)
401to find out about your system's variants of these commands. The
402versions shown above assume a Linux system.
403Run a similar script on
404.BR bob ,
405to tell its
406.B tripe
407server to talk to
408.BR alice .
410.hP 7.
411Congratulations. The two servers will exchange keys and begin sending
412packets almost immediately. You've set up a virtual private network.
52c03a2a 413.SS "Using elliptic curve keys"
415.B tripe
416server can use elliptic curve Diffie-Hellman for key exchange, rather
417than traditional integer Diffie-Hellman. Given current public
418knowledge, elliptic curves can provide similar or better security to
419systems based on integer discrete log problems, faster, and with less
420transmitted data. It's a matter of controversy whether this will
421continue to be the case. The author uses elliptic curves.
423The server works out which it
424should be doing based on the key type, which is either
425.B tripe\-dh
426for standard Diffie-Hellman, or
427.B tripe\-ec
428for elliptic curves. To create elliptic curve keys, say something like
430key add \-aec\-param \-Cnist-p192 \-eforever \e
431 \-tparam tripe\-ec\-param
433to construct a parameters key, using your preferred elliptic curve in
435.B \-C
436option (see
437.BR key (1)
438for details); and create the private keys by
440key add \-aec \-pparam \-talice \e
441 \-e"now + 1 year" tripe\-ec
443Now start
444.B tripe
445with the
446.B \-ttripe\-ec
447option, and all should be well.
b5c45da1 448.SS "Using other symmetric algorithms"
449The default symmetric algorithms
450.B tripe
451uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
452(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
453mode, designed by Bellare, Canetti and Krawczyk). These can all be
454overridden by setting attributes on your private key, as follows.
456.B cipher
457Names the symmetric encryption scheme to use. The default is
458.BR blowfish\-cbc .
460.B hash
461Names the hash function to use. The default is
462.BR rmd160 .
464.B mac
465Names the message authentication code to use. The name of the MAC may
466be followed by a
467.RB ` / '
468and the desired tag length in bits. The default is
469.IB hash \-hmac
470at half the underlying hash function's output length.
472.B mgf
473A `mask-generation function', used in the key-exchange. The default is
474.IB hash \-mgf
475and there's no good reason to change it.
b9066fbb 476.SS "Using SLIP interfaces"
477Though not for the faint of heart, it is possible to get
478.B tripe
479to read and write network packets to a pair of file descriptors using
480SLIP encapsulation. No fancy header compression of any kind is
98fdb08d 481supported.
483Two usage modes are supported: a preallocation system, whereby SLIP
484interfaces are created and passed to the
485.B tripe
486server at startup; and a dynamic system, where the server runs a script
487to allocate a new SLIP interface when it needs one. It is possible to
488use a mixture of these two modes, starting
b9066fbb 489.B tripe
98fdb08d 490with a few preallocated interfaces and having it allocate more
491dynamically as it needs them.
493The behaviour of
494.BR tripe 's
495SLIP driver is controlled by the
1f68dfc5 497environment variable. The server will not create SLIP tunnels if this
498variable is not defined. The variable's value is a colon-delimited list
499of preallocated interfaces, followed optionally by the filename of a
500script to run to dynamically allocate more interfaces.
b9066fbb 501.PP
98fdb08d 502A static allocation entry has the form
b9066fbb 503.IR infd [ \c
504.BI , outfd \c
505.RB ] \c
506.BI = \c
98fdb08d 507.IR ifname ,
b9066fbb 508If the
509.I outfd
510is omitted, the same file descriptor is used for input and output.
98fdb08d 512The dynamic allocation script must be named by an absolute or relative
513pathname, beginning with
514.RB ` / '
516.RB ` . '.
517The server will pass the script an argument, which is the name of the
518peer for which the interface is being created. The script should
519allocate a new SLIP interface (presumably by creating a pty pair),
520configure it appropriately, and write the interface's name to its
521standard output, followed by a newline. It should then read and write
522SLIP packets on its stdin and stdout. The script's stdin will be closed
523when the interface is no longer needed, and the server will attempt to
524send it a
526signal (though this may fail if the script runs with higher privileges
527than the server).
b9066fbb 529The output file descriptor should not block unless it really needs to:
531.B tripe
1f68dfc5 532daemon assumes that it won't, and will get wedged waiting for it to
533accept output.
74eb47db 534.SS "About the name"
535The program's name is
536.BR tripe ,
537all in lower-case. The name of the protocol it uses is `TrIPE', with
538four capital letters and one lower-case. The name stands for `Trivial
539IP Encryption'.
540.SH "BUGS"
74eb47db 541The code hasn't been audited. It may contain security bugs. If you
542find one, please inform the author
543.IR immediately .
545.BR key (1),
546.BR tripectl (1),
547.BR tripe\-admin (5).
549.IR "The Trivial IP Encryption Protocol" ,
550.IR "The Wrestlers Protocol" .
d36eda2a 552Mark Wooding, <>