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
63 program is a server which can provide strong IP-level encryption and
64 authentication between two co-operating hosts. The program and its
65 protocol are deliberately very simple, to make analysing them easy and
66 to help build trust rapidly in the system.
70 server manages a number of secure connections to other `peer' hosts.
71 Each daemon is given a private key of its own, and a file of public keys
72 for the peers with which it is meant to communicate. It is responsible
73 for negotiating sets of symmetric keys with its peers, and for
74 encrypting, encapsulating and sending IP packets to its peers, and
75 decrypting, checking and de-encapsulating packets it receives from
78 When the server starts, it creates a Unix-domain socket on which it
79 listens for administration commands. It also logs warnings and
80 diagnostic information to the programs connected to its admin socket.
81 Clients connected to the socket can add new peers, and remove or find
82 out about existing peers. The textual protocol used to give the
84 server admin commands is described in
88 is provided to allow commands to be sent to the server either
89 interactively or by simple scripts.
90 .SS "Command-line arguments"
91 If not given any command-line arguments,
93 will initialize by following these steps:
95 It changes directory to
98 It acquires a UDP socket with an arbitrary kernel-selected port number.
99 It will use this socket to send and receive all communications with its
100 peer servers. The port chosen may be discovered by means of the
103 .BR tripe\-admin (5)).
105 It loads the private key with the tag or type name
107 from the Catacomb-format file
111 ready for extracting the public keys of peers as they're introduced.
112 (The format of these files is described in
114 They are maintained using the program
116 provided with the Catacomb distribution.)
118 It creates and listens to the Unix-domain socket
121 Following this, the server enters its main loop, accepting admin
122 connections and obeying any administrative commands, and communicating
123 with peers. It also treats its standard input and standard output
124 streams as an admin connection, reading commands from standard input and
125 writing responses and diagnostics messages to standard output. Finally,
126 it will reload keys from its keyring files if it notices that they've
127 changed (it checks inode number and modification time) \- there's no
128 need to send a signal.
130 Much of this behaviour may be altered by giving
132 suitable command-line options:
135 Writes a brief description of the command-line options available to
136 standard output and exits with status 0.
138 .B "\-v, \-\-version"
141 version number to standard output and exits with status 0.
144 Writes a brief usage summary to standard output and exits with status 0.
147 Dissociates from its terminal and starts running in the background after
148 completing the initialization procedure described above. If running as
151 will not read commands from standard input or write diagnostics to
152 standard output. A better way to start
154 in the background is with
157 .BI "\-d, \-\-directory=" dir
160 the current directory, instead of
162 Give a current directory of
164 if you don't want it to change directory at all.
166 .BI "\-p, \-\-port=" port
167 Use the specified UDP port for all communications with peers, rather
168 than an arbitarary kernel-assigned port.
170 .BI "\-U, \-\-setuid=" user
173 (either a user name or integer uid) after initialization. Also set gid
176 primary group, unless overridden by a
180 .BI "\-G, \-\-setgid=" group
183 (either a group name or integer gid) after initialization.
185 .BI "\-k, \-\-priv\-keyring=" file
186 Reads the private key from
188 rather than the default
191 .BI "\-K, \-\-pub\-keyring=" file
192 Reads public keys from
194 rather than the default
196 This can be the same as the private keyring, but that's not recommended.
198 .BI "\-t, \-\-tag=" tag
199 Uses the private key whose tag or type is
201 rather than the default
204 .BI "\-a, \-\-admin\-socket=" socket
205 Accept admin connections to a Unix-domain socket named
207 rather than the default
210 .BI "\-T, \-\-trace=" trace-opts
211 Allows the enabling or disabling of various internal diagnostics. See
212 below for the list of options.
213 .SS "Setting up a VPN with tripe"
216 server identifies peers by name. While it's
218 for each host to maintain its own naming system for its peers, this is
219 likely to lead to confusion, and it's more sensible to organize a naming
220 system that works everywhere. How you manage this naming is up to you.
221 The only restriction on the format of names is that they must be valid
222 Catacomb key tags, since this is how
224 identifies which public key to use for a particular peer: they may not
225 contain whitespace characters, or a colon
230 Allocating IP addresses for VPNs can get quite complicated. I'll
231 attempt to illustrate with a relatively simple example. Our objective
232 will be to set up a virtual private network between two sites of
234 The two sites are using distinct IP address ranges from the private
235 address space described in RFC1918: site A is using addresses from
236 10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
237 host set up with both an address on the site's private network, and an
238 externally-routable address from the public IP address space. Site A's
241 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
243 and has addresses 10.0.2.1 and 200.0.2.1.
245 This isn't quite complicated enough. Each of
249 needs an extra IP address which we'll use when setting up the
250 point-to-point link. These addresses need to be routable, at least
251 within the virtual private network: unfortunately, you can't just use
252 the same pair everywhere. We'll assign
254 the point-to-point address 192.168.0.1, and
256 the address 192.168.0.2.
260 on both of the gateway hosts. Create the directory
267 the current directory and generate a Diffie-Hellman group:
270 key add \-adh\-param \-LS \-b2048 \-B256 \e
271 \-eforever \-tparam tripe\-dh\-param
275 from the Catacomb distribution for details about the
277 command.) Also generate a private key for
280 key add \-adh \-pparam \-talice \e
281 \-e"now + 1 year" tripe\-dh
283 Extract the group parameters and
287 files, and put the public key in
290 key extract param param
291 key extract \-f\-secret alice.pub alice
292 key \-kkeyring.pub merge alice.pub
300 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
301 you can be sure they've not been altered in transit.
308 the current directory, and import the key material from
313 key \-kkeyring.pub merge alice.pub
315 Generate a private key for
317 and extract the public half, as before:
319 key add \-adh \-pparam \-tbob \e
320 \-e"now + 1 year" tripe\-dh
321 key extract \-f\-secret bob.pub bob
322 key \-kkeyring.pub merge bob.pub
328 using some secure method.
335 key into the public keyring. Now, on each host, run
338 key \-kkeyring.pub fingerprint
340 and check that the hashes match. If the two sites have separate
341 administrators, they should read the hashes to each other over the
342 telephone (assuming that they can recognize each other's voices).
350 tripectl \-slD \-S\-P23169
358 forces the server to use UDP port 23169: use some other number if 23169
359 is inappropriate for your requirements. I chose it by reducing the
361 .RB ` tripe\-port\-number\e0 '
362 modulo 2\*(ss16\*(se.)
369 run this shell script (or one like it):
374 tripectl add bob 200.0.2.1 23169
375 ifname=`tripectl ifname bob`
378 pointopoint 192.168.0.2
380 10.0.2.0 netmask 255.255.255.0 \e
387 to find out about your system's variants of these commands. The
388 versions shown above assume a Linux system.
389 Run a similar script on
397 Congratulations. The two servers will exchange keys and begin sending
398 packets almost immediately. You've set up a virtual private network.
400 The program's name is
402 all in lower-case. The name of the protocol it uses is `TrIPE', with
403 four capital letters and one lower-case. The name stands for `Trivial
406 The code hasn't been audited. It may contain security bugs. If you
407 find one, please inform the author
412 .BR tripe\-admin (5).
414 .IR "The Trivial IP Encryption Protocol" ,
415 .IR "The Wrestlers Protocol" .
417 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob