Commit | Line | Data |
---|---|---|
74eb47db | 1 | .\" -*-nroff-*- |
2 | .\". | |
fc916a09 MW |
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 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 27 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
28 | . |
29 | .\"-------------------------------------------------------------------------- | |
74eb47db | 30 | .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
31 | . |
32 | .\"-------------------------------------------------------------------------- | |
74eb47db | 33 | .SH "NAME" |
fc916a09 | 34 | . |
74eb47db | 35 | tripe \- a simple VPN daemon |
fc916a09 MW |
36 | . |
37 | .\"-------------------------------------------------------------------------- | |
74eb47db | 38 | .SH "SYNOPSIS" |
fc916a09 | 39 | . |
74eb47db | 40 | .B tripe |
46dde080 | 41 | .RB [ \-DF ] |
74eb47db | 42 | .RB [ \-d |
43 | .IR dir ] | |
d13e5724 | 44 | .RB [ \-b |
45 | .IR addr ] | |
33ced0d3 | 46 | .RB [ \-p |
47 | .IR port ] | |
42da2a58 | 48 | .RB [ \-n |
49 | .IR tunnel ] | |
d13e5724 | 50 | .br |
85b1ebd6 | 51 | \c |
33ced0d3 | 52 | .RB [ \-U |
53 | .IR user ] | |
54 | .RB [ \-G | |
55 | .IR group ] | |
d13e5724 | 56 | .RB [ \-a |
57 | .IR socket ] | |
a9279e37 MW |
58 | .RB [ \-m |
59 | .IR mode ] | |
d13e5724 | 60 | .RB [ \-T |
61 | .IR trace-opts ] | |
74eb47db | 62 | .br |
85b1ebd6 | 63 | \c |
74eb47db | 64 | .RB [ \-k |
65 | .IR priv-keyring ] | |
66 | .RB [ \-K | |
67 | .IR pub-keyring ] | |
68 | .RB [ \-t | |
69 | .IR key-tag ] | |
fc916a09 MW |
70 | . |
71 | .\"-------------------------------------------------------------------------- | |
74eb47db | 72 | .SH "DESCRIPTION" |
fc916a09 | 73 | . |
74eb47db | 74 | The |
75 | .B tripe | |
76 | program is a server which can provide strong IP-level encryption and | |
1a19f865 | 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. | |
74eb47db | 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: | |
1a19f865 | 107 | .hP 1. |
108 | It sets the directory named by the | |
109 | .B TRIPEDIR | |
110 | environment variable (or | |
f7b5d108 | 111 | .B "\*(/c" |
1a19f865 | 112 | if the variable is unset) as the current directory. |
113 | .hP 2. | |
74eb47db | 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)). | |
1a19f865 | 120 | .hP 3. |
74eb47db | 121 | It loads the private key with the tag or type name |
fc5f4823 MW |
122 | .B tripe |
123 | (or, failing that, | |
74eb47db | 124 | .B tripe\-dh |
fc5f4823 | 125 | for backwards compatibility reasons) from the Catacomb-format file |
74eb47db | 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.) | |
1a19f865 | 135 | .hP 4. |
74eb47db | 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 | |
33ced0d3 | 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. | |
74eb47db | 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 | |
42da2a58 | 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 | |
3cdc3f3a | 167 | start-up script, so that it can check that it will actually work. |
168 | .TP | |
74eb47db | 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 | |
46dde080 MW |
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 | |
74eb47db | 187 | .BI "\-d, \-\-directory=" dir |
188 | Makes | |
189 | .I dir | |
797cf76b MW |
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 | |
f7b5d108 | 194 | .B "\*(/c" |
797cf76b | 195 | is used. Give a current directory of |
74eb47db | 196 | .B . |
197 | if you don't want it to change directory at all. | |
198 | .TP | |
d13e5724 | 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 | |
74eb47db | 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 | |
42da2a58 | 211 | .BI "\-n, \-\-tunnel=" tunnel |
212 | Use the specified tunnel driver for new peers by default. | |
213 | .TP | |
33ced0d3 | 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 | |
aa2405e8 MW |
222 | option. The selected user (and group) will also be the owner of the |
223 | administration socket. | |
33ced0d3 | 224 | .TP |
225 | .BI "\-G, \-\-setgid=" group | |
226 | Set gid to that of | |
227 | .I group | |
228 | (either a group name or integer gid) after initialization. | |
229 | .TP | |
74eb47db | 230 | .BI "\-k, \-\-priv\-keyring=" file |
231 | Reads the private key from | |
232 | .I file | |
233 | rather than the default | |
234 | .BR keyring . | |
235 | .TP | |
236 | .BI "\-K, \-\-pub\-keyring=" file | |
237 | Reads public keys from | |
238 | .I file | |
239 | rather than the default | |
240 | .BR keyring.pub . | |
241 | This can be the same as the private keyring, but that's not recommended. | |
242 | .TP | |
243 | .BI "\-t, \-\-tag=" tag | |
244 | Uses the private key whose tag or type is | |
245 | .I tag | |
246 | rather than the default | |
fc5f4823 MW |
247 | .B tripe |
248 | or | |
74eb47db | 249 | .BR tripe\-dh . |
250 | .TP | |
251 | .BI "\-a, \-\-admin\-socket=" socket | |
252 | Accept admin connections to a Unix-domain socket named | |
797cf76b MW |
253 | .IR socket . |
254 | The default socket, if this option isn't specified, is given by the | |
255 | environment variable | |
256 | .BR TRIPESOCK ; | |
257 | if that's not set either, then a default default of | |
f7b5d108 | 258 | .B "\*(/s/tripesock" |
797cf76b | 259 | is used instead. |
74eb47db | 260 | .TP |
a9279e37 MW |
261 | .BI "\-m, \-\-admin\-perms=" mode |
262 | Permissions (as an octal number) to set on the administration socket. The | |
263 | default is 600, which allows only the socket owner. Setting 660 allows | |
264 | members of the | |
265 | .I group | |
266 | configured through the | |
267 | .B \-G | |
268 | option to connect to the socket, which may be useful. Allowing world access | |
269 | is a terrible idea. | |
270 | .TP | |
74eb47db | 271 | .BI "\-T, \-\-trace=" trace-opts |
272 | Allows the enabling or disabling of various internal diagnostics. See | |
273 | below for the list of options. | |
fc5f4823 | 274 | .SS "Key exchange group types" |
d6623498 | 275 | The |
276 | .B tripe | |
fc5f4823 MW |
277 | server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys |
278 | used for bulk data transfer. Currently | |
d6623498 | 279 | .B tripe |
fc5f4823 MW |
280 | can do Diffie\(en\&Hellman in two different kinds of cyclic groups: |
281 | .I "Schnorr groups" | |
282 | (denoted | |
283 | .BR dh ) | |
284 | and | |
285 | .I "elliptic curve groups" | |
286 | (denoted | |
287 | .BR ec ). | |
d6623498 | 288 | .PP |
fc5f4823 MW |
289 | A Schnorr group is a prime-order subgroup of the multiplicative group of |
290 | a finite field; this is the usual | |
291 | .I g\*(ssx\*(se | |
292 | mod | |
293 | .I p | |
294 | kind of Diffie\(en\&Hellman. An elliptic curve group is a prime-order | |
295 | subgroup of the abelian group of | |
296 | .BR K -rational | |
297 | points on an elliptic curve defined over a finite field | |
298 | .BR K . | |
299 | .PP | |
300 | Given current public knowledge, elliptic curves can provide similar or | |
301 | better security to systems based on integer discrete log problems, | |
302 | faster, and with less transmitted data. It's a matter of controversy | |
303 | whether this will continue to be the case. The author uses elliptic | |
304 | curves. | |
305 | .PP | |
306 | The server works out which it should be doing based on the key's | |
307 | .B kx-group | |
308 | attribute, which should be either | |
309 | .B dh | |
310 | or | |
311 | .BR ec . | |
312 | If this attribute isn't present, then the key's type is examined: if | |
313 | it's of the form | |
314 | .BR tripe\- group | |
315 | then the | |
316 | .I group | |
317 | is used. If no group is specified, | |
318 | .B dh | |
319 | is used as a fallback. | |
320 | .PP | |
321 | To create usual Schnorr-group keys, say something like | |
74eb47db | 322 | .VS |
fc5f4823 MW |
323 | key add \-adh-param \-LS \-b3072 \-B256 \e |
324 | \-eforever \-tparam tripe\-param kx-group=dh | |
74eb47db | 325 | .VE |
fc5f4823 | 326 | to construct a parameters key; and create the private keys by |
d6623498 | 327 | .VS |
328 | key add \-adh \-pparam \-talice \e | |
fc5f4823 | 329 | \-e"now + 1 year" tripe |
d6623498 | 330 | .VE |
fc5f4823 | 331 | To create elliptic curve keys, say something like |
d6623498 | 332 | .VS |
fc5f4823 MW |
333 | key add \-aec\-param \-Cnist-p256 \-eforever \e |
334 | \-tparam tripe\-param kx-group=ec | |
52c03a2a | 335 | .VE |
336 | to construct a parameters key, using your preferred elliptic curve in | |
337 | the | |
338 | .B \-C | |
339 | option (see | |
340 | .BR key (1) | |
341 | for details); and create the private keys by | |
342 | .VS | |
343 | key add \-aec \-pparam \-talice \e | |
fc5f4823 | 344 | \-e"now + 1 year" tripe |
52c03a2a | 345 | .VE |
fc5f4823 MW |
346 | Note that the |
347 | .BR tripe-keys (8) | |
348 | program provides a rather more convenient means for generating and | |
349 | managing keys for | |
350 | .BR tripe . | |
b5c45da1 | 351 | .SS "Using other symmetric algorithms" |
352 | The default symmetric algorithms | |
353 | .B tripe | |
354 | uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160 | |
355 | (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC | |
356 | mode, designed by Bellare, Canetti and Krawczyk). These can all be | |
357 | overridden by setting attributes on your private key, as follows. | |
358 | .TP | |
359 | .B cipher | |
360 | Names the symmetric encryption scheme to use. The default is | |
361 | .BR blowfish\-cbc . | |
362 | .TP | |
363 | .B hash | |
364 | Names the hash function to use. The default is | |
365 | .BR rmd160 . | |
366 | .TP | |
367 | .B mac | |
368 | Names the message authentication code to use. The name of the MAC may | |
369 | be followed by a | |
370 | .RB ` / ' | |
371 | and the desired tag length in bits. The default is | |
372 | .IB hash \-hmac | |
373 | at half the underlying hash function's output length. | |
374 | .TP | |
375 | .B mgf | |
376 | A `mask-generation function', used in the key-exchange. The default is | |
377 | .IB hash \-mgf | |
378 | and there's no good reason to change it. | |
b9066fbb | 379 | .SS "Using SLIP interfaces" |
380 | Though not for the faint of heart, it is possible to get | |
381 | .B tripe | |
382 | to read and write network packets to a pair of file descriptors using | |
383 | SLIP encapsulation. No fancy header compression of any kind is | |
98fdb08d | 384 | supported. |
385 | .PP | |
386 | Two usage modes are supported: a preallocation system, whereby SLIP | |
387 | interfaces are created and passed to the | |
388 | .B tripe | |
389 | server at startup; and a dynamic system, where the server runs a script | |
390 | to allocate a new SLIP interface when it needs one. It is possible to | |
391 | use a mixture of these two modes, starting | |
b9066fbb | 392 | .B tripe |
98fdb08d | 393 | with a few preallocated interfaces and having it allocate more |
394 | dynamically as it needs them. | |
395 | .PP | |
396 | The behaviour of | |
397 | .BR tripe 's | |
398 | SLIP driver is controlled by the | |
399 | .B TRIPE_SLIPIF | |
1f68dfc5 | 400 | environment variable. The server will not create SLIP tunnels if this |
401 | variable is not defined. The variable's value is a colon-delimited list | |
402 | of preallocated interfaces, followed optionally by the filename of a | |
403 | script to run to dynamically allocate more interfaces. | |
b9066fbb | 404 | .PP |
98fdb08d | 405 | A static allocation entry has the form |
b9066fbb | 406 | .IR infd [ \c |
407 | .BI , outfd \c | |
408 | .RB ] \c | |
409 | .BI = \c | |
98fdb08d | 410 | .IR ifname , |
b9066fbb | 411 | If the |
412 | .I outfd | |
413 | is omitted, the same file descriptor is used for input and output. | |
414 | .PP | |
98fdb08d | 415 | The dynamic allocation script must be named by an absolute or relative |
e04c2d50 | 416 | pathname, beginning with |
98fdb08d | 417 | .RB ` / ' |
418 | or | |
419 | .RB ` . '. | |
420 | The server will pass the script an argument, which is the name of the | |
421 | peer for which the interface is being created. The script should | |
422 | allocate a new SLIP interface (presumably by creating a pty pair), | |
423 | configure it appropriately, and write the interface's name to its | |
424 | standard output, followed by a newline. It should then read and write | |
425 | SLIP packets on its stdin and stdout. The script's stdin will be closed | |
426 | when the interface is no longer needed, and the server will attempt to | |
427 | send it a | |
428 | .B SIGTERM | |
429 | signal (though this may fail if the script runs with higher privileges | |
430 | than the server). | |
431 | .PP | |
b9066fbb | 432 | The output file descriptor should not block unless it really needs to: |
433 | the | |
434 | .B tripe | |
1f68dfc5 | 435 | daemon assumes that it won't, and will get wedged waiting for it to |
436 | accept output. | |
74eb47db | 437 | .SS "About the name" |
438 | The program's name is | |
439 | .BR tripe , | |
440 | all in lower-case. The name of the protocol it uses is `TrIPE', with | |
441 | four capital letters and one lower-case. The name stands for `Trivial | |
442 | IP Encryption'. | |
fc916a09 MW |
443 | . |
444 | .\"-------------------------------------------------------------------------- | |
74eb47db | 445 | .SH "BUGS" |
fc916a09 | 446 | . |
74eb47db | 447 | The code hasn't been audited. It may contain security bugs. If you |
448 | find one, please inform the author | |
449 | .IR immediately . | |
fc916a09 MW |
450 | . |
451 | .\"-------------------------------------------------------------------------- | |
74eb47db | 452 | .SH "SEE ALSO" |
fc916a09 | 453 | . |
74eb47db | 454 | .BR key (1), |
455 | .BR tripectl (1), | |
fc5f4823 MW |
456 | .BR tripe\-admin (5), |
457 | .BR tripe\-keys (8). | |
74eb47db | 458 | .PP |
459 | .IR "The Trivial IP Encryption Protocol" , | |
460 | .IR "The Wrestlers Protocol" . | |
fc916a09 MW |
461 | . |
462 | .\"-------------------------------------------------------------------------- | |
74eb47db | 463 | .SH "AUTHOR" |
fc916a09 | 464 | . |
d36eda2a | 465 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
466 | . |
467 | .\"----- That's all, folks -------------------------------------------------- |