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
57 program is a server which can provide strong IP-level encryption and
58 authentication between two co-operating hosts. The program and its
59 protocol are deliberately very simple, to make analysing them easy and
60 to help build trust rapidly in the system.
64 server manages a number of secure connections to other `peer' hosts.
65 Each daemon is given a private key of its own, and a file of public keys
66 for the peers with which it is meant to communicate. It is responsible
67 for negotiating sets of symmetric keys with its peers, and for
68 encrypting, encapsulating and sending IP packets to its peers, and
69 decrypting, checking and de-encapsulating packets it receives from
72 When the server starts, it creates a Unix-domain socket on which it
73 listens for administration commands. It also logs warnings and
74 diagnostic information to the programs connected to its admin socket.
75 Clients connected to the socket can add new peers, and remove or find
76 out about existing peers. The textual protocol used to give the
78 server admin commands is described in
82 is provided to allow commands to be sent to the server either
83 interactively or by simple scripts.
84 .SS "Command-line arguments"
85 If not given any command-line arguments,
87 will initialize by following these steps:
89 It changes directory to
92 It acquires a UDP socket with an arbitrary kernel-selected port number.
93 It will use this socket to send and receive all communications with its
94 peer servers. The port chosen may be discovered by means of the
97 .BR tripe\-admin (5)).
99 It loads the private key with the tag or type name
101 from the Catacomb-format file
105 ready for extracting the public keys of peers as they're introduced.
106 (The format of these files is described in
108 They are maintained using the program
110 provided with the Catacomb distribution.)
112 It creates and listens to the Unix-domain socket
115 Following this, the server enters its main loop, accepting admin
116 connections and obeying any administrative commands, and communicating
117 with peers. It also treats its standard input and standard output
118 streams as an admin connection, reading commands from standard input and
119 writing responses and diagnostics messages to standard output.
121 Much of this behaviour may be altered by giving
123 suitable command-line options:
126 Writes a brief description of the command-line options available to
127 standard output and exits with status 0.
129 .B "\-v, \-\-version"
132 version number to standard output and exits with status 0.
135 Writes a brief usage summary to standard output and exits with status 0.
138 Dissociates from its terminal and starts running in the background after
139 completing the initialization procedure described above. If running as
142 will not read commands from standard input or write diagnostics to
143 standard output. A better way to start
145 in the background is with
148 .BI "\-d, \-\-directory=" dir
151 the current directory, instead of
153 Give a current directory of
155 if you don't want it to change directory at all.
157 .BI "\-p, \-\-port=" port
158 Use the specified UDP port for all communications with peers, rather
159 than an arbitarary kernel-assigned port.
161 .BI "\-k, \-\-priv\-keyring=" file
162 Reads the private key from
164 rather than the default
167 .BI "\-K, \-\-pub\-keyring=" file
168 Reads public keys from
170 rather than the default
172 This can be the same as the private keyring, but that's not recommended.
174 .BI "\-t, \-\-tag=" tag
175 Uses the private key whose tag or type is
177 rather than the default
180 .BI "\-a, \-\-admin\-socket=" socket
181 Accept admin connections to a Unix-domain socket named
183 rather than the default
186 .BI "\-T, \-\-trace=" trace-opts
187 Allows the enabling or disabling of various internal diagnostics. See
188 below for the list of options.
189 .SS "Setting up a VPN with tripe"
192 server identifies peers by name. While it's
194 for each host to maintain its own naming system for its peers, this is
195 likely to lead to confusion, and it's more sensible to organize a naming
196 system that works everywhere. How you manage this naming is up to you.
197 The only restriction on the format of names is that they must be valid
198 Catacomb key tags, since this is how
200 identifies which public key to use for a particular peer: they may not
201 contain whitespace characters, or a colon
206 Allocating IP addresses for VPNs can get quite complicated. I'll
207 attempt to illustrate with a relatively simple example. Our objective
208 will be to set up a virtual private network between two sites of
210 The two sites are using distinct IP address ranges from the private
211 address space described in RFC1918: site A is using addresses from
212 10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
213 host set up with both an address on the site's private network, and an
214 externally-routable address from the public IP address space. Site A's
217 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
219 and has addresses 10.0.2.1 and 200.0.2.1.
221 This isn't quite complicated enough. Each of
225 needs an extra IP address which we'll use when setting up the
226 point-to-point link. These addresses need to be routable, at least
227 within the virtual private network: unfortunately, you can't just use
228 the same pair everywhere. We'll assign
230 the point-to-point address 192.168.0.1, and
232 the address 192.168.0.2.
236 on both of the gateway hosts. Create the directory
243 the current directory and generate a Diffie-Hellman group:
246 key add \-adh\-param \-LS \-b2048 \-B256 \e
247 \-eforever \-tparam tripe\-dh\-param
251 from the Catacomb distribution for details about the
253 command.) Also generate a private key for
256 key add \-adh \-pparam \-talice \e
257 \-e"now + 1 year" tripe\-dh
259 Extract the group parameters and
263 files, and put the public key in
266 key extract param param
267 key extract \-f\-secret alice alice.pub
268 key \-kkeyring.pub merge alice.pub
276 in some secure way (e.g., in PGP-signed email, or by using SSH), so that
277 you can be sure they've not been altered in transit.
284 the current directory, and import the key material from
289 key \-kkeyring.pub merge alice.pub
291 Generate a private key for
293 and extract the public half, as before:
295 key add \-adh \-pparam \-tbob \e
296 \-e"now + 1 year" tripe\-dh
297 key extract \-f\-secret bob bob.pub
298 key \-kkeyring.pub merge bob.pub
304 using some secure method.
311 key into the public keyring. Now, on each host, run
314 key \-kkeyring.pub fingerprint
316 and check that the hashes match. If the two sites have separate
317 administrators, they should read the hashes to each other over the
318 telephone (assuming that they can recognize each other's voices).
326 tripectl \-slD \-S\-P23169
334 forces the server to use UDP port 23169: use some other number if 23169
335 is inappropriate for your requirements. I chose it by reducing the
337 .RB ` tripe\-port\-number\e0 '
338 modulo 2\*(ss16\*(se.)
345 run this shell script (or one like it):
350 tripectl add bob 200.0.2.1 23169
351 ifname=`tripectl ifname bob`
354 pointopoint 192.168.0.2
356 10.0.2.0 netmask 255.255.255.0 \e
363 to find out about your system's variants of these commands. The
364 versions shown above assume a Linux system.
365 Run a similar script on
373 Congratulations. The two servers will exchange keys and begin sending
374 packets almost immediately. You've set up a virtual private network.
376 The program's name is
378 all in lower-case. The name of the protocol it uses is `TrIPE', with
379 four capital letters and one lower-case. The name stands for `Trivial
382 The code hasn't been audited. It may contain security bugs. If you
383 find one, please inform the author
388 .BR tripe\-admin (5).
390 .IR "The Trivial IP Encryption Protocol" ,
391 .IR "The Wrestlers Protocol" .
393 Mark Wooding, <mdw@nsict.org>
~mdw / tripe / blob