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 | .\" | |
11ad66c2 MW |
12 | .\" TrIPE is free software: you can redistribute it and/or modify it under |
13 | .\" the terms of the GNU General Public License as published by the Free | |
14 | .\" Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
fc916a09 | 16 | .\" |
11ad66c2 MW |
17 | .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
fc916a09 MW |
21 | .\" |
22 | .\" You should have received a copy of the GNU General Public License | |
11ad66c2 | 23 | .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>. |
fc916a09 MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 26 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
0647ba7c | 29 | .TH tripe 8tripe "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
30 | . |
31 | .\"-------------------------------------------------------------------------- | |
74eb47db | 32 | .SH "NAME" |
fc916a09 | 33 | . |
74eb47db | 34 | tripe \- a simple VPN daemon |
fc916a09 MW |
35 | . |
36 | .\"-------------------------------------------------------------------------- | |
74eb47db | 37 | .SH "SYNOPSIS" |
fc916a09 | 38 | . |
74eb47db | 39 | .B tripe |
47828bd9 | 40 | .RB [ \-46DF ] |
74eb47db | 41 | .RB [ \-d |
42 | .IR dir ] | |
d13e5724 | 43 | .RB [ \-b |
44 | .IR addr ] | |
33ced0d3 | 45 | .RB [ \-p |
46 | .IR port ] | |
42da2a58 | 47 | .RB [ \-n |
48 | .IR tunnel ] | |
d13e5724 | 49 | .br |
85b1ebd6 | 50 | \c |
33ced0d3 | 51 | .RB [ \-U |
52 | .IR user ] | |
53 | .RB [ \-G | |
54 | .IR group ] | |
d13e5724 | 55 | .RB [ \-a |
56 | .IR socket ] | |
a9279e37 MW |
57 | .RB [ \-m |
58 | .IR mode ] | |
d13e5724 | 59 | .RB [ \-T |
60 | .IR trace-opts ] | |
74eb47db | 61 | .br |
85b1ebd6 | 62 | \c |
74eb47db | 63 | .RB [ \-k |
64 | .IR priv-keyring ] | |
65 | .RB [ \-K | |
66 | .IR pub-keyring ] | |
67 | .RB [ \-t | |
68 | .IR key-tag ] | |
fc916a09 MW |
69 | . |
70 | .\"-------------------------------------------------------------------------- | |
74eb47db | 71 | .SH "DESCRIPTION" |
fc916a09 | 72 | . |
74eb47db | 73 | The |
74 | .B tripe | |
75 | program is a server which can provide strong IP-level encryption and | |
1a19f865 | 76 | authentication between co-operating hosts. The program and its protocol |
77 | are deliberately very simple, to make analysing them easy and to help | |
78 | build trust rapidly in the system. | |
74eb47db | 79 | .SS "Overview" |
80 | The | |
81 | .B tripe | |
82 | server manages a number of secure connections to other `peer' hosts. | |
83 | Each daemon is given a private key of its own, and a file of public keys | |
84 | for the peers with which it is meant to communicate. It is responsible | |
85 | for negotiating sets of symmetric keys with its peers, and for | |
86 | encrypting, encapsulating and sending IP packets to its peers, and | |
87 | decrypting, checking and de-encapsulating packets it receives from | |
88 | them. | |
89 | .PP | |
90 | When the server starts, it creates a Unix-domain socket on which it | |
91 | listens for administration commands. It also logs warnings and | |
92 | diagnostic information to the programs connected to its admin socket. | |
93 | Clients connected to the socket can add new peers, and remove or find | |
94 | out about existing peers. The textual protocol used to give the | |
95 | .B tripe | |
96 | server admin commands is described in | |
97 | .BR tripe\-admin (5). | |
98 | A client program | |
99 | .BR tripectl (1) | |
100 | is provided to allow commands to be sent to the server either | |
101 | interactively or by simple scripts. | |
102 | .SS "Command-line arguments" | |
103 | If not given any command-line arguments, | |
104 | .B tripe | |
105 | will initialize by following these steps: | |
1a19f865 | 106 | .hP 1. |
107 | It sets the directory named by the | |
108 | .B TRIPEDIR | |
109 | environment variable (or | |
f7b5d108 | 110 | .B "\*(/c" |
1a19f865 | 111 | if the variable is unset) as the current directory. |
112 | .hP 2. | |
f492fa0b | 113 | It acquires a UDP socket. The default port is 4070 |
74eb47db | 114 | It will use this socket to send and receive all communications with its |
115 | peer servers. The port chosen may be discovered by means of the | |
116 | .B PORT | |
117 | admin command (see | |
118 | .BR tripe\-admin (5)). | |
1a19f865 | 119 | .hP 3. |
74eb47db | 120 | It loads the private key with the tag or type name |
fc5f4823 MW |
121 | .B tripe |
122 | (or, failing that, | |
74eb47db | 123 | .B tripe\-dh |
fc5f4823 | 124 | for backwards compatibility reasons) from the Catacomb-format file |
74eb47db | 125 | .BR keyring , |
126 | and loads the file | |
127 | .B keyring.pub | |
128 | ready for extracting the public keys of peers as they're introduced. | |
129 | (The format of these files is described in | |
130 | .BR keyring (5). | |
131 | They are maintained using the program | |
132 | .BR key (1) | |
133 | provided with the Catacomb distribution.) | |
1a19f865 | 134 | .hP 4. |
74eb47db | 135 | It creates and listens to the Unix-domain socket |
136 | .BR tripesock . | |
137 | .PP | |
138 | Following this, the server enters its main loop, accepting admin | |
139 | connections and obeying any administrative commands, and communicating | |
140 | with peers. It also treats its standard input and standard output | |
141 | streams as an admin connection, reading commands from standard input and | |
33ced0d3 | 142 | writing responses and diagnostics messages to standard output. Finally, |
143 | it will reload keys from its keyring files if it notices that they've | |
144 | changed (it checks inode number and modification time) \- there's no | |
145 | need to send a signal. | |
74eb47db | 146 | .PP |
147 | Much of this behaviour may be altered by giving | |
148 | .B tripe | |
149 | suitable command-line options: | |
150 | .TP | |
151 | .B "\-h, \-\-help" | |
152 | Writes a brief description of the command-line options available to | |
153 | standard output and exits with status 0. | |
154 | .TP | |
155 | .B "\-v, \-\-version" | |
156 | Writes | |
157 | .BR tripe 's | |
158 | version number to standard output and exits with status 0. | |
159 | .TP | |
160 | .B "\-u, \-\-usage" | |
161 | Writes a brief usage summary to standard output and exits with status 0. | |
162 | .TP | |
42da2a58 | 163 | .B "\-\-tunnels" |
164 | Writes to standard output a list of the configured tunnel drivers, one | |
165 | per line, and exits with status 0. This is intended for the use of the | |
3cdc3f3a | 166 | start-up script, so that it can check that it will actually work. |
167 | .TP | |
47828bd9 MW |
168 | .B "\-4, \-\-ipv4" |
169 | Use only IPv4 addresses. The server will resolve names only to IPv4 | |
170 | addresses, and not attempt to create IPv6 sockets. | |
171 | .TP | |
172 | .B "\-6, \-\-ipv6" | |
173 | Use only IPv6 addresses. The server will resolve names only to IPv6 | |
174 | addresses, and not attempt to create IPv4 sockets. Note that v6-mapped | |
175 | IPv4 addresses won't work either. | |
176 | .TP | |
74eb47db | 177 | .B "\-D, \-\-daemon" |
178 | Dissociates from its terminal and starts running in the background after | |
179 | completing the initialization procedure described above. If running as | |
180 | a daemon, | |
181 | .B tripe | |
182 | will not read commands from standard input or write diagnostics to | |
183 | standard output. A better way to start | |
184 | .B tripe | |
185 | in the background is with | |
186 | .BR tripectl (1). | |
187 | .TP | |
46dde080 MW |
188 | .B "\-F, \-\-foreground" |
189 | Runs the server in the `foreground'; i.e., | |
190 | .B tripe | |
191 | will quit if it sees end-of-file on its standard input. This is | |
192 | incompatible with | |
193 | .BR \-D . | |
194 | .TP | |
74eb47db | 195 | .BI "\-d, \-\-directory=" dir |
196 | Makes | |
197 | .I dir | |
797cf76b MW |
198 | the current directory. The default directory to change to is given by |
199 | the environment variable | |
200 | .BR TRIPEDIR ; | |
201 | if that's not specified, a default default of | |
f7b5d108 | 202 | .B "\*(/c" |
797cf76b | 203 | is used. Give a current directory of |
74eb47db | 204 | .B . |
205 | if you don't want it to change directory at all. | |
206 | .TP | |
d13e5724 | 207 | .BI "\-b, \-\-bind-address="addr |
208 | Bind the UDP socket to IP address | |
209 | .I addr | |
210 | rather than the default of | |
211 | .BR INADDR_ANY . | |
212 | This is useful if your main globally-routable IP address is one you want | |
213 | to tunnel through the VPN. | |
214 | .TP | |
74eb47db | 215 | .BI "\-p, \-\-port=" port |
216 | Use the specified UDP port for all communications with peers, rather | |
f492fa0b MW |
217 | than the default port 4070. If this is zero, the kernel will assign a |
218 | free port, which can be determined using the | |
219 | .B PORT | |
220 | administration command (see | |
221 | .BR tripe-admin (5)). | |
74eb47db | 222 | .TP |
42da2a58 | 223 | .BI "\-n, \-\-tunnel=" tunnel |
224 | Use the specified tunnel driver for new peers by default. | |
225 | .TP | |
33ced0d3 | 226 | .BI "\-U, \-\-setuid=" user |
227 | Set uid to that of | |
228 | .I user | |
229 | (either a user name or integer uid) after initialization. Also set gid | |
230 | to | |
231 | .IR user 's | |
232 | primary group, unless overridden by a | |
233 | .B \-G | |
aa2405e8 MW |
234 | option. The selected user (and group) will also be the owner of the |
235 | administration socket. | |
33ced0d3 | 236 | .TP |
237 | .BI "\-G, \-\-setgid=" group | |
ec9b8aed MW |
238 | If the current effective uid is zero (i.e., the daemon was invoked as |
239 | .BR root ) | |
240 | then set gid to that of | |
33ced0d3 | 241 | .I group |
ec9b8aed MW |
242 | (either a group name or integer gid) after initialization. In any |
243 | event, arrange hat the administration socket be owned by the given | |
244 | .IR group . | |
33ced0d3 | 245 | .TP |
74eb47db | 246 | .BI "\-k, \-\-priv\-keyring=" file |
247 | Reads the private key from | |
248 | .I file | |
249 | rather than the default | |
250 | .BR keyring . | |
251 | .TP | |
252 | .BI "\-K, \-\-pub\-keyring=" file | |
253 | Reads public keys from | |
254 | .I file | |
255 | rather than the default | |
256 | .BR keyring.pub . | |
257 | This can be the same as the private keyring, but that's not recommended. | |
258 | .TP | |
259 | .BI "\-t, \-\-tag=" tag | |
260 | Uses the private key whose tag or type is | |
261 | .I tag | |
262 | rather than the default | |
fc5f4823 MW |
263 | .B tripe |
264 | or | |
74eb47db | 265 | .BR tripe\-dh . |
266 | .TP | |
267 | .BI "\-a, \-\-admin\-socket=" socket | |
268 | Accept admin connections to a Unix-domain socket named | |
797cf76b MW |
269 | .IR socket . |
270 | The default socket, if this option isn't specified, is given by the | |
271 | environment variable | |
272 | .BR TRIPESOCK ; | |
273 | if that's not set either, then a default default of | |
f7b5d108 | 274 | .B "\*(/s/tripesock" |
797cf76b | 275 | is used instead. |
74eb47db | 276 | .TP |
a9279e37 MW |
277 | .BI "\-m, \-\-admin\-perms=" mode |
278 | Permissions (as an octal number) to set on the administration socket. The | |
279 | default is 600, which allows only the socket owner. Setting 660 allows | |
280 | members of the | |
281 | .I group | |
282 | configured through the | |
283 | .B \-G | |
284 | option to connect to the socket, which may be useful. Allowing world access | |
285 | is a terrible idea. | |
286 | .TP | |
74eb47db | 287 | .BI "\-T, \-\-trace=" trace-opts |
288 | Allows the enabling or disabling of various internal diagnostics. See | |
97e1aa23 MW |
289 | the |
290 | .B TRACE | |
291 | command in | |
292 | .BR trace-admin (5) | |
293 | for the list of options. | |
fc5f4823 | 294 | .SS "Key exchange group types" |
d6623498 | 295 | The |
296 | .B tripe | |
fc5f4823 | 297 | server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys |
b86e6f3f | 298 | used for bulk data transfer. |
fc5f4823 MW |
299 | .PP |
300 | The server works out which it should be doing based on the key's | |
301 | .B kx-group | |
b86e6f3f | 302 | attribute. |
fc5f4823 MW |
303 | If this attribute isn't present, then the key's type is examined: if |
304 | it's of the form | |
1a0b1e9f | 305 | .BI tripe\- group |
fc5f4823 MW |
306 | then the |
307 | .I group | |
308 | is used. If no group is specified, | |
309 | .B dh | |
310 | is used as a fallback. | |
b86e6f3f MW |
311 | The following groups are defined. |
312 | .TP | |
313 | .B dh | |
314 | .RS | |
315 | Use traditional Diffie\(enHellman in a | |
316 | .IR "Schnorr group" : | |
317 | a prime-order subgroup of the multiplicative group of | |
318 | a finite field; this is the usual | |
319 | .I g\*(ssx\*(se | |
320 | mod | |
321 | .I p | |
322 | kind of Diffie\(en\&Hellman. | |
fc5f4823 MW |
323 | .PP |
324 | To create usual Schnorr-group keys, say something like | |
74eb47db | 325 | .VS |
fc5f4823 MW |
326 | key add \-adh-param \-LS \-b3072 \-B256 \e |
327 | \-eforever \-tparam tripe\-param kx-group=dh | |
74eb47db | 328 | .VE |
fc5f4823 | 329 | to construct a parameters key; and create the private keys by |
d6623498 | 330 | .VS |
331 | key add \-adh \-pparam \-talice \e | |
fc5f4823 | 332 | \-e"now + 1 year" tripe |
d6623498 | 333 | .VE |
b86e6f3f MW |
334 | .RE |
335 | .sv -1 | |
336 | .TP | |
337 | .B ec | |
338 | .RS | |
339 | Use elliptic curve Diffie\(enHellman. | |
340 | An elliptic curve group is a prime-order | |
341 | subgroup of the abelian group of | |
342 | .BR K -rational | |
343 | points on an elliptic curve defined over a finite field | |
344 | .BR K . | |
345 | .PP | |
346 | Given current public knowledge, elliptic curves can provide similar or | |
347 | better security to systems based on integer discrete log problems, | |
348 | faster, and with less transmitted data. It's a matter of controversy | |
349 | whether this will continue to be the case. The author uses elliptic | |
350 | curves. | |
351 | .PP | |
fc5f4823 | 352 | To create elliptic curve keys, say something like |
d6623498 | 353 | .VS |
fc5f4823 MW |
354 | key add \-aec\-param \-Cnist-p256 \-eforever \e |
355 | \-tparam tripe\-param kx-group=ec | |
52c03a2a | 356 | .VE |
357 | to construct a parameters key, using your preferred elliptic curve in | |
358 | the | |
359 | .B \-C | |
360 | option (see | |
361 | .BR key (1) | |
362 | for details); and create the private keys by | |
363 | .VS | |
364 | key add \-aec \-pparam \-talice \e | |
fc5f4823 | 365 | \-e"now + 1 year" tripe |
52c03a2a | 366 | .VE |
b86e6f3f | 367 | .RE |
26936c83 MW |
368 | .sv -1 |
369 | .TP | |
370 | .B x25519 | |
371 | .RS | |
372 | Use Bernstein's X25519 Diffie\(enHellman function. | |
373 | This is technically a variant on | |
374 | the general elliptic curve Diffie\(enHellman | |
375 | available through the | |
376 | .B ec | |
377 | setting, | |
378 | but carefully designed and heavily optimized. | |
379 | .PP | |
380 | To create | |
381 | .B x25519 | |
382 | keys, | |
383 | say something like | |
384 | .VS | |
385 | key add \-aempty \-eforever \e | |
386 | \-tparam tripe\-param kx-group=x25519 | |
387 | .VE | |
388 | to construct a parameters key | |
389 | (see | |
390 | .BR key (1) | |
391 | for details); | |
392 | and create the private keys by | |
393 | .VS | |
394 | key add \-ax25519 \-pparam \-talice \e | |
395 | \-e"now + 1 year" tripe | |
396 | .VE | |
397 | .RE | |
398 | .sv -1 | |
399 | .TP | |
400 | .B x448 | |
401 | .RS | |
402 | Use Hamburg's X448 Diffie\(enHellman function. | |
403 | Like | |
404 | .B x25519 | |
405 | above, | |
406 | this is technically a variant on | |
407 | the general elliptic curve Diffie\(enHellman | |
408 | available through the | |
409 | .B ec | |
410 | setting, | |
411 | but carefully designed and heavily optimized. | |
412 | .PP | |
413 | To create | |
414 | .B x448 | |
415 | keys, | |
416 | say something like | |
417 | .VS | |
418 | key add \-aempty \-eforever \e | |
419 | \-tparam tripe\-param kx-group=x448 | |
420 | .VE | |
421 | to construct a parameters key | |
422 | (see | |
423 | .BR key (1) | |
424 | for details); | |
425 | and create the private keys by | |
426 | .VS | |
427 | key add \-ax448 \-pparam \-talice \e | |
428 | \-e"now + 1 year" tripe | |
429 | .VE | |
430 | .RE | |
fc5f4823 MW |
431 | Note that the |
432 | .BR tripe-keys (8) | |
433 | program provides a rather more convenient means for generating and | |
434 | managing keys for | |
435 | .BR tripe . | |
b5c45da1 | 436 | .SS "Using other symmetric algorithms" |
437 | The default symmetric algorithms | |
438 | .B tripe | |
439 | uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160 | |
440 | (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC | |
441 | mode, designed by Bellare, Canetti and Krawczyk). These can all be | |
442 | overridden by setting attributes on your private key, as follows. | |
443 | .TP | |
a93aacce | 444 | .B bulk |
b87bffcb MW |
445 | Names the bulk-crypto transform to use. See below. |
446 | .TP | |
447 | .B blkc | |
b2177d04 | 448 | Names a blockcipher, used by some bulk-crypto transforms (e.g., |
a305982d | 449 | .BR iiv ). |
b2177d04 | 450 | The default is to use the blockcipher underlying the chosen |
b87bffcb MW |
451 | .BR cipher , |
452 | if any. | |
a93aacce | 453 | .TP |
b5c45da1 | 454 | .B cipher |
455 | Names the symmetric encryption scheme to use. The default is | |
456 | .BR blowfish\-cbc . | |
457 | .TP | |
458 | .B hash | |
459 | Names the hash function to use. The default is | |
460 | .BR rmd160 . | |
461 | .TP | |
462 | .B mac | |
463 | Names the message authentication code to use. The name of the MAC may | |
464 | be followed by a | |
465 | .RB ` / ' | |
466 | and the desired tag length in bits. The default is | |
467 | .IB hash \-hmac | |
468 | at half the underlying hash function's output length. | |
73d383c0 MW |
469 | If the MAC's name contains a |
470 | .RB ` / ' | |
471 | character, | |
472 | e.g., | |
473 | .RB ` sha512/256 ', | |
474 | then an | |
475 | .I additional | |
476 | .RB ` / ' | |
477 | and the tag size is required to disambiguate, | |
478 | so, e.g., | |
479 | one might write | |
480 | .RB ` sha512/256/256 '. | |
b5c45da1 | 481 | .TP |
482 | .B mgf | |
483 | A `mask-generation function', used in the key-exchange. The default is | |
484 | .IB hash \-mgf | |
485 | and there's no good reason to change it. | |
b87bffcb MW |
486 | .PP |
487 | The available bulk-crypto transforms are as follows. | |
488 | .TP | |
489 | .B v0 | |
490 | Originally this was the only transform available. It's a standard | |
491 | generic composition of a CPA-secure symmetric encryption scheme with a | |
492 | MAC; initialization vectors for symmetric encryption are chosen at | |
493 | random and included explicitly in the cryptogram. | |
494 | .TP | |
495 | .B iiv | |
496 | A newer `implicit-IV' transform. Rather than having an explicit random | |
b2177d04 | 497 | IV, the IV is computed from the sequence number using a blockcipher. |
b87bffcb MW |
498 | This has two advantages over the |
499 | .B v0 | |
500 | transform. Firstly, it adds less overhead to encrypted messages | |
501 | (because the IV no longer needs to be sent explicitly). Secondly, and | |
502 | more significantly, the transform is entirely deterministic, so (a) it | |
503 | doesn't need the (possibly slow) random number generator, and (b) it | |
504 | closes a kleptographic channel, over which a compromised implementation | |
505 | could leak secret information to a third party. | |
de8edc7f | 506 | .TP |
e53273ef MW |
507 | .B aead |
508 | A transform based on an all-in-one `authenticated encryption with | |
509 | additional data' scheme. The scheme is named in the | |
510 | .B cipher | |
511 | attribute; the default is | |
512 | .BR rijndael-ocb3 . | |
513 | If the | |
514 | .B mac | |
515 | attribute is given, it must be either | |
516 | .B aead | |
517 | or | |
518 | .BR aead/ \c | |
519 | .IR tagsz , | |
520 | where | |
521 | .I tagsz | |
522 | is the desired tag length in bits; alternatively, the tag length can be | |
523 | set in the | |
524 | .B tagsz | |
525 | attribute. The chosen AEAD scheme must accept at least a 64-bit nonce | |
526 | (this rules out OCB3 and CCM with 64-bit blockciphers); it mustn't | |
527 | require an absurdly large nonce size (none of the schemes implemented in | |
528 | Catacomb present a problem here, but it bears mentioning); it must | |
529 | actually support additional header data (which rules out the | |
530 | .B naclbox | |
531 | schemes, but see the | |
532 | .B naclbox | |
533 | transform below); and it must produce an empty ciphertext when | |
534 | encrypting an empty message (again, all of Catacomb's schemes meet this | |
535 | requirement). | |
536 | .TP | |
de8edc7f MW |
537 | .B naclbox |
538 | A transform based on the NaCl | |
539 | .B crypto_secretbox | |
540 | transformation. | |
541 | The main difference is that NaCl uses XSalsa20, | |
542 | while TrIPE uses plain Salsa20 or ChaCha, | |
543 | because it doesn't need the larger nonce space. | |
544 | You can set the | |
545 | .B cipher | |
546 | key attribute to one of | |
547 | .BR salsa20 , | |
548 | .BR salsa20/12 , | |
549 | .BR salsa20/8 , | |
550 | .BR chacha20 , | |
551 | .BR chacha12 , | |
552 | or | |
553 | .B chacha8 | |
554 | to select the main cipher. | |
555 | You can set the | |
556 | .B mac | |
557 | key attribute to | |
558 | .B poly1305 | |
559 | or | |
560 | .B poly1305/128 | |
561 | but these are the default and no other choice is permitted. | |
562 | (This is for forward compatibility, | |
563 | in case other MACs and/or tag sizes are allowed later.) | |
07bdda1f MW |
564 | .SS "Other key attributes" |
565 | The following attributes can also be set on keys. | |
566 | .TP | |
567 | .B serialization | |
568 | Selects group-element serialization formats. | |
569 | The recommended setting is | |
570 | .BR constlen , | |
571 | which selects a constant-length encoding when hashing group elements. | |
572 | The default, | |
573 | for backwards compatibility, is | |
574 | .BR v0 ; | |
575 | but this is deprecated. | |
576 | (The old format uses a variable length format for hashing, | |
577 | which can leak information through timing.) | |
b9066fbb | 578 | .SS "Using SLIP interfaces" |
579 | Though not for the faint of heart, it is possible to get | |
580 | .B tripe | |
581 | to read and write network packets to a pair of file descriptors using | |
582 | SLIP encapsulation. No fancy header compression of any kind is | |
98fdb08d | 583 | supported. |
584 | .PP | |
585 | Two usage modes are supported: a preallocation system, whereby SLIP | |
586 | interfaces are created and passed to the | |
587 | .B tripe | |
588 | server at startup; and a dynamic system, where the server runs a script | |
589 | to allocate a new SLIP interface when it needs one. It is possible to | |
590 | use a mixture of these two modes, starting | |
b9066fbb | 591 | .B tripe |
98fdb08d | 592 | with a few preallocated interfaces and having it allocate more |
593 | dynamically as it needs them. | |
594 | .PP | |
595 | The behaviour of | |
596 | .BR tripe 's | |
597 | SLIP driver is controlled by the | |
598 | .B TRIPE_SLIPIF | |
1f68dfc5 | 599 | environment variable. The server will not create SLIP tunnels if this |
600 | variable is not defined. The variable's value is a colon-delimited list | |
601 | of preallocated interfaces, followed optionally by the filename of a | |
602 | script to run to dynamically allocate more interfaces. | |
b9066fbb | 603 | .PP |
98fdb08d | 604 | A static allocation entry has the form |
b9066fbb | 605 | .IR infd [ \c |
606 | .BI , outfd \c | |
607 | .RB ] \c | |
608 | .BI = \c | |
98fdb08d | 609 | .IR ifname , |
b9066fbb | 610 | If the |
611 | .I outfd | |
612 | is omitted, the same file descriptor is used for input and output. | |
613 | .PP | |
98fdb08d | 614 | The dynamic allocation script must be named by an absolute or relative |
e04c2d50 | 615 | pathname, beginning with |
98fdb08d | 616 | .RB ` / ' |
617 | or | |
618 | .RB ` . '. | |
619 | The server will pass the script an argument, which is the name of the | |
620 | peer for which the interface is being created. The script should | |
621 | allocate a new SLIP interface (presumably by creating a pty pair), | |
622 | configure it appropriately, and write the interface's name to its | |
623 | standard output, followed by a newline. It should then read and write | |
624 | SLIP packets on its stdin and stdout. The script's stdin will be closed | |
625 | when the interface is no longer needed, and the server will attempt to | |
626 | send it a | |
627 | .B SIGTERM | |
628 | signal (though this may fail if the script runs with higher privileges | |
629 | than the server). | |
630 | .PP | |
b9066fbb | 631 | The output file descriptor should not block unless it really needs to: |
632 | the | |
633 | .B tripe | |
1f68dfc5 | 634 | daemon assumes that it won't, and will get wedged waiting for it to |
635 | accept output. | |
74eb47db | 636 | .SS "About the name" |
637 | The program's name is | |
638 | .BR tripe , | |
639 | all in lower-case. The name of the protocol it uses is `TrIPE', with | |
640 | four capital letters and one lower-case. The name stands for `Trivial | |
641 | IP Encryption'. | |
fc916a09 MW |
642 | . |
643 | .\"-------------------------------------------------------------------------- | |
74eb47db | 644 | .SH "BUGS" |
fc916a09 | 645 | . |
74eb47db | 646 | The code hasn't been audited. It may contain security bugs. If you |
647 | find one, please inform the author | |
648 | .IR immediately . | |
fc916a09 MW |
649 | . |
650 | .\"-------------------------------------------------------------------------- | |
74eb47db | 651 | .SH "SEE ALSO" |
fc916a09 | 652 | . |
74eb47db | 653 | .BR key (1), |
654 | .BR tripectl (1), | |
fc5f4823 MW |
655 | .BR tripe\-admin (5), |
656 | .BR tripe\-keys (8). | |
74eb47db | 657 | .PP |
658 | .IR "The Trivial IP Encryption Protocol" , | |
659 | .IR "The Wrestlers Protocol" . | |
fc916a09 MW |
660 | . |
661 | .\"-------------------------------------------------------------------------- | |
74eb47db | 662 | .SH "AUTHOR" |
fc916a09 | 663 | . |
d36eda2a | 664 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
665 | . |
666 | .\"----- That's all, folks -------------------------------------------------- |