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 co-operating hosts. The program and its protocol
65 are deliberately very simple, to make analysing them easy and to help
66 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 sets the directory named by the
97 environment variable (or
99 if the variable is unset) as the current directory.
101 It acquires a UDP socket with an arbitrary kernel-selected port number.
102 It will use this socket to send and receive all communications with its
103 peer servers. The port chosen may be discovered by means of the
106 .BR tripe\-admin (5)).
108 It loads the private key with the tag or type name
110 from the Catacomb-format file
114 ready for extracting the public keys of peers as they're introduced.
115 (The format of these files is described in
117 They are maintained using the program
119 provided with the Catacomb distribution.)
121 It creates and listens to the Unix-domain socket
124 Following this, the server enters its main loop, accepting admin
125 connections and obeying any administrative commands, and communicating
126 with peers. It also treats its standard input and standard output
127 streams as an admin connection, reading commands from standard input and
128 writing responses and diagnostics messages to standard output. Finally,
129 it will reload keys from its keyring files if it notices that they've
130 changed (it checks inode number and modification time) \- there's no
131 need to send a signal.
133 Much of this behaviour may be altered by giving
135 suitable command-line options:
138 Writes a brief description of the command-line options available to
139 standard output and exits with status 0.
141 .B "\-v, \-\-version"
144 version number to standard output and exits with status 0.
147 Writes a brief usage summary to standard output and exits with status 0.
150 Dissociates from its terminal and starts running in the background after
151 completing the initialization procedure described above. If running as
154 will not read commands from standard input or write diagnostics to
155 standard output. A better way to start
157 in the background is with
160 .BI "\-d, \-\-directory=" dir
163 the current directory, instead of
165 Give a current directory of
167 if you don't want it to change directory at all.
169 .BI "\-p, \-\-port=" port
170 Use the specified UDP port for all communications with peers, rather
171 than an arbitarary kernel-assigned port.
173 .BI "\-U, \-\-setuid=" user
176 (either a user name or integer uid) after initialization. Also set gid
179 primary group, unless overridden by a
183 .BI "\-G, \-\-setgid=" group
186 (either a group name or integer gid) after initialization.
188 .BI "\-k, \-\-priv\-keyring=" file
189 Reads the private key from
191 rather than the default
194 .BI "\-K, \-\-pub\-keyring=" file
195 Reads public keys from
197 rather than the default
199 This can be the same as the private keyring, but that's not recommended.
201 .BI "\-t, \-\-tag=" tag
202 Uses the private key whose tag or type is
204 rather than the default
207 .BI "\-a, \-\-admin\-socket=" socket
208 Accept admin connections to a Unix-domain socket named
210 rather than the default
213 .BI "\-T, \-\-trace=" trace-opts
214 Allows the enabling or disabling of various internal diagnostics. See
215 below for the list of options.
216 .SS "Setting up a VPN with tripe"
219 server identifies peers by name. While it's
221 for each host to maintain its own naming system for its peers, this is
222 likely to lead to confusion, and it's more sensible to organize a naming
223 system that works everywhere. How you manage this naming is up to you.
224 The only restriction on the format of names is that they must be valid
225 Catacomb key tags, since this is how
227 identifies which public key to use for a particular peer: they may not
228 contain whitespace characters, or a colon
233 Allocating IP addresses for VPNs can get quite complicated. I'll
234 attempt to illustrate with a relatively simple example. Our objective
235 will be to set up a virtual private network between two sites of
237 The two sites are using distinct IP address ranges from the private
238 address space described in RFC1918: site A is using addresses from
239 10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
240 host set up with both an address on the site's private network, and an
241 externally-routable address from the public IP address space. Site A's
244 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
246 and has addresses 10.0.2.1 and 200.0.2.1.
248 This isn't quite complicated enough. Each of
252 needs an extra IP address which we'll use when setting up the
253 point-to-point link. These addresses need to be routable, at least
254 within the virtual private network: unfortunately, you can't just use
255 the same pair everywhere. We'll assign
257 the point-to-point address 192.168.0.1, and
259 the address 192.168.0.2.
263 on both of the gateway hosts. Create the directory
270 the current directory and generate a Diffie-Hellman group:
273 key add \-adh\-param \-LS \-b2048 \-B256 \e
274 \-eforever \-tparam tripe\-dh\-param
278 from the Catacomb distribution for details about the
280 command.) Also generate a private key for
283 key add \-adh \-pparam \-talice \e
284 \-e"now + 1 year" tripe\-dh
286 Extract the group parameters and
290 files, and put the public key in
293 key extract param param
294 key extract \-f\-secret alice.pub alice
295 key \-kkeyring.pub merge alice.pub
303 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
304 you can be sure they've not been altered in transit.
311 the current directory, and import the key material from
316 key \-kkeyring.pub merge alice.pub
318 Generate a private key for
320 and extract the public half, as before:
322 key add \-adh \-pparam \-tbob \e
323 \-e"now + 1 year" tripe\-dh
324 key extract \-f\-secret bob.pub bob
325 key \-kkeyring.pub merge bob.pub
331 using some secure method.
338 key into the public keyring. Now, on each host, run
341 key \-kkeyring.pub fingerprint
343 and check that the hashes match. If the two sites have separate
344 administrators, they should read the hashes to each other over the
345 telephone (assuming that they can recognize each other's voices).
353 tripectl \-slD \-S\-P23169
361 forces the server to use UDP port 23169: use some other number if 23169
362 is inappropriate for your requirements. I chose it by reducing the
364 .RB ` tripe\-port\-number\e0 '
365 modulo 2\*(ss16\*(se.)
372 run this shell script (or one like it):
377 tripectl add bob 200.0.2.1 23169
378 ifname=`tripectl ifname bob`
381 pointopoint 192.168.0.2
383 10.0.2.0 netmask 255.255.255.0 \e
390 to find out about your system's variants of these commands. The
391 versions shown above assume a Linux system.
392 Run a similar script on
400 Congratulations. The two servers will exchange keys and begin sending
401 packets almost immediately. You've set up a virtual private network.
403 The program's name is
405 all in lower-case. The name of the protocol it uses is `TrIPE', with
406 four capital letters and one lower-case. The name stands for `Trivial
409 The code hasn't been audited. It may contain security bugs. If you
410 find one, please inform the author
415 .BR tripe\-admin (5).
417 .IR "The Trivial IP Encryption Protocol" ,
418 .IR "The Wrestlers Protocol" .
420 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob