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