chiark / gitweb /
Version bump; new email address.
[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
3cdc3f3a 151.B "\-\-tunnel"
152Writes a string to standard output describing the configured tunnelling
153method and exits with status 0. This is intended for the use of the
154start-up script, so that it can check that it will actually work.
155.TP
74eb47db 156.B "\-D, \-\-daemon"
157Dissociates from its terminal and starts running in the background after
158completing the initialization procedure described above. If running as
159a daemon,
160.B tripe
161will not read commands from standard input or write diagnostics to
162standard output. A better way to start
163.B tripe
164in the background is with
165.BR tripectl (1).
166.TP
167.BI "\-d, \-\-directory=" dir
168Makes
169.I dir
170the current directory, instead of
171.BR /var/lib/tripe .
172Give a current directory of
173.B .
174if you don't want it to change directory at all.
175.TP
d13e5724 176.BI "\-b, \-\-bind-address="addr
177Bind the UDP socket to IP address
178.I addr
179rather than the default of
180.BR INADDR_ANY .
181This is useful if your main globally-routable IP address is one you want
182to tunnel through the VPN.
183.TP
74eb47db 184.BI "\-p, \-\-port=" port
185Use the specified UDP port for all communications with peers, rather
186than an arbitarary kernel-assigned port.
187.TP
33ced0d3 188.BI "\-U, \-\-setuid=" user
189Set uid to that of
190.I user
191(either a user name or integer uid) after initialization. Also set gid
192to
193.IR user 's
194primary group, unless overridden by a
195.B \-G
196option.
197.TP
198.BI "\-G, \-\-setgid=" group
199Set gid to that of
200.I group
201(either a group name or integer gid) after initialization.
202.TP
74eb47db 203.BI "\-k, \-\-priv\-keyring=" file
204Reads the private key from
205.I file
206rather than the default
207.BR keyring .
208.TP
209.BI "\-K, \-\-pub\-keyring=" file
210Reads public keys from
211.I file
212rather than the default
213.BR keyring.pub .
214This can be the same as the private keyring, but that's not recommended.
215.TP
216.BI "\-t, \-\-tag=" tag
217Uses the private key whose tag or type is
218.I tag
219rather than the default
220.BR tripe\-dh .
221.TP
222.BI "\-a, \-\-admin\-socket=" socket
223Accept admin connections to a Unix-domain socket named
224.I socket
225rather than the default
226.BR tripesock .
227.TP
228.BI "\-T, \-\-trace=" trace-opts
229Allows the enabling or disabling of various internal diagnostics. See
230below for the list of options.
d6623498 231.SS "Setting up a VPN with tripe"
232The
233.B tripe
234server identifies peers by name. While it's
235.I possible
236for each host to maintain its own naming system for its peers, this is
237likely to lead to confusion, and it's more sensible to organize a naming
238system that works everywhere. How you manage this naming is up to you.
239The only restriction on the format of names is that they must be valid
240Catacomb key tags, since this is how
241.B tripe
242identifies which public key to use for a particular peer: they may not
243contain whitespace characters, or a colon
244.RB ` : '
245or dot
246.RB ` . ',
247.PP
248Allocating IP addresses for VPNs can get quite complicated. I'll
249attempt to illustrate with a relatively simple example. Our objective
250will be to set up a virtual private network between two sites of
251.BR example.com .
252The two sites are using distinct IP address ranges from the private
253address space described in RFC1918: site A is using addresses from
25410.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway
255host set up with both an address on the site's private network, and an
256externally-routable address from the public IP address space. Site A's
257gateway machine,
258.BR alice ,
259has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
260.B bob
261and has addresses 10.0.2.1 and 200.0.2.1.
262.PP
263This isn't quite complicated enough. Each of
264.B alice
265and
266.B bob
267needs an extra IP address which we'll use when setting up the
268point-to-point link. These addresses need to be routable, at least
269within the virtual private network: unfortunately, you can't just use
270the same pair everywhere. We'll assign
271.B alice
272the point-to-point address 192.168.0.1, and
273.B bob
274the address 192.168.0.2.
275.hP 1.
276Install
277.B tripe
278on both of the gateway hosts. Create the directory
279.BR /var/lib/tripe .
280.hP 2.
281On
282.BR alice ,
283make
284.B /var/lib/tripe
285the current directory and generate a Diffie-Hellman group:
286.RS
74eb47db 287.VS
288key add \-adh\-param \-LS \-b2048 \-B256 \e
289 \-eforever \-tparam tripe\-dh\-param
290.VE
d6623498 291(See
292.BR key (1)
293from the Catacomb distribution for details about the
294.B key
295command.) Also generate a private key for
296.BR alice :
297.VS
298key add \-adh \-pparam \-talice \e
299 \-e"now + 1 year" tripe\-dh
300.VE
301Extract the group parameters and
302.BR alice 's
303public key to
304.I separate
305files, and put the public key in
306.BR keyring.pub :
74eb47db 307.VS
308key extract param param
37075862 309key extract \-f\-secret alice.pub alice
d6623498 310key \-kkeyring.pub merge alice.pub
74eb47db 311.VE
d6623498 312Send the files
313.B param
314and
315.B alice.pub
316to
317.B bob
318in some secure way (e.g., in PGP-signed email, or by using SSH), so that
319you can be sure they've not been altered in transit.
320.RE
321.hP 3.
322On
323.B bob
324now, make
325.B /var/lib/tripe
326the current directory, and import the key material from
327.BR alice :
328.RS
74eb47db 329.VS
330key merge param
d6623498 331key \-kkeyring.pub merge alice.pub
74eb47db 332.VE
d6623498 333Generate a private key for
334.B bob
335and extract the public half, as before:
74eb47db 336.VS
d6623498 337key add \-adh \-pparam \-tbob \e
338 \-e"now + 1 year" tripe\-dh
383f2a0b 339key extract \-f\-secret bob.pub bob
d6623498 340key \-kkeyring.pub merge bob.pub
74eb47db 341.VE
d6623498 342and send
343.B bob.pub
344back to
345.B alice
346using some secure method.
347.RE
348.hP 4
349On
350.BR alice ,
351merge
352.B bob 's
353key into the public keyring. Now, on each host, run
354.RS
355.VS
356key \-kkeyring.pub fingerprint
357.VE
358and check that the hashes match. If the two sites have separate
359administrators, they should read the hashes to each other over the
360telephone (assuming that they can recognize each other's voices).
361.RE
362.hP 5.
363Start the
364.B tripe
365servers up. Run
366.RS
367.VS
368tripectl \-slD \-S\-P23169
369.VE
370on each of
371.B alice
372and
373.BR bob .
374(The
375.RB ` \-P23169 '
376forces the server to use UDP port 23169: use some other number if 23169
377is inappropriate for your requirements. I chose it by reducing the
378RIPEMD160 hash of
379.RB ` tripe\-port\-number\e0 '
380modulo 2\*(ss16\*(se.)
381.RE
382.hP 6.
383To get
384.B alice
385talking to
386.BR bob ,
387run this shell script (or one like it):
388.RS
389.VS
390#! /bin/sh
74eb47db 391
d6623498 392tripectl add bob 200.0.2.1 23169
393ifname=`tripectl ifname bob`
394ifconfig $ifname \e
395 192.168.0.1 \e
396 pointopoint 192.168.0.2
397route add -net \e
398 10.0.2.0 netmask 255.255.255.0 \e
399 gw 192.168.0.2
400.VE
401Read
402.BR ifconfig (8)
403and
404.BR route (8)
405to find out about your system's variants of these commands. The
406versions shown above assume a Linux system.
407Run a similar script on
408.BR bob ,
409to tell its
410.B tripe
411server to talk to
412.BR alice .
413.RE
414.hP 7.
415Congratulations. The two servers will exchange keys and begin sending
416packets almost immediately. You've set up a virtual private network.
52c03a2a 417.SS "Using elliptic curve keys"
418The
419.B tripe
420server can use elliptic curve Diffie-Hellman for key exchange, rather
421than traditional integer Diffie-Hellman. Given current public
422knowledge, elliptic curves can provide similar or better security to
423systems based on integer discrete log problems, faster, and with less
424transmitted data. It's a matter of controversy whether this will
425continue to be the case. The author uses elliptic curves.
426.PP
427The server works out which it
428should be doing based on the key type, which is either
429.B tripe\-dh
430for standard Diffie-Hellman, or
431.B tripe\-ec
432for elliptic curves. To create elliptic curve keys, say something like
433.VS
434key add \-aec\-param \-Cnist-p192 \-eforever \e
435 \-tparam tripe\-ec\-param
436.VE
437to construct a parameters key, using your preferred elliptic curve in
438the
439.B \-C
440option (see
441.BR key (1)
442for details); and create the private keys by
443.VS
444key add \-aec \-pparam \-talice \e
445 \-e"now + 1 year" tripe\-ec
446.VE
447Now start
448.B tripe
449with the
450.B \-ttripe\-ec
451option, and all should be well.
b5c45da1 452.SS "Using other symmetric algorithms"
453The default symmetric algorithms
454.B tripe
455uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
456(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
457mode, designed by Bellare, Canetti and Krawczyk). These can all be
458overridden by setting attributes on your private key, as follows.
459.TP
460.B cipher
461Names the symmetric encryption scheme to use. The default is
462.BR blowfish\-cbc .
463.TP
464.B hash
465Names the hash function to use. The default is
466.BR rmd160 .
467.TP
468.B mac
469Names the message authentication code to use. The name of the MAC may
470be followed by a
471.RB ` / '
472and the desired tag length in bits. The default is
473.IB hash \-hmac
474at half the underlying hash function's output length.
475.TP
476.B mgf
477A `mask-generation function', used in the key-exchange. The default is
478.IB hash \-mgf
479and there's no good reason to change it.
b9066fbb 480.SS "Using SLIP interfaces"
481Though not for the faint of heart, it is possible to get
482.B tripe
483to read and write network packets to a pair of file descriptors using
484SLIP encapsulation. No fancy header compression of any kind is
485supported. The intended use is that you allocate a pty pair, set the
486slave's line discipline to SLIP, and hand the
487.B tripe
488server the master end, though in fact any old file descriptors will do.
489.PP
490The SLIP descriptors must be set up and running before the daemon is
491started, and you must inform it about the SLIP descriptors it's meant to
492use in an environment variable
493.BR TRIPE_SLIPIF ,
494whose value must be a colon-separated list of items of the form
495.IR infd [ \c
496.BI , outfd \c
497.RB ] \c
498.BI = \c
499.IR ifname .
500If the
501.I outfd
502is omitted, the same file descriptor is used for input and output.
503.PP
504The output file descriptor should not block unless it really needs to:
505the
506.B tripe
507daemon assumes that it won't, and will get wait for it to accept output.
74eb47db 508.SS "About the name"
509The program's name is
510.BR tripe ,
511all in lower-case. The name of the protocol it uses is `TrIPE', with
512four capital letters and one lower-case. The name stands for `Trivial
513IP Encryption'.
514.SH "BUGS"
74eb47db 515The code hasn't been audited. It may contain security bugs. If you
516find one, please inform the author
517.IR immediately .
518.SH "SEE ALSO"
519.BR key (1),
520.BR tripectl (1),
521.BR tripe\-admin (5).
522.PP
523.IR "The Trivial IP Encryption Protocol" ,
524.IR "The Wrestlers Protocol" .
525.SH "AUTHOR"
d36eda2a 526Mark Wooding, <mdw@distorted.org.uk>