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 with an arbitrary kernel-selected port number.
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 an arbitarary kernel-assigned port.
210 .BI "\-n, \-\-tunnel=" tunnel
211 Use the specified tunnel driver for new peers by default.
213 .BI "\-U, \-\-setuid=" user
216 (either a user name or integer uid) after initialization. Also set gid
219 primary group, unless overridden by a
221 option. The selected user (and group) will also be the owner of the
222 administration socket.
224 .BI "\-G, \-\-setgid=" group
225 If the current effective uid is zero (i.e., the daemon was invoked as
227 then set gid to that of
229 (either a group name or integer gid) after initialization. In any
230 event, arrange hat the administration socket be owned by the given
233 .BI "\-k, \-\-priv\-keyring=" file
234 Reads the private key from
236 rather than the default
239 .BI "\-K, \-\-pub\-keyring=" file
240 Reads public keys from
242 rather than the default
244 This can be the same as the private keyring, but that's not recommended.
246 .BI "\-t, \-\-tag=" tag
247 Uses the private key whose tag or type is
249 rather than the default
254 .BI "\-a, \-\-admin\-socket=" socket
255 Accept admin connections to a Unix-domain socket named
257 The default socket, if this option isn't specified, is given by the
260 if that's not set either, then a default default of
264 .BI "\-m, \-\-admin\-perms=" mode
265 Permissions (as an octal number) to set on the administration socket. The
266 default is 600, which allows only the socket owner. Setting 660 allows
269 configured through the
271 option to connect to the socket, which may be useful. Allowing world access
274 .BI "\-T, \-\-trace=" trace-opts
275 Allows the enabling or disabling of various internal diagnostics. See
276 below for the list of options.
277 .SS "Key exchange group types"
280 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
281 used for bulk data transfer.
283 The server works out which it should be doing based on the key's
286 If this attribute isn't present, then the key's type is examined: if
291 is used. If no group is specified,
293 is used as a fallback.
294 The following groups are defined.
298 Use traditional Diffie\(enHellman in a
299 .IR "Schnorr group" :
300 a prime-order subgroup of the multiplicative group of
301 a finite field; this is the usual
305 kind of Diffie\(en\&Hellman.
307 To create usual Schnorr-group keys, say something like
309 key add \-adh-param \-LS \-b3072 \-B256 \e
310 \-eforever \-tparam tripe\-param kx-group=dh
312 to construct a parameters key; and create the private keys by
314 key add \-adh \-pparam \-talice \e
315 \-e"now + 1 year" tripe
322 Use elliptic curve Diffie\(enHellman.
323 An elliptic curve group is a prime-order
324 subgroup of the abelian group of
326 points on an elliptic curve defined over a finite field
329 Given current public knowledge, elliptic curves can provide similar or
330 better security to systems based on integer discrete log problems,
331 faster, and with less transmitted data. It's a matter of controversy
332 whether this will continue to be the case. The author uses elliptic
335 To create elliptic curve keys, say something like
337 key add \-aec\-param \-Cnist-p256 \-eforever \e
338 \-tparam tripe\-param kx-group=ec
340 to construct a parameters key, using your preferred elliptic curve in
345 for details); and create the private keys by
347 key add \-aec \-pparam \-talice \e
348 \-e"now + 1 year" tripe
355 Use Bernstein's X25519 Diffie\(enHellman function.
356 This is technically a variant on
357 the general elliptic curve Diffie\(enHellman
358 available through the
361 but carefully designed and heavily optimized.
368 key add \-aempty \-eforever \e
369 \-tparam tripe\-param kx-group=x25519
371 to construct a parameters key
375 and create the private keys by
377 key add \-ax25519 \-pparam \-talice \e
378 \-e"now + 1 year" tripe
385 Use Hamburg's X448 Diffie\(enHellman function.
389 this is technically a variant on
390 the general elliptic curve Diffie\(enHellman
391 available through the
394 but carefully designed and heavily optimized.
401 key add \-aempty \-eforever \e
402 \-tparam tripe\-param kx-group=x448
404 to construct a parameters key
408 and create the private keys by
410 key add \-ax448 \-pparam \-talice \e
411 \-e"now + 1 year" tripe
416 program provides a rather more convenient means for generating and
419 .SS "Using other symmetric algorithms"
420 The default symmetric algorithms
422 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
423 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
424 mode, designed by Bellare, Canetti and Krawczyk). These can all be
425 overridden by setting attributes on your private key, as follows.
428 Names the bulk-crypto transform to use. See below.
431 Names a block cipher, used by some bulk-crypto transforms (e.g.,
433 The default is to use the block cipher underlying the chosen
438 Names the symmetric encryption scheme to use. The default is
442 Names the hash function to use. The default is
446 Names the message authentication code to use. The name of the MAC may
449 and the desired tag length in bits. The default is
451 at half the underlying hash function's output length.
452 If the MAC's name contains a
460 and the tag size is required to disambiguate,
463 .RB ` sha512/256/256 '.
466 A `mask-generation function', used in the key-exchange. The default is
468 and there's no good reason to change it.
470 The available bulk-crypto transforms are as follows.
473 Originally this was the only transform available. It's a standard
474 generic composition of a CPA-secure symmetric encryption scheme with a
475 MAC; initialization vectors for symmetric encryption are chosen at
476 random and included explicitly in the cryptogram.
479 A newer `implicit-IV' transform. Rather than having an explicit random
480 IV, the IV is computed from the sequence number using a block cipher.
481 This has two advantages over the
483 transform. Firstly, it adds less overhead to encrypted messages
484 (because the IV no longer needs to be sent explicitly). Secondly, and
485 more significantly, the transform is entirely deterministic, so (a) it
486 doesn't need the (possibly slow) random number generator, and (b) it
487 closes a kleptographic channel, over which a compromised implementation
488 could leak secret information to a third party.
491 A transform based on the NaCl
494 The main difference is that NaCl uses XSalsa20,
495 while TrIPE uses plain Salsa20 or ChaCha,
496 because it doesn't need the larger nonce space.
499 key attribute to one of
507 to select the main cipher.
514 but these are the default and no other choice is permitted.
515 (This is for forward compatibility,
516 in case other MACs and/or tag sizes are allowed later.)
517 .SS "Other key attributes"
518 The following attributes can also be set on keys.
521 Selects group-element serialization formats.
522 The recommended setting is
524 which selects a constant-length encoding when hashing group elements.
526 for backwards compatibility, is
528 but this is deprecated.
529 (The old format uses a variable length format for hashing,
530 which can leak information through timing.)
531 .SS "Using SLIP interfaces"
532 Though not for the faint of heart, it is possible to get
534 to read and write network packets to a pair of file descriptors using
535 SLIP encapsulation. No fancy header compression of any kind is
538 Two usage modes are supported: a preallocation system, whereby SLIP
539 interfaces are created and passed to the
541 server at startup; and a dynamic system, where the server runs a script
542 to allocate a new SLIP interface when it needs one. It is possible to
543 use a mixture of these two modes, starting
545 with a few preallocated interfaces and having it allocate more
546 dynamically as it needs them.
550 SLIP driver is controlled by the
552 environment variable. The server will not create SLIP tunnels if this
553 variable is not defined. The variable's value is a colon-delimited list
554 of preallocated interfaces, followed optionally by the filename of a
555 script to run to dynamically allocate more interfaces.
557 A static allocation entry has the form
565 is omitted, the same file descriptor is used for input and output.
567 The dynamic allocation script must be named by an absolute or relative
568 pathname, beginning with
572 The server will pass the script an argument, which is the name of the
573 peer for which the interface is being created. The script should
574 allocate a new SLIP interface (presumably by creating a pty pair),
575 configure it appropriately, and write the interface's name to its
576 standard output, followed by a newline. It should then read and write
577 SLIP packets on its stdin and stdout. The script's stdin will be closed
578 when the interface is no longer needed, and the server will attempt to
581 signal (though this may fail if the script runs with higher privileges
584 The output file descriptor should not block unless it really needs to:
587 daemon assumes that it won't, and will get wedged waiting for it to
590 The program's name is
592 all in lower-case. The name of the protocol it uses is `TrIPE', with
593 four capital letters and one lower-case. The name stands for `Trivial
596 .\"--------------------------------------------------------------------------
599 The code hasn't been audited. It may contain security bugs. If you
600 find one, please inform the author
603 .\"--------------------------------------------------------------------------
608 .BR tripe\-admin (5),
611 .IR "The Trivial IP Encryption Protocol" ,
612 .IR "The Wrestlers Protocol" .
614 .\"--------------------------------------------------------------------------
617 Mark Wooding, <mdw@distorted.org.uk>
619 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob