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 Use only IPv4 addresses. The server will resolve names only to IPv4
170 addresses, and not attempt to create IPv6 sockets.
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.
178 Dissociates from its terminal and starts running in the background after
179 completing the initialization procedure described above. If running as
182 will not read commands from standard input or write diagnostics to
183 standard output. A better way to start
185 in the background is with
188 .B "\-F, \-\-foreground"
189 Runs the server in the `foreground'; i.e.,
191 will quit if it sees end-of-file on its standard input. This is
195 .BI "\-d, \-\-directory=" dir
198 the current directory. The default directory to change to is given by
199 the environment variable
201 if that's not specified, a default default of
203 is used. Give a current directory of
205 if you don't want it to change directory at all.
207 .BI "\-b, \-\-bind-address="addr
208 Bind the UDP socket to IP address
210 rather than the default of
212 This is useful if your main globally-routable IP address is one you want
213 to tunnel through the VPN.
215 .BI "\-p, \-\-port=" port
216 Use the specified UDP port for all communications with peers, rather
217 than the default port 4070. If this is zero, the kernel will assign a
218 free port, which can be determined using the
220 administration command (see
221 .BR tripe-admin (5)).
223 .BI "\-n, \-\-tunnel=" tunnel
224 Use the specified tunnel driver for new peers by default.
226 .BI "\-U, \-\-setuid=" user
229 (either a user name or integer uid) after initialization. Also set gid
232 primary group, unless overridden by a
234 option. The selected user (and group) will also be the owner of the
235 administration socket.
237 .BI "\-G, \-\-setgid=" group
238 If the current effective uid is zero (i.e., the daemon was invoked as
240 then set gid to that of
242 (either a group name or integer gid) after initialization. In any
243 event, arrange hat the administration socket be owned by the given
246 .BI "\-k, \-\-priv\-keyring=" file
247 Reads the private key from
249 rather than the default
252 .BI "\-K, \-\-pub\-keyring=" file
253 Reads public keys from
255 rather than the default
257 This can be the same as the private keyring, but that's not recommended.
259 .BI "\-t, \-\-tag=" tag
260 Uses the private key whose tag or type is
262 rather than the default
267 .BI "\-a, \-\-admin\-socket=" socket
268 Accept admin connections to a Unix-domain socket named
270 The default socket, if this option isn't specified, is given by the
273 if that's not set either, then a default default of
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
282 configured through the
284 option to connect to the socket, which may be useful. Allowing world access
287 .BI "\-T, \-\-trace=" trace-opts
288 Allows the enabling or disabling of various internal diagnostics. See
289 below for the list of options.
290 .SS "Key exchange group types"
293 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
294 used for bulk data transfer.
296 The server works out which it should be doing based on the key's
299 If this attribute isn't present, then the key's type is examined: if
304 is used. If no group is specified,
306 is used as a fallback.
307 The following groups are defined.
311 Use traditional Diffie\(enHellman in a
312 .IR "Schnorr group" :
313 a prime-order subgroup of the multiplicative group of
314 a finite field; this is the usual
318 kind of Diffie\(en\&Hellman.
320 To create usual Schnorr-group keys, say something like
322 key add \-adh-param \-LS \-b3072 \-B256 \e
323 \-eforever \-tparam tripe\-param kx-group=dh
325 to construct a parameters key; and create the private keys by
327 key add \-adh \-pparam \-talice \e
328 \-e"now + 1 year" tripe
335 Use elliptic curve Diffie\(enHellman.
336 An elliptic curve group is a prime-order
337 subgroup of the abelian group of
339 points on an elliptic curve defined over a finite field
342 Given current public knowledge, elliptic curves can provide similar or
343 better security to systems based on integer discrete log problems,
344 faster, and with less transmitted data. It's a matter of controversy
345 whether this will continue to be the case. The author uses elliptic
348 To create elliptic curve keys, say something like
350 key add \-aec\-param \-Cnist-p256 \-eforever \e
351 \-tparam tripe\-param kx-group=ec
353 to construct a parameters key, using your preferred elliptic curve in
358 for details); and create the private keys by
360 key add \-aec \-pparam \-talice \e
361 \-e"now + 1 year" tripe
368 Use Bernstein's X25519 Diffie\(enHellman function.
369 This is technically a variant on
370 the general elliptic curve Diffie\(enHellman
371 available through the
374 but carefully designed and heavily optimized.
381 key add \-aempty \-eforever \e
382 \-tparam tripe\-param kx-group=x25519
384 to construct a parameters key
388 and create the private keys by
390 key add \-ax25519 \-pparam \-talice \e
391 \-e"now + 1 year" tripe
398 Use Hamburg's X448 Diffie\(enHellman function.
402 this is technically a variant on
403 the general elliptic curve Diffie\(enHellman
404 available through the
407 but carefully designed and heavily optimized.
414 key add \-aempty \-eforever \e
415 \-tparam tripe\-param kx-group=x448
417 to construct a parameters key
421 and create the private keys by
423 key add \-ax448 \-pparam \-talice \e
424 \-e"now + 1 year" tripe
429 program provides a rather more convenient means for generating and
432 .SS "Using other symmetric algorithms"
433 The default symmetric algorithms
435 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
436 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
437 mode, designed by Bellare, Canetti and Krawczyk). These can all be
438 overridden by setting attributes on your private key, as follows.
441 Names the bulk-crypto transform to use. See below.
444 Names a blockcipher, used by some bulk-crypto transforms (e.g.,
446 The default is to use the blockcipher underlying the chosen
451 Names the symmetric encryption scheme to use. The default is
455 Names the hash function to use. The default is
459 Names the message authentication code to use. The name of the MAC may
462 and the desired tag length in bits. The default is
464 at half the underlying hash function's output length.
465 If the MAC's name contains a
473 and the tag size is required to disambiguate,
476 .RB ` sha512/256/256 '.
479 A `mask-generation function', used in the key-exchange. The default is
481 and there's no good reason to change it.
483 The available bulk-crypto transforms are as follows.
486 Originally this was the only transform available. It's a standard
487 generic composition of a CPA-secure symmetric encryption scheme with a
488 MAC; initialization vectors for symmetric encryption are chosen at
489 random and included explicitly in the cryptogram.
492 A newer `implicit-IV' transform. Rather than having an explicit random
493 IV, the IV is computed from the sequence number using a blockcipher.
494 This has two advantages over the
496 transform. Firstly, it adds less overhead to encrypted messages
497 (because the IV no longer needs to be sent explicitly). Secondly, and
498 more significantly, the transform is entirely deterministic, so (a) it
499 doesn't need the (possibly slow) random number generator, and (b) it
500 closes a kleptographic channel, over which a compromised implementation
501 could leak secret information to a third party.
504 A transform based on an all-in-one `authenticated encryption with
505 additional data' scheme. The scheme is named in the
507 attribute; the default is
511 attribute is given, it must be either
518 is the desired tag length in bits; alternatively, the tag length can be
521 attribute. The chosen AEAD scheme must accept at least a 64-bit nonce
522 (this rules out OCB3 and CCM with 64-bit blockciphers); it mustn't
523 require an absurdly large nonce size (none of the schemes implemented in
524 Catacomb present a problem here, but it bears mentioning); it must
525 actually support additional header data (which rules out the
529 transform below); and it must produce an empty ciphertext when
530 encrypting an empty message (again, all of Catacomb's schemes meet this
534 A transform based on the NaCl
537 The main difference is that NaCl uses XSalsa20,
538 while TrIPE uses plain Salsa20 or ChaCha,
539 because it doesn't need the larger nonce space.
542 key attribute to one of
550 to select the main cipher.
557 but these are the default and no other choice is permitted.
558 (This is for forward compatibility,
559 in case other MACs and/or tag sizes are allowed later.)
560 .SS "Other key attributes"
561 The following attributes can also be set on keys.
564 Selects group-element serialization formats.
565 The recommended setting is
567 which selects a constant-length encoding when hashing group elements.
569 for backwards compatibility, is
571 but this is deprecated.
572 (The old format uses a variable length format for hashing,
573 which can leak information through timing.)
574 .SS "Using SLIP interfaces"
575 Though not for the faint of heart, it is possible to get
577 to read and write network packets to a pair of file descriptors using
578 SLIP encapsulation. No fancy header compression of any kind is
581 Two usage modes are supported: a preallocation system, whereby SLIP
582 interfaces are created and passed to the
584 server at startup; and a dynamic system, where the server runs a script
585 to allocate a new SLIP interface when it needs one. It is possible to
586 use a mixture of these two modes, starting
588 with a few preallocated interfaces and having it allocate more
589 dynamically as it needs them.
593 SLIP driver is controlled by the
595 environment variable. The server will not create SLIP tunnels if this
596 variable is not defined. The variable's value is a colon-delimited list
597 of preallocated interfaces, followed optionally by the filename of a
598 script to run to dynamically allocate more interfaces.
600 A static allocation entry has the form
608 is omitted, the same file descriptor is used for input and output.
610 The dynamic allocation script must be named by an absolute or relative
611 pathname, beginning with
615 The server will pass the script an argument, which is the name of the
616 peer for which the interface is being created. The script should
617 allocate a new SLIP interface (presumably by creating a pty pair),
618 configure it appropriately, and write the interface's name to its
619 standard output, followed by a newline. It should then read and write
620 SLIP packets on its stdin and stdout. The script's stdin will be closed
621 when the interface is no longer needed, and the server will attempt to
624 signal (though this may fail if the script runs with higher privileges
627 The output file descriptor should not block unless it really needs to:
630 daemon assumes that it won't, and will get wedged waiting for it to
633 The program's name is
635 all in lower-case. The name of the protocol it uses is `TrIPE', with
636 four capital letters and one lower-case. The name stands for `Trivial
639 .\"--------------------------------------------------------------------------
642 The code hasn't been audited. It may contain security bugs. If you
643 find one, please inform the author
646 .\"--------------------------------------------------------------------------
651 .BR tripe\-admin (5),
654 .IR "The Trivial IP Encryption Protocol" ,
655 .IR "The Wrestlers Protocol" .
657 .\"--------------------------------------------------------------------------
660 Mark Wooding, <mdw@distorted.org.uk>
662 .\"----- That's all, folks --------------------------------------------------