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 .\"--------------------------------------------------------------------------
69 .\"--------------------------------------------------------------------------
74 program is a server which can provide strong IP-level encryption and
75 authentication between co-operating hosts. The program and its protocol
76 are deliberately very simple, to make analysing them easy and to help
77 build trust rapidly in the system.
81 server manages a number of secure connections to other `peer' hosts.
82 Each daemon is given a private key of its own, and a file of public keys
83 for the peers with which it is meant to communicate. It is responsible
84 for negotiating sets of symmetric keys with its peers, and for
85 encrypting, encapsulating and sending IP packets to its peers, and
86 decrypting, checking and de-encapsulating packets it receives from
89 When the server starts, it creates a Unix-domain socket on which it
90 listens for administration commands. It also logs warnings and
91 diagnostic information to the programs connected to its admin socket.
92 Clients connected to the socket can add new peers, and remove or find
93 out about existing peers. The textual protocol used to give the
95 server admin commands is described in
99 is provided to allow commands to be sent to the server either
100 interactively or by simple scripts.
101 .SS "Command-line arguments"
102 If not given any command-line arguments,
104 will initialize by following these steps:
106 It sets the directory named by the
108 environment variable (or
110 if the variable is unset) as the current directory.
112 It acquires a UDP socket with an arbitrary kernel-selected port number.
113 It will use this socket to send and receive all communications with its
114 peer servers. The port chosen may be discovered by means of the
117 .BR tripe\-admin (5)).
119 It loads the private key with the tag or type name
123 for backwards compatibility reasons) from the Catacomb-format file
127 ready for extracting the public keys of peers as they're introduced.
128 (The format of these files is described in
130 They are maintained using the program
132 provided with the Catacomb distribution.)
134 It creates and listens to the Unix-domain socket
137 Following this, the server enters its main loop, accepting admin
138 connections and obeying any administrative commands, and communicating
139 with peers. It also treats its standard input and standard output
140 streams as an admin connection, reading commands from standard input and
141 writing responses and diagnostics messages to standard output. Finally,
142 it will reload keys from its keyring files if it notices that they've
143 changed (it checks inode number and modification time) \- there's no
144 need to send a signal.
146 Much of this behaviour may be altered by giving
148 suitable command-line options:
151 Writes a brief description of the command-line options available to
152 standard output and exits with status 0.
154 .B "\-v, \-\-version"
157 version number to standard output and exits with status 0.
160 Writes a brief usage summary to standard output and exits with status 0.
163 Writes to standard output a list of the configured tunnel drivers, one
164 per line, and exits with status 0. This is intended for the use of the
165 start-up script, so that it can check that it will actually work.
168 Dissociates from its terminal and starts running in the background after
169 completing the initialization procedure described above. If running as
172 will not read commands from standard input or write diagnostics to
173 standard output. A better way to start
175 in the background is with
178 .B "\-F, \-\-foreground"
179 Runs the server in the `foreground'; i.e.,
181 will quit if it sees end-of-file on its standard input. This is
185 .BI "\-d, \-\-directory=" dir
188 the current directory. The default directory to change to is given by
189 the environment variable
191 if that's not specified, a default default of
193 is used. Give a current directory of
195 if you don't want it to change directory at all.
197 .BI "\-b, \-\-bind-address="addr
198 Bind the UDP socket to IP address
200 rather than the default of
202 This is useful if your main globally-routable IP address is one you want
203 to tunnel through the VPN.
205 .BI "\-p, \-\-port=" port
206 Use the specified UDP port for all communications with peers, rather
207 than an arbitarary kernel-assigned port.
209 .BI "\-n, \-\-tunnel=" tunnel
210 Use the specified tunnel driver for new peers by default.
212 .BI "\-U, \-\-setuid=" user
215 (either a user name or integer uid) after initialization. Also set gid
218 primary group, unless overridden by a
220 option. The selected user (and group) will also be the owner of the
221 administration socket.
223 .BI "\-G, \-\-setgid=" group
226 (either a group name or integer gid) after initialization.
228 .BI "\-k, \-\-priv\-keyring=" file
229 Reads the private key from
231 rather than the default
234 .BI "\-K, \-\-pub\-keyring=" file
235 Reads public keys from
237 rather than the default
239 This can be the same as the private keyring, but that's not recommended.
241 .BI "\-t, \-\-tag=" tag
242 Uses the private key whose tag or type is
244 rather than the default
249 .BI "\-a, \-\-admin\-socket=" socket
250 Accept admin connections to a Unix-domain socket named
252 The default socket, if this option isn't specified, is given by the
255 if that's not set either, then a default default of
259 .BI "\-T, \-\-trace=" trace-opts
260 Allows the enabling or disabling of various internal diagnostics. See
261 below for the list of options.
262 .SS "Key exchange group types"
265 server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
266 used for bulk data transfer. Currently
268 can do Diffie\(en\&Hellman in two different kinds of cyclic groups:
273 .I "elliptic curve groups"
277 A Schnorr group is a prime-order subgroup of the multiplicative group of
278 a finite field; this is the usual
282 kind of Diffie\(en\&Hellman. An elliptic curve group is a prime-order
283 subgroup of the abelian group of
285 points on an elliptic curve defined over a finite field
288 Given current public knowledge, elliptic curves can provide similar or
289 better security to systems based on integer discrete log problems,
290 faster, and with less transmitted data. It's a matter of controversy
291 whether this will continue to be the case. The author uses elliptic
294 The server works out which it should be doing based on the key's
296 attribute, which should be either
300 If this attribute isn't present, then the key's type is examined: if
305 is used. If no group is specified,
307 is used as a fallback.
309 To create usual Schnorr-group keys, say something like
311 key add \-adh-param \-LS \-b3072 \-B256 \e
312 \-eforever \-tparam tripe\-param kx-group=dh
314 to construct a parameters key; and create the private keys by
316 key add \-adh \-pparam \-talice \e
317 \-e"now + 1 year" tripe
319 To create elliptic curve keys, say something like
321 key add \-aec\-param \-Cnist-p256 \-eforever \e
322 \-tparam tripe\-param kx-group=ec
324 to construct a parameters key, using your preferred elliptic curve in
329 for details); and create the private keys by
331 key add \-aec \-pparam \-talice \e
332 \-e"now + 1 year" tripe
336 program provides a rather more convenient means for generating and
339 .SS "Using other symmetric algorithms"
340 The default symmetric algorithms
342 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
343 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
344 mode, designed by Bellare, Canetti and Krawczyk). These can all be
345 overridden by setting attributes on your private key, as follows.
348 Names the symmetric encryption scheme to use. The default is
352 Names the hash function to use. The default is
356 Names the message authentication code to use. The name of the MAC may
359 and the desired tag length in bits. The default is
361 at half the underlying hash function's output length.
364 A `mask-generation function', used in the key-exchange. The default is
366 and there's no good reason to change it.
367 .SS "Using SLIP interfaces"
368 Though not for the faint of heart, it is possible to get
370 to read and write network packets to a pair of file descriptors using
371 SLIP encapsulation. No fancy header compression of any kind is
374 Two usage modes are supported: a preallocation system, whereby SLIP
375 interfaces are created and passed to the
377 server at startup; and a dynamic system, where the server runs a script
378 to allocate a new SLIP interface when it needs one. It is possible to
379 use a mixture of these two modes, starting
381 with a few preallocated interfaces and having it allocate more
382 dynamically as it needs them.
386 SLIP driver is controlled by the
388 environment variable. The server will not create SLIP tunnels if this
389 variable is not defined. The variable's value is a colon-delimited list
390 of preallocated interfaces, followed optionally by the filename of a
391 script to run to dynamically allocate more interfaces.
393 A static allocation entry has the form
401 is omitted, the same file descriptor is used for input and output.
403 The dynamic allocation script must be named by an absolute or relative
404 pathname, beginning with
408 The server will pass the script an argument, which is the name of the
409 peer for which the interface is being created. The script should
410 allocate a new SLIP interface (presumably by creating a pty pair),
411 configure it appropriately, and write the interface's name to its
412 standard output, followed by a newline. It should then read and write
413 SLIP packets on its stdin and stdout. The script's stdin will be closed
414 when the interface is no longer needed, and the server will attempt to
417 signal (though this may fail if the script runs with higher privileges
420 The output file descriptor should not block unless it really needs to:
423 daemon assumes that it won't, and will get wedged waiting for it to
426 The program's name is
428 all in lower-case. The name of the protocol it uses is `TrIPE', with
429 four capital letters and one lower-case. The name stands for `Trivial
432 .\"--------------------------------------------------------------------------
435 The code hasn't been audited. It may contain security bugs. If you
436 find one, please inform the author
439 .\"--------------------------------------------------------------------------
444 .BR tripe\-admin (5),
447 .IR "The Trivial IP Encryption Protocol" ,
448 .IR "The Wrestlers Protocol" .
450 .\"--------------------------------------------------------------------------
453 Mark Wooding, <mdw@distorted.org.uk>
455 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob