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 8 "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
228 (either a group name or integer gid) after initialization.
230 .BI "\-k, \-\-priv\-keyring=" file
231 Reads the private key from
233 rather than the default
236 .BI "\-K, \-\-pub\-keyring=" file
237 Reads public keys from
239 rather than the default
241 This can be the same as the private keyring, but that's not recommended.
243 .BI "\-t, \-\-tag=" tag
244 Uses the private key whose tag or type is
246 rather than the default
251 .BI "\-a, \-\-admin\-socket=" socket
252 Accept admin connections to a Unix-domain socket named
254 The default socket, if this option isn't specified, is given by the
257 if that's not set either, then a default default of
261 .BI "\-m, \-\-admin\-perms=" mode
262 Permissions (as an octal number) to set on the administration socket. The
263 default is 600, which allows only the socket owner. Setting 660 allows
266 configured through the
268 option to connect to the socket, which may be useful. Allowing world access
271 .BI "\-T, \-\-trace=" trace-opts
272 Allows the enabling or disabling of various internal diagnostics. See
273 below for the list of options.
274 .SS "Key exchange group types"
277 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
278 used for bulk data transfer. Currently
280 can do Diffie\(en\&Hellman in two different kinds of cyclic groups:
285 .I "elliptic curve groups"
289 A Schnorr group is a prime-order subgroup of the multiplicative group of
290 a finite field; this is the usual
294 kind of Diffie\(en\&Hellman. An elliptic curve group is a prime-order
295 subgroup of the abelian group of
297 points on an elliptic curve defined over a finite field
300 Given current public knowledge, elliptic curves can provide similar or
301 better security to systems based on integer discrete log problems,
302 faster, and with less transmitted data. It's a matter of controversy
303 whether this will continue to be the case. The author uses elliptic
306 The server works out which it should be doing based on the key's
308 attribute, which should be either
312 If this attribute isn't present, then the key's type is examined: if
317 is used. If no group is specified,
319 is used as a fallback.
321 To create usual Schnorr-group keys, say something like
323 key add \-adh-param \-LS \-b3072 \-B256 \e
324 \-eforever \-tparam tripe\-param kx-group=dh
326 to construct a parameters key; and create the private keys by
328 key add \-adh \-pparam \-talice \e
329 \-e"now + 1 year" tripe
331 To create elliptic curve keys, say something like
333 key add \-aec\-param \-Cnist-p256 \-eforever \e
334 \-tparam tripe\-param kx-group=ec
336 to construct a parameters key, using your preferred elliptic curve in
341 for details); and create the private keys by
343 key add \-aec \-pparam \-talice \e
344 \-e"now + 1 year" tripe
348 program provides a rather more convenient means for generating and
351 .SS "Using other symmetric algorithms"
352 The default symmetric algorithms
354 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
355 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
356 mode, designed by Bellare, Canetti and Krawczyk). These can all be
357 overridden by setting attributes on your private key, as follows.
360 Names the symmetric encryption scheme to use. The default is
364 Names the hash function to use. The default is
368 Names the message authentication code to use. The name of the MAC may
371 and the desired tag length in bits. The default is
373 at half the underlying hash function's output length.
376 A `mask-generation function', used in the key-exchange. The default is
378 and there's no good reason to change it.
379 .SS "Using SLIP interfaces"
380 Though not for the faint of heart, it is possible to get
382 to read and write network packets to a pair of file descriptors using
383 SLIP encapsulation. No fancy header compression of any kind is
386 Two usage modes are supported: a preallocation system, whereby SLIP
387 interfaces are created and passed to the
389 server at startup; and a dynamic system, where the server runs a script
390 to allocate a new SLIP interface when it needs one. It is possible to
391 use a mixture of these two modes, starting
393 with a few preallocated interfaces and having it allocate more
394 dynamically as it needs them.
398 SLIP driver is controlled by the
400 environment variable. The server will not create SLIP tunnels if this
401 variable is not defined. The variable's value is a colon-delimited list
402 of preallocated interfaces, followed optionally by the filename of a
403 script to run to dynamically allocate more interfaces.
405 A static allocation entry has the form
413 is omitted, the same file descriptor is used for input and output.
415 The dynamic allocation script must be named by an absolute or relative
416 pathname, beginning with
420 The server will pass the script an argument, which is the name of the
421 peer for which the interface is being created. The script should
422 allocate a new SLIP interface (presumably by creating a pty pair),
423 configure it appropriately, and write the interface's name to its
424 standard output, followed by a newline. It should then read and write
425 SLIP packets on its stdin and stdout. The script's stdin will be closed
426 when the interface is no longer needed, and the server will attempt to
429 signal (though this may fail if the script runs with higher privileges
432 The output file descriptor should not block unless it really needs to:
435 daemon assumes that it won't, and will get wedged waiting for it to
438 The program's name is
440 all in lower-case. The name of the protocol it uses is `TrIPE', with
441 four capital letters and one lower-case. The name stands for `Trivial
444 .\"--------------------------------------------------------------------------
447 The code hasn't been audited. It may contain security bugs. If you
448 find one, please inform the author
451 .\"--------------------------------------------------------------------------
456 .BR tripe\-admin (5),
459 .IR "The Trivial IP Encryption Protocol" ,
460 .IR "The Wrestlers Protocol" .
462 .\"--------------------------------------------------------------------------
465 Mark Wooding, <mdw@distorted.org.uk>
467 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob