chiark / gitweb /
New environment variable TRIPESOCK.
[tripe] / doc / tripe.8.in
CommitLineData
74eb47db 1.\" -*-nroff-*-
2.\".
3.de hP
4.IP
5\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
6..
7.de VS
8.sp 1
9.RS
10.nf
11.ft B
12..
13.de VE
14.ft R
15.fi
16.RE
17.sp 1
18..
19.ie t \{\
20. ds o \(bu
21. ds ss \s8\u
22. ds se \d\s0
23. if \n(.g \{\
24. fam P
25. \}
26.\}
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
35.SH "SYNOPSIS"
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 ]
d13e5724 46.br
47
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 ]
74eb47db 56.br
57
58.RB [ \-k
59.IR priv-keyring ]
60.RB [ \-K
61.IR pub-keyring ]
62.RB [ \-t
63.IR key-tag ]
64.SH "DESCRIPTION"
65The
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"
72The
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
80them.
81.PP
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
100.B TRIPEDIR
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
117.B keyring.pub
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 .
127.PP
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:
140.TP
141.B "\-h, \-\-help"
142Writes a brief description of the command-line options available to
143standard output and exits with status 0.
144.TP
145.B "\-v, \-\-version"
146Writes
147.BR tripe 's
148version number to standard output and exits with status 0.
149.TP
150.B "\-u, \-\-usage"
151Writes a brief usage summary to standard output and exits with status 0.
152.TP
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.
157.TP
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).
168.TP
169.BI "\-d, \-\-directory=" dir
170Makes
171.I dir
797cf76b
MW
172the current directory. The default directory to change to is given by
173the environment variable
174.BR TRIPEDIR ;
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.
180.TP
d13e5724 181.BI "\-b, \-\-bind-address="addr
182Bind the UDP socket to IP address
183.I addr
184rather than the default of
185.BR INADDR_ANY .
186This is useful if your main globally-routable IP address is one you want
187to tunnel through the VPN.
188.TP
74eb47db 189.BI "\-p, \-\-port=" port
190Use the specified UDP port for all communications with peers, rather
191than an arbitarary kernel-assigned port.
192.TP
42da2a58 193.BI "\-n, \-\-tunnel=" tunnel
194Use the specified tunnel driver for new peers by default.
195.TP
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
200to
201.IR user 's
202primary group, unless overridden by a
203.B \-G
204option.
205.TP
206.BI "\-G, \-\-setgid=" group
207Set gid to that of
208.I group
209(either a group name or integer gid) after initialization.
210.TP
74eb47db 211.BI "\-k, \-\-priv\-keyring=" file
212Reads the private key from
213.I file
214rather than the default
215.BR keyring .
216.TP
217.BI "\-K, \-\-pub\-keyring=" file
218Reads public keys from
219.I file
220rather than the default
221.BR keyring.pub .
222This can be the same as the private keyring, but that's not recommended.
223.TP
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 .
229.TP
230.BI "\-a, \-\-admin\-socket=" socket
231Accept admin connections to a Unix-domain socket named
797cf76b
MW
232.IR socket .
233The default socket, if this option isn't specified, is given by the
234environment variable
235.BR TRIPESOCK ;
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"
244The
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 ` . ',
259.PP
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 example.com .
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 10.0.2.0/24. 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 10.0.1.1 and 200.0.1.1; site B's gateway is
272.B bob
273and has addresses 10.0.2.1 and 200.0.2.1.
d6623498 274.hP 1.
275Install
276.B tripe
277on both of the gateway hosts. Create the directory
278.BR /var/lib/tripe .
279.hP 2.
280On
281.BR alice ,
282make
283.B /var/lib/tripe
284the current directory and generate a Diffie-Hellman group:
285.RS
74eb47db 286.VS
287key add \-adh\-param \-LS \-b2048 \-B256 \e
288 \-eforever \-tparam tripe\-dh\-param
289.VE
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 :
296.VS
297key add \-adh \-pparam \-talice \e
298 \-e"now + 1 year" tripe\-dh
299.VE
300Extract the group parameters and
301.BR alice 's
302public key to
303.I separate
304files, and put the public key in
305.BR keyring.pub :
74eb47db 306.VS
307key extract param param
37075862 308key extract \-f\-secret alice.pub alice
d6623498 309key \-kkeyring.pub merge alice.pub
74eb47db 310.VE
d6623498 311Send the files
312.B param
313and
314.B alice.pub
315to
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.
319.RE
320.hP 3.
321On
322.B bob
323now, make
324.B /var/lib/tripe
325the current directory, and import the key material from
326.BR alice :
327.RS
74eb47db 328.VS
329key merge param
d6623498 330key \-kkeyring.pub merge alice.pub
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.pub bob
d6623498 339key \-kkeyring.pub merge bob.pub
74eb47db 340.VE
d6623498 341and send
342.B bob.pub
343back to
344.B alice
345using some secure method.
346.RE
347.hP 4
348On
349.BR alice ,
350merge
351.B bob 's
352key into the public keyring. Now, on each host, run
353.RS
354.VS
355key \-kkeyring.pub fingerprint
356.VE
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).
360.RE
361.hP 5.
362Start the
363.B tripe
364servers up. Run
365.RS
366.VS
1f68dfc5 367tripectl \-slD \-S\-p22003
d6623498 368.VE
369on each of
370.B alice
371and
372.BR bob .
373(The
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):
386.RS
387.VS
388#! /bin/sh
74eb47db 389
1f68dfc5 390tripectl add bob 200.0.2.1 22003
d6623498 391ifname=`tripectl ifname bob`
1f68dfc5 392ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1
d6623498 393route add -net \e
394 10.0.2.0 netmask 255.255.255.0 \e
1f68dfc5 395 gw 10.0.2.1
d6623498 396.VE
397Read
398.BR ifconfig (8)
399and
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 .
409.RE
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"
414The
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.
422.PP
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
429.VS
430key add \-aec\-param \-Cnist-p192 \-eforever \e
431 \-tparam tripe\-ec\-param
432.VE
433to construct a parameters key, using your preferred elliptic curve in
434the
435.B \-C
436option (see
437.BR key (1)
438for details); and create the private keys by
439.VS
440key add \-aec \-pparam \-talice \e
441 \-e"now + 1 year" tripe\-ec
442.VE
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.
455.TP
456.B cipher
457Names the symmetric encryption scheme to use. The default is
458.BR blowfish\-cbc .
459.TP
460.B hash
461Names the hash function to use. The default is
462.BR rmd160 .
463.TP
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.
471.TP
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.
482.PP
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.
492.PP
493The behaviour of
494.BR tripe 's
495SLIP driver is controlled by the
496.B TRIPE_SLIPIF
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.
511.PP
98fdb08d 512The dynamic allocation script must be named by an absolute or relative
513pathname, beginning with
514.RB ` / '
515or
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
525.B SIGTERM
526signal (though this may fail if the script runs with higher privileges
527than the server).
528.PP
b9066fbb 529The output file descriptor should not block unless it really needs to:
530the
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 .
544.SH "SEE ALSO"
545.BR key (1),
546.BR tripectl (1),
547.BR tripe\-admin (5).
548.PP
549.IR "The Trivial IP Encryption Protocol" ,
550.IR "The Wrestlers Protocol" .
551.SH "AUTHOR"
d36eda2a 552Mark Wooding, <mdw@distorted.org.uk>