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 ../defs.man.in \" @@@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
121 from the Catacomb-format file
125 ready for extracting the public keys of peers as they're introduced.
126 (The format of these files is described in
128 They are maintained using the program
130 provided with the Catacomb distribution.)
132 It creates and listens to the Unix-domain socket
135 Following this, the server enters its main loop, accepting admin
136 connections and obeying any administrative commands, and communicating
137 with peers. It also treats its standard input and standard output
138 streams as an admin connection, reading commands from standard input and
139 writing responses and diagnostics messages to standard output. Finally,
140 it will reload keys from its keyring files if it notices that they've
141 changed (it checks inode number and modification time) \- there's no
142 need to send a signal.
144 Much of this behaviour may be altered by giving
146 suitable command-line options:
149 Writes a brief description of the command-line options available to
150 standard output and exits with status 0.
152 .B "\-v, \-\-version"
155 version number to standard output and exits with status 0.
158 Writes a brief usage summary to standard output and exits with status 0.
161 Writes to standard output a list of the configured tunnel drivers, one
162 per line, and exits with status 0. This is intended for the use of the
163 start-up script, so that it can check that it will actually work.
166 Dissociates from its terminal and starts running in the background after
167 completing the initialization procedure described above. If running as
170 will not read commands from standard input or write diagnostics to
171 standard output. A better way to start
173 in the background is with
176 .BI "\-d, \-\-directory=" dir
179 the current directory. The default directory to change to is given by
180 the environment variable
182 if that's not specified, a default default of
184 is used. Give a current directory of
186 if you don't want it to change directory at all.
188 .BI "\-b, \-\-bind-address="addr
189 Bind the UDP socket to IP address
191 rather than the default of
193 This is useful if your main globally-routable IP address is one you want
194 to tunnel through the VPN.
196 .BI "\-p, \-\-port=" port
197 Use the specified UDP port for all communications with peers, rather
198 than an arbitarary kernel-assigned port.
200 .BI "\-n, \-\-tunnel=" tunnel
201 Use the specified tunnel driver for new peers by default.
203 .BI "\-U, \-\-setuid=" user
206 (either a user name or integer uid) after initialization. Also set gid
209 primary group, unless overridden by a
213 .BI "\-G, \-\-setgid=" group
216 (either a group name or integer gid) after initialization.
218 .BI "\-k, \-\-priv\-keyring=" file
219 Reads the private key from
221 rather than the default
224 .BI "\-K, \-\-pub\-keyring=" file
225 Reads public keys from
227 rather than the default
229 This can be the same as the private keyring, but that's not recommended.
231 .BI "\-t, \-\-tag=" tag
232 Uses the private key whose tag or type is
234 rather than the default
237 .BI "\-a, \-\-admin\-socket=" socket
238 Accept admin connections to a Unix-domain socket named
240 The default socket, if this option isn't specified, is given by the
243 if that's not set either, then a default default of
247 .BI "\-T, \-\-trace=" trace-opts
248 Allows the enabling or disabling of various internal diagnostics. See
249 below for the list of options.
250 .SS "Setting up a VPN with tripe"
253 server identifies peers by name. While it's
255 for each host to maintain its own naming system for its peers, this is
256 likely to lead to confusion, and it's more sensible to organize a naming
257 system that works everywhere. How you manage this naming is up to you.
258 The only restriction on the format of names is that they must be valid
259 Catacomb key tags, since this is how
261 identifies which public key to use for a particular peer: they may not
262 contain whitespace characters, or a colon
267 Allocating IP addresses for VPNs can get quite complicated. I'll
268 attempt to illustrate with a relatively simple example. Our objective
269 will be to set up a virtual private network between two sites of
271 The two sites are using distinct IP address ranges from the private
272 address space described in RFC1918: site A is using addresses from
273 10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
274 host set up with both an address on the site's private network, and an
275 externally-routable address from the public IP address space. Site A's
278 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
280 and has addresses 10.0.2.1 and 200.0.2.1.
284 on both of the gateway hosts. Create the directory
291 the current directory and generate a Diffie-Hellman group:
294 key add \-adh\-param \-LS \-b2048 \-B256 \e
295 \-eforever \-tparam tripe\-dh\-param
299 from the Catacomb distribution for details about the
301 command.) Also generate a private key for
304 key add \-adh \-pparam \-talice \e
305 \-e"now + 1 year" tripe\-dh
307 Extract the group parameters and
311 files, and put the public key in
314 key extract param param
315 key extract \-f\-secret alice.pub alice
316 key \-kkeyring.pub merge alice.pub
324 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
325 you can be sure they've not been altered in transit.
332 the current directory, and import the key material from
337 key \-kkeyring.pub merge alice.pub
339 Generate a private key for
341 and extract the public half, as before:
343 key add \-adh \-pparam \-tbob \e
344 \-e"now + 1 year" tripe\-dh
345 key extract \-f\-secret bob.pub bob
346 key \-kkeyring.pub merge bob.pub
352 using some secure method.
359 key into the public keyring. Now, on each host, run
362 key \-kkeyring.pub fingerprint
364 and check that the hashes match. If the two sites have separate
365 administrators, they should read the hashes to each other over the
366 telephone (assuming that they can recognize each other's voices).
386 run this shell script (or one like it):
391 tripectl add bob 200.0.2.1 4070
392 ifname=`tripectl ifname bob`
393 ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1
395 10.0.2.0 netmask 255.255.255.0 \e
402 to find out about your system's variants of these commands. The
403 versions shown above assume a Linux system.
404 Run a similar script on
412 Congratulations. The two servers will exchange keys and begin sending
413 packets almost immediately. You've set up a virtual private network.
414 .SS "Using elliptic curve keys"
417 server can use elliptic curve Diffie-Hellman for key exchange, rather
418 than traditional integer Diffie-Hellman. Given current public
419 knowledge, elliptic curves can provide similar or better security to
420 systems based on integer discrete log problems, faster, and with less
421 transmitted data. It's a matter of controversy whether this will
422 continue to be the case. The author uses elliptic curves.
424 The server works out which it
425 should be doing based on the key type, which is either
427 for standard Diffie-Hellman, or
429 for elliptic curves. To create elliptic curve keys, say something like
431 key add \-aec\-param \-Cnist-p192 \-eforever \e
432 \-tparam tripe\-ec\-param
434 to construct a parameters key, using your preferred elliptic curve in
439 for details); and create the private keys by
441 key add \-aec \-pparam \-talice \e
442 \-e"now + 1 year" tripe\-ec
448 option, and all should be well.
449 .SS "Using other symmetric algorithms"
450 The default symmetric algorithms
452 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
453 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
454 mode, designed by Bellare, Canetti and Krawczyk). These can all be
455 overridden by setting attributes on your private key, as follows.
458 Names the symmetric encryption scheme to use. The default is
462 Names the hash function to use. The default is
466 Names the message authentication code to use. The name of the MAC may
469 and the desired tag length in bits. The default is
471 at half the underlying hash function's output length.
474 A `mask-generation function', used in the key-exchange. The default is
476 and there's no good reason to change it.
477 .SS "Using SLIP interfaces"
478 Though not for the faint of heart, it is possible to get
480 to read and write network packets to a pair of file descriptors using
481 SLIP encapsulation. No fancy header compression of any kind is
484 Two usage modes are supported: a preallocation system, whereby SLIP
485 interfaces are created and passed to the
487 server at startup; and a dynamic system, where the server runs a script
488 to allocate a new SLIP interface when it needs one. It is possible to
489 use a mixture of these two modes, starting
491 with a few preallocated interfaces and having it allocate more
492 dynamically as it needs them.
496 SLIP driver is controlled by the
498 environment variable. The server will not create SLIP tunnels if this
499 variable is not defined. The variable's value is a colon-delimited list
500 of preallocated interfaces, followed optionally by the filename of a
501 script to run to dynamically allocate more interfaces.
503 A static allocation entry has the form
511 is omitted, the same file descriptor is used for input and output.
513 The dynamic allocation script must be named by an absolute or relative
514 pathname, beginning with
518 The server will pass the script an argument, which is the name of the
519 peer for which the interface is being created. The script should
520 allocate a new SLIP interface (presumably by creating a pty pair),
521 configure it appropriately, and write the interface's name to its
522 standard output, followed by a newline. It should then read and write
523 SLIP packets on its stdin and stdout. The script's stdin will be closed
524 when the interface is no longer needed, and the server will attempt to
527 signal (though this may fail if the script runs with higher privileges
530 The output file descriptor should not block unless it really needs to:
533 daemon assumes that it won't, and will get wedged waiting for it to
536 The program's name is
538 all in lower-case. The name of the protocol it uses is `TrIPE', with
539 four capital letters and one lower-case. The name stands for `Trivial
542 .\"--------------------------------------------------------------------------
545 The code hasn't been audited. It may contain security bugs. If you
546 find one, please inform the author
549 .\"--------------------------------------------------------------------------
554 .BR tripe\-admin (5).
556 .IR "The Trivial IP Encryption Protocol" ,
557 .IR "The Wrestlers Protocol" .
559 .\"--------------------------------------------------------------------------
562 Mark Wooding, <mdw@distorted.org.uk>
564 .\"----- That's all, folks --------------------------------------------------