chiark / gitweb /
server/tests.at (AWAIT_KXDONE): Ignore the correct server messages.
[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 8tripe "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 [ \-m
59 .IR mode ]
60 .RB [ \-T
61 .IR trace-opts ]
62 .br
63         \c
64 .RB [ \-k
65 .IR priv-keyring ]
66 .RB [ \-K
67 .IR pub-keyring ]
68 .RB [ \-t
69 .IR key-tag ]
70 .
71 .\"--------------------------------------------------------------------------
72 .SH "DESCRIPTION"
73 .
74 The
75 .B tripe
76 program is a server which can provide strong IP-level encryption and
77 authentication between co-operating hosts.  The program and its protocol
78 are deliberately very simple, to make analysing them easy and to help
79 build trust rapidly in the system.
80 .SS "Overview"
81 The
82 .B tripe
83 server manages a number of secure connections to other `peer' hosts.
84 Each daemon is given a private key of its own, and a file of public keys
85 for the peers with which it is meant to communicate.  It is responsible
86 for negotiating sets of symmetric keys with its peers, and for
87 encrypting, encapsulating and sending IP packets to its peers, and
88 decrypting, checking and de-encapsulating packets it receives from
89 them.
90 .PP
91 When the server starts, it creates a Unix-domain socket on which it
92 listens for administration commands.  It also logs warnings and
93 diagnostic information to the programs connected to its admin socket.
94 Clients connected to the socket can add new peers, and remove or find
95 out about existing peers.  The textual protocol used to give the
96 .B tripe
97 server admin commands is described in
98 .BR tripe\-admin (5).
99 A client program
100 .BR tripectl (1)
101 is provided to allow commands to be sent to the server either
102 interactively or by simple scripts.
103 .SS "Command-line arguments"
104 If not given any command-line arguments,
105 .B tripe
106 will initialize by following these steps:
107 .hP 1.
108 It sets the directory named by the
109 .B TRIPEDIR
110 environment variable (or
111 .B "\*(/c"
112 if the variable is unset) as the current directory.
113 .hP 2.
114 It acquires a UDP socket with an arbitrary kernel-selected port number.
115 It will use this socket to send and receive all communications with its
116 peer servers.  The port chosen may be discovered by means of the
117 .B PORT
118 admin command (see
119 .BR tripe\-admin (5)).
120 .hP 3.
121 It loads the private key with the tag or type name
122 .B tripe
123 (or, failing that,
124 .B tripe\-dh
125 for backwards compatibility reasons) from the Catacomb-format file
126 .BR keyring ,
127 and loads the file
128 .B keyring.pub
129 ready for extracting the public keys of peers as they're introduced.
130 (The format of these files is described in
131 .BR keyring (5).
132 They are maintained using the program
133 .BR key (1)
134 provided with the Catacomb distribution.)
135 .hP 4.
136 It creates and listens to the Unix-domain socket
137 .BR tripesock .
138 .PP
139 Following this, the server enters its main loop, accepting admin
140 connections and obeying any administrative commands, and communicating
141 with peers.  It also treats its standard input and standard output
142 streams as an admin connection, reading commands from standard input and
143 writing responses and diagnostics messages to standard output.  Finally,
144 it will reload keys from its keyring files if it notices that they've
145 changed (it checks inode number and modification time) \- there's no
146 need to send a signal.
147 .PP
148 Much of this behaviour may be altered by giving
149 .B tripe
150 suitable command-line options:
151 .TP
152 .B "\-h, \-\-help"
153 Writes a brief description of the command-line options available to
154 standard output and exits with status 0.
155 .TP
156 .B "\-v, \-\-version"
157 Writes
158 .BR tripe 's
159 version number to standard output and exits with status 0.
160 .TP
161 .B "\-u, \-\-usage"
162 Writes a brief usage summary to standard output and exits with status 0.
163 .TP
164 .B "\-\-tunnels"
165 Writes to standard output a list of the configured tunnel drivers, one
166 per line, and exits with status 0.  This is intended for the use of the
167 start-up script, so that it can check that it will actually work.
168 .TP
169 .B "\-D, \-\-daemon"
170 Dissociates from its terminal and starts running in the background after
171 completing the initialization procedure described above.  If running as
172 a daemon,
173 .B tripe
174 will not read commands from standard input or write diagnostics to
175 standard output.  A better way to start
176 .B tripe
177 in the background is with
178 .BR tripectl (1).
179 .TP
180 .B "\-F, \-\-foreground"
181 Runs the server in the `foreground'; i.e.,
182 .B tripe
183 will quit if it sees end-of-file on its standard input.  This is
184 incompatible with
185 .BR \-D .
186 .TP
187 .BI "\-d, \-\-directory=" dir
188 Makes
189 .I dir
190 the current directory.  The default directory to change to is given by
191 the environment variable
192 .BR TRIPEDIR ;
193 if that's not specified, a default default of
194 .B "\*(/c"
195 is used.  Give a current directory of
196 .B .
197 if you don't want it to change directory at all.
198 .TP
199 .BI "\-b, \-\-bind-address="addr
200 Bind the UDP socket to IP address
201 .I addr
202 rather than the default of
203 .BR INADDR_ANY .
204 This is useful if your main globally-routable IP address is one you want
205 to tunnel through the VPN.
206 .TP
207 .BI "\-p, \-\-port=" port
208 Use the specified UDP port for all communications with peers, rather
209 than an arbitarary kernel-assigned port.
210 .TP
211 .BI "\-n, \-\-tunnel=" tunnel
212 Use the specified tunnel driver for new peers by default.
213 .TP
214 .BI "\-U, \-\-setuid=" user
215 Set uid to that of
216 .I user
217 (either a user name or integer uid) after initialization.  Also set gid
218 to
219 .IR user 's
220 primary group, unless overridden by a
221 .B \-G
222 option.  The selected user (and group) will also be the owner of the
223 administration socket.
224 .TP
225 .BI "\-G, \-\-setgid=" group
226 If the current effective uid is zero (i.e., the daemon was invoked as
227 .BR root )
228 then set gid to that of
229 .I group
230 (either a group name or integer gid) after initialization.  In any
231 event, arrange hat the administration socket be owned by the given
232 .IR group .
233 .TP
234 .BI "\-k, \-\-priv\-keyring=" file
235 Reads the private key from
236 .I file
237 rather than the default
238 .BR keyring .
239 .TP
240 .BI "\-K, \-\-pub\-keyring=" file
241 Reads public keys from
242 .I file
243 rather than the default
244 .BR keyring.pub .
245 This can be the same as the private keyring, but that's not recommended.
246 .TP
247 .BI "\-t, \-\-tag=" tag
248 Uses the private key whose tag or type is
249 .I tag
250 rather than the default
251 .B tripe
252 or
253 .BR tripe\-dh .
254 .TP
255 .BI "\-a, \-\-admin\-socket=" socket
256 Accept admin connections to a Unix-domain socket named
257 .IR socket .
258 The default socket, if this option isn't specified, is given by the
259 environment variable
260 .BR TRIPESOCK ;
261 if that's not set either, then a default default of
262 .B "\*(/s/tripesock"
263 is used instead.
264 .TP
265 .BI "\-m, \-\-admin\-perms=" mode
266 Permissions (as an octal number) to set on the administration socket.  The
267 default is 600, which allows only the socket owner.  Setting 660 allows
268 members of the
269 .I group
270 configured through the
271 .B \-G
272 option to connect to the socket, which may be useful.  Allowing world access
273 is a terrible idea.
274 .TP
275 .BI "\-T, \-\-trace=" trace-opts
276 Allows the enabling or disabling of various internal diagnostics.  See
277 below for the list of options.
278 .SS "Key exchange group types"
279 The
280 .B tripe
281 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
282 used for bulk data transfer.  Currently
283 .B tripe
284 can do Diffie\(en\&Hellman in two different kinds of cyclic groups:
285 .I "Schnorr groups"
286 (denoted
287 .BR dh )
288 and
289 .I "elliptic curve groups"
290 (denoted
291 .BR ec ).
292 .PP
293 A Schnorr group is a prime-order subgroup of the multiplicative group of
294 a finite field; this is the usual
295 .I g\*(ssx\*(se
296 mod
297 .I p
298 kind of Diffie\(en\&Hellman.  An elliptic curve group is a prime-order
299 subgroup of the abelian group of
300 .BR K -rational
301 points on an elliptic curve defined over a finite field
302 .BR K .
303 .PP
304 Given current public knowledge, elliptic curves can provide similar or
305 better security to systems based on integer discrete log problems,
306 faster, and with less transmitted data.  It's a matter of controversy
307 whether this will continue to be the case.  The author uses elliptic
308 curves.
309 .PP
310 The server works out which it should be doing based on the key's
311 .B kx-group
312 attribute, which should be either
313 .B dh
314 or
315 .BR ec .
316 If this attribute isn't present, then the key's type is examined: if
317 it's of the form
318 .BR tripe\- group
319 then the
320 .I group
321 is used.  If no group is specified,
322 .B dh
323 is used as a fallback.
324 .PP
325 To create usual Schnorr-group keys, say something like
326 .VS
327 key add \-adh-param \-LS \-b3072 \-B256 \e
328         \-eforever \-tparam tripe\-param kx-group=dh
329 .VE
330 to construct a parameters key; and create the private keys by
331 .VS
332 key add \-adh \-pparam \-talice \e
333         \-e"now + 1 year" tripe
334 .VE
335 To create elliptic curve keys, say something like
336 .VS
337 key add \-aec\-param \-Cnist-p256 \-eforever \e
338         \-tparam tripe\-param kx-group=ec
339 .VE
340 to construct a parameters key, using your preferred elliptic curve in
341 the
342 .B \-C
343 option (see
344 .BR key (1)
345 for details); and create the private keys by
346 .VS
347 key add \-aec \-pparam \-talice \e
348         \-e"now + 1 year" tripe
349 .VE
350 Note that the
351 .BR tripe-keys (8)
352 program provides a rather more convenient means for generating and
353 managing keys for
354 .BR tripe .
355 .SS "Using other symmetric algorithms"
356 The default symmetric algorithms
357 .B tripe
358 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
359 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
360 mode, designed by Bellare, Canetti and Krawczyk).  These can all be
361 overridden by setting attributes on your private key, as follows.
362 .TP
363 .B bulk
364 Names the bulk-crypto transform to use.  See below.
365 .TP
366 .B blkc
367 Names a block cipher, used by some bulk-crypto transforms (e.g.,
368 .BR iiv ).  The default is to use the block cipher underlying the chosen
369 .BR cipher ,
370 if any.
371 .TP
372 .B cipher
373 Names the symmetric encryption scheme to use.  The default is
374 .BR blowfish\-cbc .
375 .TP
376 .B hash
377 Names the hash function to use.  The default is
378 .BR rmd160 .
379 .TP
380 .B mac
381 Names the message authentication code to use.  The name of the MAC may
382 be followed by a
383 .RB ` / '
384 and the desired tag length in bits.  The default is
385 .IB hash \-hmac
386 at half the underlying hash function's output length.
387 .TP
388 .B mgf
389 A `mask-generation function', used in the key-exchange.  The default is
390 .IB hash \-mgf
391 and there's no good reason to change it.
392 .PP
393 The available bulk-crypto transforms are as follows.
394 .TP
395 .B v0
396 Originally this was the only transform available.  It's a standard
397 generic composition of a CPA-secure symmetric encryption scheme with a
398 MAC; initialization vectors for symmetric encryption are chosen at
399 random and included explicitly in the cryptogram.
400 .TP
401 .B iiv
402 A newer `implicit-IV' transform.  Rather than having an explicit random
403 IV, the IV is computed from the sequence number using a block cipher.
404 This has two advantages over the
405 .B v0
406 transform.  Firstly, it adds less overhead to encrypted messages
407 (because the IV no longer needs to be sent explicitly).  Secondly, and
408 more significantly, the transform is entirely deterministic, so (a) it
409 doesn't need the (possibly slow) random number generator, and (b) it
410 closes a kleptographic channel, over which a compromised implementation
411 could leak secret information to a third party.
412 .SS "Using SLIP interfaces"
413 Though not for the faint of heart, it is possible to get
414 .B tripe
415 to read and write network packets to a pair of file descriptors using
416 SLIP encapsulation.  No fancy header compression of any kind is
417 supported.
418 .PP
419 Two usage modes are supported: a preallocation system, whereby SLIP
420 interfaces are created and passed to the
421 .B tripe
422 server at startup; and a dynamic system, where the server runs a script
423 to allocate a new SLIP interface when it needs one.  It is possible to
424 use a mixture of these two modes, starting
425 .B tripe
426 with a few preallocated interfaces and having it allocate more
427 dynamically as it needs them.
428 .PP
429 The behaviour of
430 .BR tripe 's
431 SLIP driver is controlled by the
432 .B TRIPE_SLIPIF
433 environment variable.  The server will not create SLIP tunnels if this
434 variable is not defined.  The variable's value is a colon-delimited list
435 of preallocated interfaces, followed optionally by the filename of a
436 script to run to dynamically allocate more interfaces.
437 .PP
438 A static allocation entry has the form
439 .IR infd [ \c
440 .BI , outfd \c
441 .RB ] \c
442 .BI = \c
443 .IR ifname ,
444 If the
445 .I outfd
446 is omitted, the same file descriptor is used for input and output.
447 .PP
448 The dynamic allocation script must be named by an absolute or relative
449 pathname, beginning with
450 .RB ` / '
451 or
452 .RB ` . '.
453 The server will pass the script an argument, which is the name of the
454 peer for which the interface is being created.  The script should
455 allocate a new SLIP interface (presumably by creating a pty pair),
456 configure it appropriately, and write the interface's name to its
457 standard output, followed by a newline.  It should then read and write
458 SLIP packets on its stdin and stdout.  The script's stdin will be closed
459 when the interface is no longer needed, and the server will attempt to
460 send it a
461 .B SIGTERM
462 signal (though this may fail if the script runs with higher privileges
463 than the server).
464 .PP
465 The output file descriptor should not block unless it really needs to:
466 the
467 .B tripe
468 daemon assumes that it won't, and will get wedged waiting for it to
469 accept output.
470 .SS "About the name"
471 The program's name is
472 .BR tripe ,
473 all in lower-case.  The name of the protocol it uses is `TrIPE', with
474 four capital letters and one lower-case.  The name stands for `Trivial
475 IP Encryption'.
476 .
477 .\"--------------------------------------------------------------------------
478 .SH "BUGS"
479 .
480 The code hasn't been audited.  It may contain security bugs.  If you
481 find one, please inform the author
482 .IR immediately .
483 .
484 .\"--------------------------------------------------------------------------
485 .SH "SEE ALSO"
486 .
487 .BR key (1),
488 .BR tripectl (1),
489 .BR tripe\-admin (5),
490 .BR tripe\-keys (8).
491 .PP
492 .IR "The Trivial IP Encryption Protocol" ,
493 .IR "The Wrestlers Protocol" .
494 .
495 .\"--------------------------------------------------------------------------
496 .SH "AUTHOR"
497 .
498 Mark Wooding, <mdw@distorted.org.uk>
499 .
500 .\"----- That's all, folks --------------------------------------------------