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. Currently
284 can do Diffie\(en\&Hellman in two different kinds of cyclic groups:
289 .I "elliptic curve groups"
293 A Schnorr group is a prime-order subgroup of the multiplicative group of
294 a finite field; this is the usual
298 kind of Diffie\(en\&Hellman. An elliptic curve group is a prime-order
299 subgroup of the abelian group of
301 points on an elliptic curve defined over a finite field
304 Given current public knowledge, elliptic curves can provide similar or
305 better security to systems based on integer discrete log problems,
306 faster, and with less transmitted data. It's a matter of controversy
307 whether this will continue to be the case. The author uses elliptic
310 The server works out which it should be doing based on the key's
312 attribute, which should be either
316 If this attribute isn't present, then the key's type is examined: if
321 is used. If no group is specified,
323 is used as a fallback.
325 To create usual Schnorr-group keys, say something like
327 key add \-adh-param \-LS \-b3072 \-B256 \e
328 \-eforever \-tparam tripe\-param kx-group=dh
330 to construct a parameters key; and create the private keys by
332 key add \-adh \-pparam \-talice \e
333 \-e"now + 1 year" tripe
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
352 program provides a rather more convenient means for generating and
355 .SS "Using other symmetric algorithms"
356 The default symmetric algorithms
358 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
359 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
360 mode, designed by Bellare, Canetti and Krawczyk). These can all be
361 overridden by setting attributes on your private key, as follows.
364 Names the bulk-crypto transform to use. See below.
367 Names a block cipher, used by some bulk-crypto transforms (e.g.,
369 The default is to use the block cipher underlying the chosen
374 Names the symmetric encryption scheme to use. The default is
378 Names the hash function to use. The default is
382 Names the message authentication code to use. The name of the MAC may
385 and the desired tag length in bits. The default is
387 at half the underlying hash function's output length.
390 A `mask-generation function', used in the key-exchange. The default is
392 and there's no good reason to change it.
394 The available bulk-crypto transforms are as follows.
397 Originally this was the only transform available. It's a standard
398 generic composition of a CPA-secure symmetric encryption scheme with a
399 MAC; initialization vectors for symmetric encryption are chosen at
400 random and included explicitly in the cryptogram.
403 A newer `implicit-IV' transform. Rather than having an explicit random
404 IV, the IV is computed from the sequence number using a block cipher.
405 This has two advantages over the
407 transform. Firstly, it adds less overhead to encrypted messages
408 (because the IV no longer needs to be sent explicitly). Secondly, and
409 more significantly, the transform is entirely deterministic, so (a) it
410 doesn't need the (possibly slow) random number generator, and (b) it
411 closes a kleptographic channel, over which a compromised implementation
412 could leak secret information to a third party.
413 .SS "Using SLIP interfaces"
414 Though not for the faint of heart, it is possible to get
416 to read and write network packets to a pair of file descriptors using
417 SLIP encapsulation. No fancy header compression of any kind is
420 Two usage modes are supported: a preallocation system, whereby SLIP
421 interfaces are created and passed to the
423 server at startup; and a dynamic system, where the server runs a script
424 to allocate a new SLIP interface when it needs one. It is possible to
425 use a mixture of these two modes, starting
427 with a few preallocated interfaces and having it allocate more
428 dynamically as it needs them.
432 SLIP driver is controlled by the
434 environment variable. The server will not create SLIP tunnels if this
435 variable is not defined. The variable's value is a colon-delimited list
436 of preallocated interfaces, followed optionally by the filename of a
437 script to run to dynamically allocate more interfaces.
439 A static allocation entry has the form
447 is omitted, the same file descriptor is used for input and output.
449 The dynamic allocation script must be named by an absolute or relative
450 pathname, beginning with
454 The server will pass the script an argument, which is the name of the
455 peer for which the interface is being created. The script should
456 allocate a new SLIP interface (presumably by creating a pty pair),
457 configure it appropriately, and write the interface's name to its
458 standard output, followed by a newline. It should then read and write
459 SLIP packets on its stdin and stdout. The script's stdin will be closed
460 when the interface is no longer needed, and the server will attempt to
463 signal (though this may fail if the script runs with higher privileges
466 The output file descriptor should not block unless it really needs to:
469 daemon assumes that it won't, and will get wedged waiting for it to
472 The program's name is
474 all in lower-case. The name of the protocol it uses is `TrIPE', with
475 four capital letters and one lower-case. The name stands for `Trivial
478 .\"--------------------------------------------------------------------------
481 The code hasn't been audited. It may contain security bugs. If you
482 find one, please inform the author
485 .\"--------------------------------------------------------------------------
490 .BR tripe\-admin (5),
493 .IR "The Trivial IP Encryption Protocol" ,
494 .IR "The Wrestlers Protocol" .
496 .\"--------------------------------------------------------------------------
499 Mark Wooding, <mdw@distorted.org.uk>
501 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob