3 .\" Manual for the server
5 .\" (c) 2008 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
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.
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.
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.
26 .\"--------------------------------------------------------------------------
27 .so ../common/defs.man \" @@@PRE@@@
29 .\"--------------------------------------------------------------------------
30 .TH tripe 8tripe "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
32 .\"--------------------------------------------------------------------------
35 tripe \- a simple VPN daemon
37 .\"--------------------------------------------------------------------------
71 .\"--------------------------------------------------------------------------
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.
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
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
97 server admin commands is described in
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,
106 will initialize by following these steps:
108 It sets the directory named by the
110 environment variable (or
112 if the variable is unset) as the current directory.
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
119 .BR tripe\-admin (5)).
121 It loads the private key with the tag or type name
125 for backwards compatibility reasons) from the Catacomb-format file
129 ready for extracting the public keys of peers as they're introduced.
130 (The format of these files is described in
132 They are maintained using the program
134 provided with the Catacomb distribution.)
136 It creates and listens to the Unix-domain socket
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.
148 Much of this behaviour may be altered by giving
150 suitable command-line options:
153 Writes a brief description of the command-line options available to
154 standard output and exits with status 0.
156 .B "\-v, \-\-version"
159 version number to standard output and exits with status 0.
162 Writes a brief usage summary to standard output and exits with status 0.
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.
170 Dissociates from its terminal and starts running in the background after
171 completing the initialization procedure described above. If running as
174 will not read commands from standard input or write diagnostics to
175 standard output. A better way to start
177 in the background is with
180 .B "\-F, \-\-foreground"
181 Runs the server in the `foreground'; i.e.,
183 will quit if it sees end-of-file on its standard input. This is
187 .BI "\-d, \-\-directory=" dir
190 the current directory. The default directory to change to is given by
191 the environment variable
193 if that's not specified, a default default of
195 is used. Give a current directory of
197 if you don't want it to change directory at all.
199 .BI "\-b, \-\-bind-address="addr
200 Bind the UDP socket to IP address
202 rather than the default of
204 This is useful if your main globally-routable IP address is one you want
205 to tunnel through the VPN.
207 .BI "\-p, \-\-port=" port
208 Use the specified UDP port for all communications with peers, rather
209 than an arbitarary kernel-assigned port.
211 .BI "\-n, \-\-tunnel=" tunnel
212 Use the specified tunnel driver for new peers by default.
214 .BI "\-U, \-\-setuid=" user
217 (either a user name or integer uid) after initialization. Also set gid
220 primary group, unless overridden by a
222 option. The selected user (and group) will also be the owner of the
223 administration socket.
225 .BI "\-G, \-\-setgid=" group
226 If the current effective uid is zero (i.e., the daemon was invoked as
228 then set gid to that of
230 (either a group name or integer gid) after initialization. In any
231 event, arrange hat the administration socket be owned by the given
234 .BI "\-k, \-\-priv\-keyring=" file
235 Reads the private key from
237 rather than the default
240 .BI "\-K, \-\-pub\-keyring=" file
241 Reads public keys from
243 rather than the default
245 This can be the same as the private keyring, but that's not recommended.
247 .BI "\-t, \-\-tag=" tag
248 Uses the private key whose tag or type is
250 rather than the default
255 .BI "\-a, \-\-admin\-socket=" socket
256 Accept admin connections to a Unix-domain socket named
258 The default socket, if this option isn't specified, is given by the
261 if that's not set either, then a default default of
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
270 configured through the
272 option to connect to the socket, which may be useful. Allowing world access
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"
281 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
282 used for bulk data transfer.
284 The server works out which it should be doing based on the key's
287 If this attribute isn't present, then the key's type is examined: if
292 is used. If no group is specified,
294 is used as a fallback.
295 The following groups are defined.
299 Use traditional Diffie\(enHellman in a
300 .IR "Schnorr group" :
301 a prime-order subgroup of the multiplicative group of
302 a finite field; this is the usual
306 kind of Diffie\(en\&Hellman.
308 To create usual Schnorr-group keys, say something like
310 key add \-adh-param \-LS \-b3072 \-B256 \e
311 \-eforever \-tparam tripe\-param kx-group=dh
313 to construct a parameters key; and create the private keys by
315 key add \-adh \-pparam \-talice \e
316 \-e"now + 1 year" tripe
323 Use elliptic curve Diffie\(enHellman.
324 An elliptic curve group is a prime-order
325 subgroup of the abelian group of
327 points on an elliptic curve defined over a finite field
330 Given current public knowledge, elliptic curves can provide similar or
331 better security to systems based on integer discrete log problems,
332 faster, and with less transmitted data. It's a matter of controversy
333 whether this will continue to be the case. The author uses elliptic
336 To create elliptic curve keys, say something like
338 key add \-aec\-param \-Cnist-p256 \-eforever \e
339 \-tparam tripe\-param kx-group=ec
341 to construct a parameters key, using your preferred elliptic curve in
346 for details); and create the private keys by
348 key add \-aec \-pparam \-talice \e
349 \-e"now + 1 year" tripe
356 Use Bernstein's X25519 Diffie\(enHellman function.
357 This is technically a variant on
358 the general elliptic curve Diffie\(enHellman
359 available through the
362 but carefully designed and heavily optimized.
369 key add \-aempty \-eforever \e
370 \-tparam tripe\-param kx-group=x25519
372 to construct a parameters key
376 and create the private keys by
378 key add \-ax25519 \-pparam \-talice \e
379 \-e"now + 1 year" tripe
386 Use Hamburg's X448 Diffie\(enHellman function.
390 this is technically a variant on
391 the general elliptic curve Diffie\(enHellman
392 available through the
395 but carefully designed and heavily optimized.
402 key add \-aempty \-eforever \e
403 \-tparam tripe\-param kx-group=x448
405 to construct a parameters key
409 and create the private keys by
411 key add \-ax448 \-pparam \-talice \e
412 \-e"now + 1 year" tripe
417 program provides a rather more convenient means for generating and
420 .SS "Using other symmetric algorithms"
421 The default symmetric algorithms
423 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
424 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
425 mode, designed by Bellare, Canetti and Krawczyk). These can all be
426 overridden by setting attributes on your private key, as follows.
429 Names the bulk-crypto transform to use. See below.
432 Names a block cipher, used by some bulk-crypto transforms (e.g.,
434 The default is to use the block cipher underlying the chosen
439 Names the symmetric encryption scheme to use. The default is
443 Names the hash function to use. The default is
447 Names the message authentication code to use. The name of the MAC may
450 and the desired tag length in bits. The default is
452 at half the underlying hash function's output length.
453 If the MAC's name contains a
461 and the tag size is required to disambiguate,
464 .RB ` sha512/256/256 '.
467 A `mask-generation function', used in the key-exchange. The default is
469 and there's no good reason to change it.
471 The available bulk-crypto transforms are as follows.
474 Originally this was the only transform available. It's a standard
475 generic composition of a CPA-secure symmetric encryption scheme with a
476 MAC; initialization vectors for symmetric encryption are chosen at
477 random and included explicitly in the cryptogram.
480 A newer `implicit-IV' transform. Rather than having an explicit random
481 IV, the IV is computed from the sequence number using a block cipher.
482 This has two advantages over the
484 transform. Firstly, it adds less overhead to encrypted messages
485 (because the IV no longer needs to be sent explicitly). Secondly, and
486 more significantly, the transform is entirely deterministic, so (a) it
487 doesn't need the (possibly slow) random number generator, and (b) it
488 closes a kleptographic channel, over which a compromised implementation
489 could leak secret information to a third party.
492 A transform based on the NaCl
495 The main difference is that NaCl uses XSalsa20,
496 while TrIPE uses plain Salsa20 or ChaCha,
497 because it doesn't need the larger nonce space.
500 key attribute to one of
508 to select the main cipher.
515 but these are the default and no other choice is permitted.
516 (This is for forward compatibility,
517 in case other MACs and/or tag sizes are allowed later.)
518 .SS "Other key attributes"
519 The following attributes can also be set on keys.
522 Selects group-element serialization formats.
523 The recommended setting is
525 which selects a constant-length encoding when hashing group elements.
527 for backwards compatibility, is
529 but this is deprecated.
530 (The old format uses a variable length format for hashing,
531 which can leak information through timing.)
532 .SS "Using SLIP interfaces"
533 Though not for the faint of heart, it is possible to get
535 to read and write network packets to a pair of file descriptors using
536 SLIP encapsulation. No fancy header compression of any kind is
539 Two usage modes are supported: a preallocation system, whereby SLIP
540 interfaces are created and passed to the
542 server at startup; and a dynamic system, where the server runs a script
543 to allocate a new SLIP interface when it needs one. It is possible to
544 use a mixture of these two modes, starting
546 with a few preallocated interfaces and having it allocate more
547 dynamically as it needs them.
551 SLIP driver is controlled by the
553 environment variable. The server will not create SLIP tunnels if this
554 variable is not defined. The variable's value is a colon-delimited list
555 of preallocated interfaces, followed optionally by the filename of a
556 script to run to dynamically allocate more interfaces.
558 A static allocation entry has the form
566 is omitted, the same file descriptor is used for input and output.
568 The dynamic allocation script must be named by an absolute or relative
569 pathname, beginning with
573 The server will pass the script an argument, which is the name of the
574 peer for which the interface is being created. The script should
575 allocate a new SLIP interface (presumably by creating a pty pair),
576 configure it appropriately, and write the interface's name to its
577 standard output, followed by a newline. It should then read and write
578 SLIP packets on its stdin and stdout. The script's stdin will be closed
579 when the interface is no longer needed, and the server will attempt to
582 signal (though this may fail if the script runs with higher privileges
585 The output file descriptor should not block unless it really needs to:
588 daemon assumes that it won't, and will get wedged waiting for it to
591 The program's name is
593 all in lower-case. The name of the protocol it uses is `TrIPE', with
594 four capital letters and one lower-case. The name stands for `Trivial
597 .\"--------------------------------------------------------------------------
600 The code hasn't been audited. It may contain security bugs. If you
601 find one, please inform the author
604 .\"--------------------------------------------------------------------------
609 .BR tripe\-admin (5),
612 .IR "The Trivial IP Encryption Protocol" ,
613 .IR "The Wrestlers Protocol" .
615 .\"--------------------------------------------------------------------------
618 Mark Wooding, <mdw@distorted.org.uk>
620 .\"----- That's all, folks --------------------------------------------------