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
293 for the list of options.
294 .SS "Key exchange group types"
297 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
298 used for bulk data transfer.
300 The server works out which it should be doing based on the key's
303 If this attribute isn't present, then the key's type is examined: if
308 is used. If no group is specified,
310 is used as a fallback.
311 The following groups are defined.
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
322 kind of Diffie\(en\&Hellman.
324 To create usual Schnorr-group keys, say something like
326 key add \-adh-param \-LS \-b3072 \-B256 \e
327 \-eforever \-tparam tripe\-param kx-group=dh
329 to construct a parameters key; and create the private keys by
331 key add \-adh \-pparam \-talice \e
332 \-e"now + 1 year" tripe
339 Use elliptic curve Diffie\(enHellman.
340 An elliptic curve group is a prime-order
341 subgroup of the abelian group of
343 points on an elliptic curve defined over a finite field
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
352 To create elliptic curve keys, say something like
354 key add \-aec\-param \-Cnist-p256 \-eforever \e
355 \-tparam tripe\-param kx-group=ec
357 to construct a parameters key, using your preferred elliptic curve in
362 for details); and create the private keys by
364 key add \-aec \-pparam \-talice \e
365 \-e"now + 1 year" tripe
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
378 but carefully designed and heavily optimized.
385 key add \-aempty \-eforever \e
386 \-tparam tripe\-param kx-group=x25519
388 to construct a parameters key
392 and create the private keys by
394 key add \-ax25519 \-pparam \-talice \e
395 \-e"now + 1 year" tripe
402 Use Hamburg's X448 Diffie\(enHellman function.
406 this is technically a variant on
407 the general elliptic curve Diffie\(enHellman
408 available through the
411 but carefully designed and heavily optimized.
418 key add \-aempty \-eforever \e
419 \-tparam tripe\-param kx-group=x448
421 to construct a parameters key
425 and create the private keys by
427 key add \-ax448 \-pparam \-talice \e
428 \-e"now + 1 year" tripe
433 program provides a rather more convenient means for generating and
436 .SS "Using other symmetric algorithms"
437 The default symmetric algorithms
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.
445 Names the bulk-crypto transform to use. See below.
448 Names a blockcipher, used by some bulk-crypto transforms (e.g.,
450 The default is to use the blockcipher underlying the chosen
455 Names the symmetric encryption scheme to use. The default is
459 Names the hash function to use. The default is
463 Names the message authentication code to use. The name of the MAC may
466 and the desired tag length in bits. The default is
468 at half the underlying hash function's output length.
469 If the MAC's name contains a
477 and the tag size is required to disambiguate,
480 .RB ` sha512/256/256 '.
483 A `mask-generation function', used in the key-exchange. The default is
485 and there's no good reason to change it.
487 The available bulk-crypto transforms are as follows.
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.
496 A newer `implicit-IV' transform. Rather than having an explicit random
497 IV, the IV is computed from the sequence number using a blockcipher.
498 This has two advantages over the
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.
508 A transform based on an all-in-one `authenticated encryption with
509 additional data' scheme. The scheme is named in the
511 attribute; the default is
515 attribute is given, it must be either
522 is the desired tag length in bits; alternatively, the tag length can be
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
533 transform below); and it must produce an empty ciphertext when
534 encrypting an empty message (again, all of Catacomb's schemes meet this
538 A transform based on the NaCl
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.
546 key attribute to one of
554 to select the main cipher.
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.)
564 .SS "Other key attributes"
565 The following attributes can also be set on keys.
568 Selects group-element serialization formats.
569 The recommended setting is
571 which selects a constant-length encoding when hashing group elements.
573 for backwards compatibility, is
575 but this is deprecated.
576 (The old format uses a variable length format for hashing,
577 which can leak information through timing.)
578 .SS "Using SLIP interfaces"
579 Though not for the faint of heart, it is possible to get
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
585 Two usage modes are supported: a preallocation system, whereby SLIP
586 interfaces are created and passed to the
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
592 with a few preallocated interfaces and having it allocate more
593 dynamically as it needs them.
597 SLIP driver is controlled by the
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.
604 A static allocation entry has the form
612 is omitted, the same file descriptor is used for input and output.
614 The dynamic allocation script must be named by an absolute or relative
615 pathname, beginning with
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
628 signal (though this may fail if the script runs with higher privileges
631 The output file descriptor should not block unless it really needs to:
634 daemon assumes that it won't, and will get wedged waiting for it to
637 The program's name is
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
643 .\"--------------------------------------------------------------------------
646 The code hasn't been audited. It may contain security bugs. If you
647 find one, please inform the author
650 .\"--------------------------------------------------------------------------
655 .BR tripe\-admin (5),
658 .IR "The Trivial IP Encryption Protocol" ,
659 .IR "The Wrestlers Protocol" .
661 .\"--------------------------------------------------------------------------
664 Mark Wooding, <mdw@distorted.org.uk>
666 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob