5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
32 .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
34 tripe \- a simple VPN daemon
65 program is a server which can provide strong IP-level encryption and
66 authentication between co-operating hosts. The program and its protocol
67 are deliberately very simple, to make analysing them easy and to help
68 build trust rapidly in the system.
72 server manages a number of secure connections to other `peer' hosts.
73 Each daemon is given a private key of its own, and a file of public keys
74 for the peers with which it is meant to communicate. It is responsible
75 for negotiating sets of symmetric keys with its peers, and for
76 encrypting, encapsulating and sending IP packets to its peers, and
77 decrypting, checking and de-encapsulating packets it receives from
80 When the server starts, it creates a Unix-domain socket on which it
81 listens for administration commands. It also logs warnings and
82 diagnostic information to the programs connected to its admin socket.
83 Clients connected to the socket can add new peers, and remove or find
84 out about existing peers. The textual protocol used to give the
86 server admin commands is described in
90 is provided to allow commands to be sent to the server either
91 interactively or by simple scripts.
92 .SS "Command-line arguments"
93 If not given any command-line arguments,
95 will initialize by following these steps:
97 It sets the directory named by the
99 environment variable (or
101 if the variable is unset) as the current directory.
103 It acquires a UDP socket with an arbitrary kernel-selected port number.
104 It will use this socket to send and receive all communications with its
105 peer servers. The port chosen may be discovered by means of the
108 .BR tripe\-admin (5)).
110 It loads the private key with the tag or type name
112 from the Catacomb-format file
116 ready for extracting the public keys of peers as they're introduced.
117 (The format of these files is described in
119 They are maintained using the program
121 provided with the Catacomb distribution.)
123 It creates and listens to the Unix-domain socket
126 Following this, the server enters its main loop, accepting admin
127 connections and obeying any administrative commands, and communicating
128 with peers. It also treats its standard input and standard output
129 streams as an admin connection, reading commands from standard input and
130 writing responses and diagnostics messages to standard output. Finally,
131 it will reload keys from its keyring files if it notices that they've
132 changed (it checks inode number and modification time) \- there's no
133 need to send a signal.
135 Much of this behaviour may be altered by giving
137 suitable command-line options:
140 Writes a brief description of the command-line options available to
141 standard output and exits with status 0.
143 .B "\-v, \-\-version"
146 version number to standard output and exits with status 0.
149 Writes a brief usage summary to standard output and exits with status 0.
152 Writes a string to standard output describing the configured tunnelling
153 method and exits with status 0. This is intended for the use of the
154 start-up script, so that it can check that it will actually work.
157 Dissociates from its terminal and starts running in the background after
158 completing the initialization procedure described above. If running as
161 will not read commands from standard input or write diagnostics to
162 standard output. A better way to start
164 in the background is with
167 .BI "\-d, \-\-directory=" dir
170 the current directory, instead of
172 Give a current directory of
174 if you don't want it to change directory at all.
176 .BI "\-b, \-\-bind-address="addr
177 Bind the UDP socket to IP address
179 rather than the default of
181 This is useful if your main globally-routable IP address is one you want
182 to tunnel through the VPN.
184 .BI "\-p, \-\-port=" port
185 Use the specified UDP port for all communications with peers, rather
186 than an arbitarary kernel-assigned port.
188 .BI "\-U, \-\-setuid=" user
191 (either a user name or integer uid) after initialization. Also set gid
194 primary group, unless overridden by a
198 .BI "\-G, \-\-setgid=" group
201 (either a group name or integer gid) after initialization.
203 .BI "\-k, \-\-priv\-keyring=" file
204 Reads the private key from
206 rather than the default
209 .BI "\-K, \-\-pub\-keyring=" file
210 Reads public keys from
212 rather than the default
214 This can be the same as the private keyring, but that's not recommended.
216 .BI "\-t, \-\-tag=" tag
217 Uses the private key whose tag or type is
219 rather than the default
222 .BI "\-a, \-\-admin\-socket=" socket
223 Accept admin connections to a Unix-domain socket named
225 rather than the default
228 .BI "\-T, \-\-trace=" trace-opts
229 Allows the enabling or disabling of various internal diagnostics. See
230 below for the list of options.
231 .SS "Setting up a VPN with tripe"
234 server identifies peers by name. While it's
236 for each host to maintain its own naming system for its peers, this is
237 likely to lead to confusion, and it's more sensible to organize a naming
238 system that works everywhere. How you manage this naming is up to you.
239 The only restriction on the format of names is that they must be valid
240 Catacomb key tags, since this is how
242 identifies which public key to use for a particular peer: they may not
243 contain whitespace characters, or a colon
248 Allocating IP addresses for VPNs can get quite complicated. I'll
249 attempt to illustrate with a relatively simple example. Our objective
250 will be to set up a virtual private network between two sites of
252 The two sites are using distinct IP address ranges from the private
253 address space described in RFC1918: site A is using addresses from
254 10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
255 host set up with both an address on the site's private network, and an
256 externally-routable address from the public IP address space. Site A's
259 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
261 and has addresses 10.0.2.1 and 200.0.2.1.
263 This isn't quite complicated enough. Each of
267 needs an extra IP address which we'll use when setting up the
268 point-to-point link. These addresses need to be routable, at least
269 within the virtual private network: unfortunately, you can't just use
270 the same pair everywhere. We'll assign
272 the point-to-point address 192.168.0.1, and
274 the address 192.168.0.2.
278 on both of the gateway hosts. Create the directory
285 the current directory and generate a Diffie-Hellman group:
288 key add \-adh\-param \-LS \-b2048 \-B256 \e
289 \-eforever \-tparam tripe\-dh\-param
293 from the Catacomb distribution for details about the
295 command.) Also generate a private key for
298 key add \-adh \-pparam \-talice \e
299 \-e"now + 1 year" tripe\-dh
301 Extract the group parameters and
305 files, and put the public key in
308 key extract param param
309 key extract \-f\-secret alice.pub alice
310 key \-kkeyring.pub merge alice.pub
318 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
319 you can be sure they've not been altered in transit.
326 the current directory, and import the key material from
331 key \-kkeyring.pub merge alice.pub
333 Generate a private key for
335 and extract the public half, as before:
337 key add \-adh \-pparam \-tbob \e
338 \-e"now + 1 year" tripe\-dh
339 key extract \-f\-secret bob.pub bob
340 key \-kkeyring.pub merge bob.pub
346 using some secure method.
353 key into the public keyring. Now, on each host, run
356 key \-kkeyring.pub fingerprint
358 and check that the hashes match. If the two sites have separate
359 administrators, they should read the hashes to each other over the
360 telephone (assuming that they can recognize each other's voices).
368 tripectl \-slD \-S\-P23169
376 forces the server to use UDP port 23169: use some other number if 23169
377 is inappropriate for your requirements. I chose it by reducing the
379 .RB ` tripe\-port\-number\e0 '
380 modulo 2\*(ss16\*(se.)
387 run this shell script (or one like it):
392 tripectl add bob 200.0.2.1 23169
393 ifname=`tripectl ifname bob`
396 pointopoint 192.168.0.2
398 10.0.2.0 netmask 255.255.255.0 \e
405 to find out about your system's variants of these commands. The
406 versions shown above assume a Linux system.
407 Run a similar script on
415 Congratulations. The two servers will exchange keys and begin sending
416 packets almost immediately. You've set up a virtual private network.
417 .SS "Using elliptic curve keys"
420 server can use elliptic curve Diffie-Hellman for key exchange, rather
421 than traditional integer Diffie-Hellman. Given current public
422 knowledge, elliptic curves can provide similar or better security to
423 systems based on integer discrete log problems, faster, and with less
424 transmitted data. It's a matter of controversy whether this will
425 continue to be the case. The author uses elliptic curves.
427 The server works out which it
428 should be doing based on the key type, which is either
430 for standard Diffie-Hellman, or
432 for elliptic curves. To create elliptic curve keys, say something like
434 key add \-aec\-param \-Cnist-p192 \-eforever \e
435 \-tparam tripe\-ec\-param
437 to construct a parameters key, using your preferred elliptic curve in
442 for details); and create the private keys by
444 key add \-aec \-pparam \-talice \e
445 \-e"now + 1 year" tripe\-ec
451 option, and all should be well.
452 .SS "Using other symmetric algorithms"
453 The default symmetric algorithms
455 uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
456 (by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
457 mode, designed by Bellare, Canetti and Krawczyk). These can all be
458 overridden by setting attributes on your private key, as follows.
461 Names the symmetric encryption scheme to use. The default is
465 Names the hash function to use. The default is
469 Names the message authentication code to use. The name of the MAC may
472 and the desired tag length in bits. The default is
474 at half the underlying hash function's output length.
477 A `mask-generation function', used in the key-exchange. The default is
479 and there's no good reason to change it.
481 The program's name is
483 all in lower-case. The name of the protocol it uses is `TrIPE', with
484 four capital letters and one lower-case. The name stands for `Trivial
487 The code hasn't been audited. It may contain security bugs. If you
488 find one, please inform the author
493 .BR tripe\-admin (5).
495 .IR "The Trivial IP Encryption Protocol" ,
496 .IR "The Wrestlers Protocol" .
498 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob