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