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