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 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.
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
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
25 .\"--------------------------------------------------------------------------
26 .so ../common/defs.man \" @@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH tripe 8tripe "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
34 tripe \- a simple VPN daemon
36 .\"--------------------------------------------------------------------------
70 .\"--------------------------------------------------------------------------
75 program is a server which can provide strong IP-level encryption and
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.
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
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
96 server admin commands is described in
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,
105 will initialize by following these steps:
107 It sets the directory named by the
109 environment variable (or
111 if the variable is unset) as the current directory.
113 It acquires a UDP socket. The default port is 4070
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
118 .BR tripe\-admin (5)).
120 It loads the private key with the tag or type name
124 for backwards compatibility reasons) from the Catacomb-format file
128 ready for extracting the public keys of peers as they're introduced.
129 (The format of these files is described in
131 They are maintained using the program
133 provided with the Catacomb distribution.)
135 It creates and listens to the Unix-domain socket
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
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.
147 Much of this behaviour may be altered by giving
149 suitable command-line options:
152 Writes a brief description of the command-line options available to
153 standard output and exits with status 0.
155 .B "\-v, \-\-version"
158 version number to standard output and exits with status 0.
161 Writes a brief usage summary to standard output and exits with status 0.
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
166 start-up script, so that it can check that it will actually work.
169 Dissociates from its terminal and starts running in the background after
170 completing the initialization procedure described above. If running as
173 will not read commands from standard input or write diagnostics to
174 standard output. A better way to start
176 in the background is with
179 .B "\-F, \-\-foreground"
180 Runs the server in the `foreground'; i.e.,
182 will quit if it sees end-of-file on its standard input. This is
186 .BI "\-d, \-\-directory=" dir
189 the current directory. The default directory to change to is given by
190 the environment variable
192 if that's not specified, a default default of
194 is used. Give a current directory of
196 if you don't want it to change directory at all.
198 .BI "\-b, \-\-bind-address="addr
199 Bind the UDP socket to IP address
201 rather than the default of
203 This is useful if your main globally-routable IP address is one you want
204 to tunnel through the VPN.
206 .BI "\-p, \-\-port=" port
207 Use the specified UDP port for all communications with peers, rather
208 than the default port 4070. If this is zero, the kernel will assign a
209 free port, which can be determined using the
211 administration command (see
212 .BR tripe-admin (5)).
214 .BI "\-n, \-\-tunnel=" tunnel
215 Use the specified tunnel driver for new peers by default.
217 .BI "\-U, \-\-setuid=" user
220 (either a user name or integer uid) after initialization. Also set gid
223 primary group, unless overridden by a
225 option. The selected user (and group) will also be the owner of the
226 administration socket.
228 .BI "\-G, \-\-setgid=" group
229 If the current effective uid is zero (i.e., the daemon was invoked as
231 then set gid to that of
233 (either a group name or integer gid) after initialization. In any
234 event, arrange hat the administration socket be owned by the given
237 .BI "\-k, \-\-priv\-keyring=" file
238 Reads the private key from
240 rather than the default
243 .BI "\-K, \-\-pub\-keyring=" file
244 Reads public keys from
246 rather than the default
248 This can be the same as the private keyring, but that's not recommended.
250 .BI "\-t, \-\-tag=" tag
251 Uses the private key whose tag or type is
253 rather than the default
258 .BI "\-a, \-\-admin\-socket=" socket
259 Accept admin connections to a Unix-domain socket named
261 The default socket, if this option isn't specified, is given by the
264 if that's not set either, then a default default of
268 .BI "\-m, \-\-admin\-perms=" mode
269 Permissions (as an octal number) to set on the administration socket. The
270 default is 600, which allows only the socket owner. Setting 660 allows
273 configured through the
275 option to connect to the socket, which may be useful. Allowing world access
278 .BI "\-T, \-\-trace=" trace-opts
279 Allows the enabling or disabling of various internal diagnostics. See
280 below for the list of options.
281 .SS "Key exchange group types"
284 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
285 used for bulk data transfer.
287 The server works out which it should be doing based on the key's
290 If this attribute isn't present, then the key's type is examined: if
295 is used. If no group is specified,
297 is used as a fallback.
298 The following groups are defined.
302 Use traditional Diffie\(enHellman in a
303 .IR "Schnorr group" :
304 a prime-order subgroup of the multiplicative group of
305 a finite field; this is the usual
309 kind of Diffie\(en\&Hellman.
311 To create usual Schnorr-group keys, say something like
313 key add \-adh-param \-LS \-b3072 \-B256 \e
314 \-eforever \-tparam tripe\-param kx-group=dh
316 to construct a parameters key; and create the private keys by
318 key add \-adh \-pparam \-talice \e
319 \-e"now + 1 year" tripe
326 Use elliptic curve Diffie\(enHellman.
327 An elliptic curve group is a prime-order
328 subgroup of the abelian group of
330 points on an elliptic curve defined over a finite field
333 Given current public knowledge, elliptic curves can provide similar or
334 better security to systems based on integer discrete log problems,
335 faster, and with less transmitted data. It's a matter of controversy
336 whether this will continue to be the case. The author uses elliptic
339 To create elliptic curve keys, say something like
341 key add \-aec\-param \-Cnist-p256 \-eforever \e
342 \-tparam tripe\-param kx-group=ec
344 to construct a parameters key, using your preferred elliptic curve in
349 for details); and create the private keys by
351 key add \-aec \-pparam \-talice \e
352 \-e"now + 1 year" tripe
359 Use Bernstein's X25519 Diffie\(enHellman function.
360 This is technically a variant on
361 the general elliptic curve Diffie\(enHellman
362 available through the
365 but carefully designed and heavily optimized.
372 key add \-aempty \-eforever \e
373 \-tparam tripe\-param kx-group=x25519
375 to construct a parameters key
379 and create the private keys by
381 key add \-ax25519 \-pparam \-talice \e
382 \-e"now + 1 year" tripe
389 Use Hamburg's X448 Diffie\(enHellman function.
393 this is technically a variant on
394 the general elliptic curve Diffie\(enHellman
395 available through the
398 but carefully designed and heavily optimized.
405 key add \-aempty \-eforever \e
406 \-tparam tripe\-param kx-group=x448
408 to construct a parameters key
412 and create the private keys by
414 key add \-ax448 \-pparam \-talice \e
415 \-e"now + 1 year" tripe
420 program provides a rather more convenient means for generating and
423 .SS "Using other symmetric algorithms"
424 The default symmetric algorithms
426 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
427 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
428 mode, designed by Bellare, Canetti and Krawczyk). These can all be
429 overridden by setting attributes on your private key, as follows.
432 Names the bulk-crypto transform to use. See below.
435 Names a block cipher, used by some bulk-crypto transforms (e.g.,
437 The default is to use the block cipher underlying the chosen
442 Names the symmetric encryption scheme to use. The default is
446 Names the hash function to use. The default is
450 Names the message authentication code to use. The name of the MAC may
453 and the desired tag length in bits. The default is
455 at half the underlying hash function's output length.
456 If the MAC's name contains a
464 and the tag size is required to disambiguate,
467 .RB ` sha512/256/256 '.
470 A `mask-generation function', used in the key-exchange. The default is
472 and there's no good reason to change it.
474 The available bulk-crypto transforms are as follows.
477 Originally this was the only transform available. It's a standard
478 generic composition of a CPA-secure symmetric encryption scheme with a
479 MAC; initialization vectors for symmetric encryption are chosen at
480 random and included explicitly in the cryptogram.
483 A newer `implicit-IV' transform. Rather than having an explicit random
484 IV, the IV is computed from the sequence number using a block cipher.
485 This has two advantages over the
487 transform. Firstly, it adds less overhead to encrypted messages
488 (because the IV no longer needs to be sent explicitly). Secondly, and
489 more significantly, the transform is entirely deterministic, so (a) it
490 doesn't need the (possibly slow) random number generator, and (b) it
491 closes a kleptographic channel, over which a compromised implementation
492 could leak secret information to a third party.
495 A transform based on the NaCl
498 The main difference is that NaCl uses XSalsa20,
499 while TrIPE uses plain Salsa20 or ChaCha,
500 because it doesn't need the larger nonce space.
503 key attribute to one of
511 to select the main cipher.
518 but these are the default and no other choice is permitted.
519 (This is for forward compatibility,
520 in case other MACs and/or tag sizes are allowed later.)
521 .SS "Other key attributes"
522 The following attributes can also be set on keys.
525 Selects group-element serialization formats.
526 The recommended setting is
528 which selects a constant-length encoding when hashing group elements.
530 for backwards compatibility, is
532 but this is deprecated.
533 (The old format uses a variable length format for hashing,
534 which can leak information through timing.)
535 .SS "Using SLIP interfaces"
536 Though not for the faint of heart, it is possible to get
538 to read and write network packets to a pair of file descriptors using
539 SLIP encapsulation. No fancy header compression of any kind is
542 Two usage modes are supported: a preallocation system, whereby SLIP
543 interfaces are created and passed to the
545 server at startup; and a dynamic system, where the server runs a script
546 to allocate a new SLIP interface when it needs one. It is possible to
547 use a mixture of these two modes, starting
549 with a few preallocated interfaces and having it allocate more
550 dynamically as it needs them.
554 SLIP driver is controlled by the
556 environment variable. The server will not create SLIP tunnels if this
557 variable is not defined. The variable's value is a colon-delimited list
558 of preallocated interfaces, followed optionally by the filename of a
559 script to run to dynamically allocate more interfaces.
561 A static allocation entry has the form
569 is omitted, the same file descriptor is used for input and output.
571 The dynamic allocation script must be named by an absolute or relative
572 pathname, beginning with
576 The server will pass the script an argument, which is the name of the
577 peer for which the interface is being created. The script should
578 allocate a new SLIP interface (presumably by creating a pty pair),
579 configure it appropriately, and write the interface's name to its
580 standard output, followed by a newline. It should then read and write
581 SLIP packets on its stdin and stdout. The script's stdin will be closed
582 when the interface is no longer needed, and the server will attempt to
585 signal (though this may fail if the script runs with higher privileges
588 The output file descriptor should not block unless it really needs to:
591 daemon assumes that it won't, and will get wedged waiting for it to
594 The program's name is
596 all in lower-case. The name of the protocol it uses is `TrIPE', with
597 four capital letters and one lower-case. The name stands for `Trivial
600 .\"--------------------------------------------------------------------------
603 The code hasn't been audited. It may contain security bugs. If you
604 find one, please inform the author
607 .\"--------------------------------------------------------------------------
612 .BR tripe\-admin (5),
615 .IR "The Trivial IP Encryption Protocol" ,
616 .IR "The Wrestlers Protocol" .
618 .\"--------------------------------------------------------------------------
621 Mark Wooding, <mdw@distorted.org.uk>
623 .\"----- That's all, folks --------------------------------------------------