chiark / gitweb /
Rearrange so as not to include Linux headers unless we need to.
[tripe] / doc / tripe.8
CommitLineData
74eb47db 1.\" -*-nroff-*-
2.\".
3.de hP
4.IP
5\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
6..
7.de VS
8.sp 1
9.RS
10.nf
11.ft B
12..
13.de VE
14.ft R
15.fi
16.RE
17.sp 1
18..
19.ie t \{\
20. ds o \(bu
21. ds ss \s8\u
22. ds se \d\s0
23. if \n(.g \{\
24. fam P
25. \}
26.\}
27.el \{\
28. ds o o
29. ds ss ^
d6623498 30. ds se
74eb47db 31.\}
32.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
33.SH "NAME"
34tripe \- a simple VPN daemon
35.SH "SYNOPSIS"
36.B tripe
37.RB [ \-D ]
38.RB [ \-p
39.IR port ]
40.RB [ \-T
41.IR trace-opts ]
42.RB [ \-d
43.IR dir ]
44.RB [ \-a
45.IR socket ]
46.br
47
48.RB [ \-k
49.IR priv-keyring ]
50.RB [ \-K
51.IR pub-keyring ]
52.RB [ \-t
53.IR key-tag ]
54.SH "DESCRIPTION"
55The
56.B tripe
57program is a server which can provide strong IP-level encryption and
58authentication between two co-operating hosts. The program and its
59protocol are deliberately very simple, to make analysing them easy and
60to help build trust rapidly in the system.
61.SS "Overview"
62The
63.B tripe
64server manages a number of secure connections to other `peer' hosts.
65Each daemon is given a private key of its own, and a file of public keys
66for the peers with which it is meant to communicate. It is responsible
67for negotiating sets of symmetric keys with its peers, and for
68encrypting, encapsulating and sending IP packets to its peers, and
69decrypting, checking and de-encapsulating packets it receives from
70them.
71.PP
72When the server starts, it creates a Unix-domain socket on which it
73listens for administration commands. It also logs warnings and
74diagnostic information to the programs connected to its admin socket.
75Clients connected to the socket can add new peers, and remove or find
76out about existing peers. The textual protocol used to give the
77.B tripe
78server admin commands is described in
79.BR tripe\-admin (5).
80A client program
81.BR tripectl (1)
82is provided to allow commands to be sent to the server either
83interactively or by simple scripts.
84.SS "Command-line arguments"
85If not given any command-line arguments,
86.B tripe
87will initialize by following these steps:
88.hP \*o
89It changes directory to
90.BR /var/lib/tripe .
91.hP \*o
92It acquires a UDP socket with an arbitrary kernel-selected port number.
93It will use this socket to send and receive all communications with its
94peer servers. The port chosen may be discovered by means of the
95.B PORT
96admin command (see
97.BR tripe\-admin (5)).
98.hP \*o
99It loads the private key with the tag or type name
100.B tripe\-dh
101from the Catacomb-format file
102.BR keyring ,
103and loads the file
104.B keyring.pub
105ready for extracting the public keys of peers as they're introduced.
106(The format of these files is described in
107.BR keyring (5).
108They are maintained using the program
109.BR key (1)
110provided with the Catacomb distribution.)
111.hP \*o
112It creates and listens to the Unix-domain socket
113.BR tripesock .
114.PP
115Following this, the server enters its main loop, accepting admin
116connections and obeying any administrative commands, and communicating
117with peers. It also treats its standard input and standard output
118streams as an admin connection, reading commands from standard input and
119writing responses and diagnostics messages to standard output.
120.PP
121Much of this behaviour may be altered by giving
122.B tripe
123suitable command-line options:
124.TP
125.B "\-h, \-\-help"
126Writes a brief description of the command-line options available to
127standard output and exits with status 0.
128.TP
129.B "\-v, \-\-version"
130Writes
131.BR tripe 's
132version number to standard output and exits with status 0.
133.TP
134.B "\-u, \-\-usage"
135Writes a brief usage summary to standard output and exits with status 0.
136.TP
137.B "\-D, \-\-daemon"
138Dissociates from its terminal and starts running in the background after
139completing the initialization procedure described above. If running as
140a daemon,
141.B tripe
142will not read commands from standard input or write diagnostics to
143standard output. A better way to start
144.B tripe
145in the background is with
146.BR tripectl (1).
147.TP
148.BI "\-d, \-\-directory=" dir
149Makes
150.I dir
151the current directory, instead of
152.BR /var/lib/tripe .
153Give a current directory of
154.B .
155if you don't want it to change directory at all.
156.TP
157.BI "\-p, \-\-port=" port
158Use the specified UDP port for all communications with peers, rather
159than an arbitarary kernel-assigned port.
160.TP
161.BI "\-k, \-\-priv\-keyring=" file
162Reads the private key from
163.I file
164rather than the default
165.BR keyring .
166.TP
167.BI "\-K, \-\-pub\-keyring=" file
168Reads public keys from
169.I file
170rather than the default
171.BR keyring.pub .
172This can be the same as the private keyring, but that's not recommended.
173.TP
174.BI "\-t, \-\-tag=" tag
175Uses the private key whose tag or type is
176.I tag
177rather than the default
178.BR tripe\-dh .
179.TP
180.BI "\-a, \-\-admin\-socket=" socket
181Accept admin connections to a Unix-domain socket named
182.I socket
183rather than the default
184.BR tripesock .
185.TP
186.BI "\-T, \-\-trace=" trace-opts
187Allows the enabling or disabling of various internal diagnostics. See
188below for the list of options.
d6623498 189.SS "Setting up a VPN with tripe"
190The
191.B tripe
192server identifies peers by name. While it's
193.I possible
194for each host to maintain its own naming system for its peers, this is
195likely to lead to confusion, and it's more sensible to organize a naming
196system that works everywhere. How you manage this naming is up to you.
197The only restriction on the format of names is that they must be valid
198Catacomb key tags, since this is how
199.B tripe
200identifies which public key to use for a particular peer: they may not
201contain whitespace characters, or a colon
202.RB ` : '
203or dot
204.RB ` . ',
205.PP
206Allocating IP addresses for VPNs can get quite complicated. I'll
207attempt to illustrate with a relatively simple example. Our objective
208will be to set up a virtual private network between two sites of
209.BR example.com .
210The two sites are using distinct IP address ranges from the private
211address space described in RFC1918: site A is using addresses from
21210.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
213host set up with both an address on the site's private network, and an
214externally-routable address from the public IP address space. Site A's
215gateway machine,
216.BR alice ,
217has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
218.B bob
219and has addresses 10.0.2.1 and 200.0.2.1.
220.PP
221This isn't quite complicated enough. Each of
222.B alice
223and
224.B bob
225needs an extra IP address which we'll use when setting up the
226point-to-point link. These addresses need to be routable, at least
227within the virtual private network: unfortunately, you can't just use
228the same pair everywhere. We'll assign
229.B alice
230the point-to-point address 192.168.0.1, and
231.B bob
232the address 192.168.0.2.
233.hP 1.
234Install
235.B tripe
236on both of the gateway hosts. Create the directory
237.BR /var/lib/tripe .
238.hP 2.
239On
240.BR alice ,
241make
242.B /var/lib/tripe
243the current directory and generate a Diffie-Hellman group:
244.RS
74eb47db 245.VS
246key add \-adh\-param \-LS \-b2048 \-B256 \e
247 \-eforever \-tparam tripe\-dh\-param
248.VE
d6623498 249(See
250.BR key (1)
251from the Catacomb distribution for details about the
252.B key
253command.) Also generate a private key for
254.BR alice :
255.VS
256key add \-adh \-pparam \-talice \e
257 \-e"now + 1 year" tripe\-dh
258.VE
259Extract the group parameters and
260.BR alice 's
261public key to
262.I separate
263files, and put the public key in
264.BR keyring.pub :
74eb47db 265.VS
266key extract param param
37075862 267key extract \-f\-secret alice.pub alice
d6623498 268key \-kkeyring.pub merge alice.pub
74eb47db 269.VE
d6623498 270Send the files
271.B param
272and
273.B alice.pub
274to
275.B bob
276in some secure way (e.g., in PGP-signed email, or by using SSH), so that
277you can be sure they've not been altered in transit.
278.RE
279.hP 3.
280On
281.B bob
282now, make
283.B /var/lib/tripe
284the current directory, and import the key material from
285.BR alice :
286.RS
74eb47db 287.VS
288key merge param
d6623498 289key \-kkeyring.pub merge alice.pub
74eb47db 290.VE
d6623498 291Generate a private key for
292.B bob
293and extract the public half, as before:
74eb47db 294.VS
d6623498 295key add \-adh \-pparam \-tbob \e
296 \-e"now + 1 year" tripe\-dh
297key extract \-f\-secret bob bob.pub
298key \-kkeyring.pub merge bob.pub
74eb47db 299.VE
d6623498 300and send
301.B bob.pub
302back to
303.B alice
304using some secure method.
305.RE
306.hP 4
307On
308.BR alice ,
309merge
310.B bob 's
311key into the public keyring. Now, on each host, run
312.RS
313.VS
314key \-kkeyring.pub fingerprint
315.VE
316and check that the hashes match. If the two sites have separate
317administrators, they should read the hashes to each other over the
318telephone (assuming that they can recognize each other's voices).
319.RE
320.hP 5.
321Start the
322.B tripe
323servers up. Run
324.RS
325.VS
326tripectl \-slD \-S\-P23169
327.VE
328on each of
329.B alice
330and
331.BR bob .
332(The
333.RB ` \-P23169 '
334forces the server to use UDP port 23169: use some other number if 23169
335is inappropriate for your requirements. I chose it by reducing the
336RIPEMD160 hash of
337.RB ` tripe\-port\-number\e0 '
338modulo 2\*(ss16\*(se.)
339.RE
340.hP 6.
341To get
342.B alice
343talking to
344.BR bob ,
345run this shell script (or one like it):
346.RS
347.VS
348#! /bin/sh
74eb47db 349
d6623498 350tripectl add bob 200.0.2.1 23169
351ifname=`tripectl ifname bob`
352ifconfig $ifname \e
353 192.168.0.1 \e
354 pointopoint 192.168.0.2
355route add -net \e
356 10.0.2.0 netmask 255.255.255.0 \e
357 gw 192.168.0.2
358.VE
359Read
360.BR ifconfig (8)
361and
362.BR route (8)
363to find out about your system's variants of these commands. The
364versions shown above assume a Linux system.
365Run a similar script on
366.BR bob ,
367to tell its
368.B tripe
369server to talk to
370.BR alice .
371.RE
372.hP 7.
373Congratulations. The two servers will exchange keys and begin sending
374packets almost immediately. You've set up a virtual private network.
74eb47db 375.SS "About the name"
376The program's name is
377.BR tripe ,
378all in lower-case. The name of the protocol it uses is `TrIPE', with
379four capital letters and one lower-case. The name stands for `Trivial
380IP Encryption'.
381.SH "BUGS"
74eb47db 382The code hasn't been audited. It may contain security bugs. If you
383find one, please inform the author
384.IR immediately .
385.SH "SEE ALSO"
386.BR key (1),
387.BR tripectl (1),
388.BR tripe\-admin (5).
389.PP
390.IR "The Trivial IP Encryption Protocol" ,
391.IR "The Wrestlers Protocol" .
392.SH "AUTHOR"
393Mark Wooding, <mdw@nsict.org>