chiark / gitweb /
f5fe5bf6dc5f0e4ecd06294762898a670b25ce1b
[tripe] / doc / tripe.8
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 ^
30 .  ds se
31 .\}
32 .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
33 .SH "NAME"
34 tripe \- a simple VPN daemon
35 .SH "SYNOPSIS"
36 .B tripe
37 .RB [ \-D ]
38 .RB [ \-d
39 .IR dir ]
40 .RB [ \-b
41 .IR addr ]
42 .RB [ \-p
43 .IR port ]
44 .RB [ \-n
45 .IR tunnel ]
46 .br
47         
48 .RB [ \-U
49 .IR user ]
50 .RB [ \-G
51 .IR group ]
52 .RB [ \-a
53 .IR socket ]
54 .RB [ \-T
55 .IR trace-opts ]
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"
65 The
66 .B tripe
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.
71 .SS "Overview"
72 The
73 .B tripe
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
80 them.
81 .PP
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
87 .B tripe
88 server admin commands is described in
89 .BR tripe\-admin (5).
90 A client program
91 .BR tripectl (1)
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,
96 .B tripe
97 will initialize by following these steps:
98 .hP 1.
99 It sets the directory named by the
100 .B TRIPEDIR
101 environment variable (or
102 .B /var/lib/tripe
103 if the variable is unset) as the current directory.
104 .hP 2.
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
108 .B PORT
109 admin command (see
110 .BR tripe\-admin (5)).
111 .hP 3.
112 It loads the private key with the tag or type name
113 .B tripe\-dh
114 from the Catacomb-format file
115 .BR keyring ,
116 and loads the file
117 .B keyring.pub
118 ready for extracting the public keys of peers as they're introduced.
119 (The format of these files is described in
120 .BR keyring (5).
121 They are maintained using the program
122 .BR key (1)
123 provided with the Catacomb distribution.)
124 .hP 4.
125 It creates and listens to the Unix-domain socket
126 .BR tripesock .
127 .PP
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.
136 .PP
137 Much of this behaviour may be altered by giving
138 .B tripe
139 suitable command-line options:
140 .TP
141 .B "\-h, \-\-help"
142 Writes a brief description of the command-line options available to
143 standard output and exits with status 0.
144 .TP
145 .B "\-v, \-\-version"
146 Writes
147 .BR tripe 's
148 version number to standard output and exits with status 0.
149 .TP
150 .B "\-u, \-\-usage"
151 Writes a brief usage summary to standard output and exits with status 0.
152 .TP
153 .B "\-\-tunnels"
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.
157 .TP
158 .B "\-D, \-\-daemon"
159 Dissociates from its terminal and starts running in the background after
160 completing the initialization procedure described above.  If running as
161 a daemon,
162 .B tripe
163 will not read commands from standard input or write diagnostics to
164 standard output.  A better way to start
165 .B tripe
166 in the background is with
167 .BR tripectl (1).
168 .TP
169 .BI "\-d, \-\-directory=" dir
170 Makes
171 .I dir
172 the current directory, instead of
173 .BR /var/lib/tripe .
174 Give a current directory of
175 .B .
176 if you don't want it to change directory at all.
177 .TP
178 .BI "\-b, \-\-bind-address="addr
179 Bind the UDP socket to IP address
180 .I addr
181 rather than the default of
182 .BR INADDR_ANY .
183 This is useful if your main globally-routable IP address is one you want
184 to tunnel through the VPN.
185 .TP
186 .BI "\-p, \-\-port=" port
187 Use the specified UDP port for all communications with peers, rather
188 than an arbitarary kernel-assigned port.
189 .TP
190 .BI "\-n, \-\-tunnel=" tunnel
191 Use the specified tunnel driver for new peers by default.
192 .TP
193 .BI "\-U, \-\-setuid=" user
194 Set uid to that of
195 .I user
196 (either a user name or integer uid) after initialization.  Also set gid
197 to
198 .IR user 's
199 primary group, unless overridden by a
200 .B \-G
201 option.
202 .TP
203 .BI "\-G, \-\-setgid=" group
204 Set gid to that of
205 .I group
206 (either a group name or integer gid) after initialization.
207 .TP
208 .BI "\-k, \-\-priv\-keyring=" file
209 Reads the private key from
210 .I file
211 rather than the default
212 .BR keyring .
213 .TP
214 .BI "\-K, \-\-pub\-keyring=" file
215 Reads public keys from
216 .I file
217 rather than the default
218 .BR keyring.pub .
219 This can be the same as the private keyring, but that's not recommended.
220 .TP
221 .BI "\-t, \-\-tag=" tag
222 Uses the private key whose tag or type is
223 .I tag
224 rather than the default
225 .BR tripe\-dh .
226 .TP
227 .BI "\-a, \-\-admin\-socket=" socket
228 Accept admin connections to a Unix-domain socket named
229 .I socket
230 rather than the default
231 .BR tripesock .
232 .TP
233 .BI "\-T, \-\-trace=" trace-opts
234 Allows the enabling or disabling of various internal diagnostics.  See
235 below for the list of options.
236 .SS "Setting up a VPN with tripe"
237 The
238 .B tripe
239 server identifies peers by name.  While it's
240 .I possible
241 for each host to maintain its own naming system for its peers, this is
242 likely to lead to confusion, and it's more sensible to organize a naming
243 system that works everywhere.  How you manage this naming is up to you.
244 The only restriction on the format of names is that they must be valid
245 Catacomb key tags, since this is how
246 .B tripe
247 identifies which public key to use for a particular peer: they may not
248 contain whitespace characters, or a colon
249 .RB ` : '
250 or dot
251 .RB ` . ',
252 .PP
253 Allocating IP addresses for VPNs can get quite complicated.  I'll
254 attempt to illustrate with a relatively simple example.  Our objective
255 will be to set up a virtual private network between two sites of
256 .BR example.com .
257 The two sites are using distinct IP address ranges from the private
258 address space described in RFC1918: site A is using addresses from
259 10.0.1.0/24 and site B is using 10.0.2.0/24.  Each site has a gateway
260 host set up with both an address on the site's private network, and an
261 externally-routable address from the public IP address space.  Site A's
262 gateway machine,
263 .BR alice ,
264 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
265 .B bob
266 and has addresses 10.0.2.1 and 200.0.2.1.
267 .hP 1.
268 Install
269 .B tripe
270 on both of the gateway hosts.  Create the directory
271 .BR /var/lib/tripe .
272 .hP 2.
273 On
274 .BR alice ,
275 make
276 .B /var/lib/tripe
277 the current directory and generate a Diffie-Hellman group:
278 .RS
279 .VS
280 key add \-adh\-param \-LS \-b2048 \-B256 \e
281         \-eforever \-tparam tripe\-dh\-param
282 .VE
283 (See
284 .BR key (1)
285 from the Catacomb distribution for details about the
286 .B key
287 command.)  Also generate a private key for
288 .BR alice :
289 .VS
290 key add \-adh \-pparam \-talice \e
291         \-e"now + 1 year" tripe\-dh
292 .VE
293 Extract the group parameters and
294 .BR alice 's
295 public key to
296 .I separate
297 files, and put the public key in
298 .BR keyring.pub :
299 .VS
300 key extract param param
301 key extract \-f\-secret alice.pub alice
302 key \-kkeyring.pub merge alice.pub
303 .VE
304 Send the files
305 .B param
306 and
307 .B alice.pub
308 to
309 .B bob
310 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
311 you can be sure they've not been altered in transit.
312 .RE
313 .hP 3.
314 On
315 .B bob
316 now, make
317 .B /var/lib/tripe
318 the current directory, and import the key material from
319 .BR alice :
320 .RS
321 .VS
322 key merge param
323 key \-kkeyring.pub merge alice.pub
324 .VE
325 Generate a private key for
326 .B bob
327 and extract the public half, as before:
328 .VS
329 key add \-adh \-pparam \-tbob \e
330         \-e"now + 1 year" tripe\-dh
331 key extract \-f\-secret bob.pub bob
332 key \-kkeyring.pub merge bob.pub
333 .VE
334 and send
335 .B bob.pub
336 back to
337 .B alice
338 using some secure method.
339 .RE
340 .hP 4
341 On
342 .BR alice ,
343 merge
344 .B bob 's
345 key into the public keyring.  Now, on each host, run
346 .RS
347 .VS
348 key \-kkeyring.pub fingerprint
349 .VE
350 and check that the hashes match.  If the two sites have separate
351 administrators, they should read the hashes to each other over the
352 telephone (assuming that they can recognize each other's voices).
353 .RE
354 .hP 5.
355 Start the
356 .B tripe
357 servers up.  Run
358 .RS
359 .VS
360 tripectl \-slD \-S\-p22003
361 .VE
362 on each of
363 .B alice
364 and
365 .BR bob .
366 (The
367 .RB ` \-p22003 '
368 forces the server to use UDP port 22003: use some other number if 22003
369 is inappropriate for your requirements.  I chose it by taking the first
370 16 bits of the RIPEMD160 hash of
371 .RB ` TrIPE '.
372 .RE
373 .hP 6.
374 To get
375 .B alice
376 talking to
377 .BR bob ,
378 run this shell script (or one like it):
379 .RS
380 .VS
381 #! /bin/sh
382
383 tripectl add bob 200.0.2.1 22003
384 ifname=`tripectl ifname bob`
385 ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1
386 route add -net \e
387         10.0.2.0 netmask 255.255.255.0 \e
388         gw 10.0.2.1
389 .VE
390 Read
391 .BR ifconfig (8)
392 and
393 .BR route (8)
394 to find out about your system's variants of these commands.  The
395 versions shown above assume a Linux system.
396 Run a similar script on
397 .BR bob ,
398 to tell its
399 .B tripe
400 server to talk to
401 .BR alice .
402 .RE
403 .hP 7.
404 Congratulations.  The two servers will exchange keys and begin sending
405 packets almost immediately.  You've set up a virtual private network.
406 .SS "Using elliptic curve keys"
407 The
408 .B tripe
409 server can use elliptic curve Diffie-Hellman for key exchange, rather
410 than traditional integer Diffie-Hellman.  Given current public
411 knowledge, elliptic curves can provide similar or better security to
412 systems based on integer discrete log problems, faster, and with less
413 transmitted data.  It's a matter of controversy whether this will
414 continue to be the case.  The author uses elliptic curves.
415 .PP
416 The server works out which it
417 should be doing based on the key type, which is either
418 .B tripe\-dh
419 for standard Diffie-Hellman, or
420 .B tripe\-ec
421 for elliptic curves.  To create elliptic curve keys, say something like
422 .VS
423 key add \-aec\-param \-Cnist-p192 \-eforever \e
424         \-tparam tripe\-ec\-param
425 .VE
426 to construct a parameters key, using your preferred elliptic curve in
427 the
428 .B \-C
429 option (see
430 .BR key (1)
431 for details); and create the private keys by
432 .VS
433 key add \-aec \-pparam \-talice \e
434         \-e"now + 1 year" tripe\-ec
435 .VE
436 Now start
437 .B tripe
438 with the
439 .B \-ttripe\-ec
440 option, and all should be well.
441 .SS "Using other symmetric algorithms"
442 The default symmetric algorithms
443 .B tripe
444 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
445 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
446 mode, designed by Bellare, Canetti and Krawczyk).  These can all be
447 overridden by setting attributes on your private key, as follows.
448 .TP
449 .B cipher
450 Names the symmetric encryption scheme to use.  The default is
451 .BR blowfish\-cbc .
452 .TP
453 .B hash
454 Names the hash function to use.  The default is
455 .BR rmd160 .
456 .TP
457 .B mac
458 Names the message authentication code to use.  The name of the MAC may
459 be followed by a
460 .RB ` / '
461 and the desired tag length in bits.  The default is
462 .IB hash \-hmac
463 at half the underlying hash function's output length.
464 .TP
465 .B mgf
466 A `mask-generation function', used in the key-exchange.  The default is
467 .IB hash \-mgf
468 and there's no good reason to change it.
469 .SS "Using SLIP interfaces"
470 Though not for the faint of heart, it is possible to get
471 .B tripe
472 to read and write network packets to a pair of file descriptors using
473 SLIP encapsulation.  No fancy header compression of any kind is
474 supported.
475 .PP
476 Two usage modes are supported: a preallocation system, whereby SLIP
477 interfaces are created and passed to the
478 .B tripe
479 server at startup; and a dynamic system, where the server runs a script
480 to allocate a new SLIP interface when it needs one.  It is possible to
481 use a mixture of these two modes, starting
482 .B tripe
483 with a few preallocated interfaces and having it allocate more
484 dynamically as it needs them.
485 .PP
486 The behaviour of
487 .BR tripe 's
488 SLIP driver is controlled by the
489 .B TRIPE_SLIPIF
490 environment variable.  The server will not create SLIP tunnels if this
491 variable is not defined.  The variable's value is a colon-delimited list
492 of preallocated interfaces, followed optionally by the filename of a
493 script to run to dynamically allocate more interfaces.
494 .PP
495 A static allocation entry has the form
496 .IR infd [ \c
497 .BI , outfd \c
498 .RB ] \c
499 .BI = \c
500 .IR ifname ,
501 If the
502 .I outfd
503 is omitted, the same file descriptor is used for input and output.
504 .PP
505 The dynamic allocation script must be named by an absolute or relative
506 pathname, beginning with 
507 .RB ` / '
508 or
509 .RB ` . '.
510 The server will pass the script an argument, which is the name of the
511 peer for which the interface is being created.  The script should
512 allocate a new SLIP interface (presumably by creating a pty pair),
513 configure it appropriately, and write the interface's name to its
514 standard output, followed by a newline.  It should then read and write
515 SLIP packets on its stdin and stdout.  The script's stdin will be closed
516 when the interface is no longer needed, and the server will attempt to
517 send it a
518 .B SIGTERM
519 signal (though this may fail if the script runs with higher privileges
520 than the server).
521 .PP
522 The output file descriptor should not block unless it really needs to:
523 the
524 .B tripe
525 daemon assumes that it won't, and will get wedged waiting for it to
526 accept output.
527 .SS "About the name"
528 The program's name is
529 .BR tripe ,
530 all in lower-case.  The name of the protocol it uses is `TrIPE', with
531 four capital letters and one lower-case.  The name stands for `Trivial
532 IP Encryption'.
533 .SH "BUGS"
534 The code hasn't been audited.  It may contain security bugs.  If you
535 find one, please inform the author
536 .IR immediately .
537 .SH "SEE ALSO"
538 .BR key (1),
539 .BR tripectl (1),
540 .BR tripe\-admin (5).
541 .PP
542 .IR "The Trivial IP Encryption Protocol" ,
543 .IR "The Wrestlers Protocol" .
544 .SH "AUTHOR"
545 Mark Wooding, <mdw@distorted.org.uk>