chiark / gitweb /
server: Add a peer without sending key-exchange packets.
[tripe] / doc /
74eb47db 1.\" -*-nroff-*-
2.\". hP
5\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
6.. VS
8.sp 1
11.ft B
12.. VE
14.ft R
17.sp 1
18.. t \{\
20. ds o \(bu
21. ds ss \s8\u
22. ds se \d\s0
23. if \n(.g \{\
24. fam P
25. \}
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
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 ]
42da2a58 44.RB [ \-n
45.IR tunnel ]
e04c2d50 47
33ced0d3 48.RB [ \-U
49.IR user ]
50.RB [ \-G
51.IR group ]
d13e5724 52.RB [ \-a
53.IR socket ]
54.RB [ \-T
55.IR trace-opts ]
e04c2d50 57
74eb47db 58.RB [ \-k
59.IR priv-keyring ]
60.RB [ \-K
61.IR pub-keyring ]
62.RB [ \-t
63.IR key-tag ]
66.B tripe
67program is a server which can provide strong IP-level encryption and
1a19f865 68authentication between co-operating hosts. The program and its protocol
69are deliberately very simple, to make analysing them easy and to help
70build trust rapidly in the system.
74eb47db 71.SS "Overview"
73.B tripe
74server manages a number of secure connections to other `peer' hosts.
75Each daemon is given a private key of its own, and a file of public keys
76for the peers with which it is meant to communicate. It is responsible
77for negotiating sets of symmetric keys with its peers, and for
78encrypting, encapsulating and sending IP packets to its peers, and
79decrypting, checking and de-encapsulating packets it receives from
82When the server starts, it creates a Unix-domain socket on which it
83listens for administration commands. It also logs warnings and
84diagnostic information to the programs connected to its admin socket.
85Clients connected to the socket can add new peers, and remove or find
86out about existing peers. The textual protocol used to give the
87.B tripe
88server admin commands is described in
89.BR tripe\-admin (5).
90A client program
91.BR tripectl (1)
92is provided to allow commands to be sent to the server either
93interactively or by simple scripts.
94.SS "Command-line arguments"
95If not given any command-line arguments,
96.B tripe
97will initialize by following these steps:
1a19f865 98.hP 1.
99It sets the directory named by the
101environment variable (or
797cf76b 102.B "@configdir@"
1a19f865 103if the variable is unset) as the current directory.
104.hP 2.
74eb47db 105It acquires a UDP socket with an arbitrary kernel-selected port number.
106It will use this socket to send and receive all communications with its
107peer servers. The port chosen may be discovered by means of the
108.B PORT
109admin command (see
110.BR tripe\-admin (5)).
1a19f865 111.hP 3.
74eb47db 112It loads the private key with the tag or type name
113.B tripe\-dh
114from the Catacomb-format file
115.BR keyring ,
116and loads the file
118ready for extracting the public keys of peers as they're introduced.
119(The format of these files is described in
120.BR keyring (5).
121They are maintained using the program
122.BR key (1)
123provided with the Catacomb distribution.)
1a19f865 124.hP 4.
74eb47db 125It creates and listens to the Unix-domain socket
126.BR tripesock .
128Following this, the server enters its main loop, accepting admin
129connections and obeying any administrative commands, and communicating
130with peers. It also treats its standard input and standard output
131streams as an admin connection, reading commands from standard input and
33ced0d3 132writing responses and diagnostics messages to standard output. Finally,
133it will reload keys from its keyring files if it notices that they've
134changed (it checks inode number and modification time) \- there's no
135need to send a signal.
74eb47db 136.PP
137Much of this behaviour may be altered by giving
138.B tripe
139suitable command-line options:
141.B "\-h, \-\-help"
142Writes a brief description of the command-line options available to
143standard output and exits with status 0.
145.B "\-v, \-\-version"
147.BR tripe 's
148version number to standard output and exits with status 0.
150.B "\-u, \-\-usage"
151Writes a brief usage summary to standard output and exits with status 0.
42da2a58 153.B "\-\-tunnels"
154Writes to standard output a list of the configured tunnel drivers, one
155per line, and exits with status 0. This is intended for the use of the
3cdc3f3a 156start-up script, so that it can check that it will actually work.
74eb47db 158.B "\-D, \-\-daemon"
159Dissociates from its terminal and starts running in the background after
160completing the initialization procedure described above. If running as
161a daemon,
162.B tripe
163will not read commands from standard input or write diagnostics to
164standard output. A better way to start
165.B tripe
166in the background is with
167.BR tripectl (1).
169.BI "\-d, \-\-directory=" dir
171.I dir
172the current directory. The default directory to change to is given by
173the environment variable
175if that's not specified, a default default of
176.B "@configdir@"
177is used. Give a current directory of
74eb47db 178.B .
179if you don't want it to change directory at all.
d13e5724 181.BI "\-b, \-\-bind-address="addr
182Bind the UDP socket to IP address
183.I addr
184rather than the default of
186This is useful if your main globally-routable IP address is one you want
187to tunnel through the VPN.
74eb47db 189.BI "\-p, \-\-port=" port
190Use the specified UDP port for all communications with peers, rather
191than an arbitarary kernel-assigned port.
42da2a58 193.BI "\-n, \-\-tunnel=" tunnel
194Use the specified tunnel driver for new peers by default.
33ced0d3 196.BI "\-U, \-\-setuid=" user
197Set uid to that of
198.I user
199(either a user name or integer uid) after initialization. Also set gid
201.IR user 's
202primary group, unless overridden by a
203.B \-G
206.BI "\-G, \-\-setgid=" group
207Set gid to that of
208.I group
209(either a group name or integer gid) after initialization.
74eb47db 211.BI "\-k, \-\-priv\-keyring=" file
212Reads the private key from
213.I file
214rather than the default
215.BR keyring .
217.BI "\-K, \-\-pub\-keyring=" file
218Reads public keys from
219.I file
220rather than the default
221.BR .
222This can be the same as the private keyring, but that's not recommended.
224.BI "\-t, \-\-tag=" tag
225Uses the private key whose tag or type is
226.I tag
227rather than the default
228.BR tripe\-dh .
230.BI "\-a, \-\-admin\-socket=" socket
231Accept admin connections to a Unix-domain socket named
232.IR socket .
233The default socket, if this option isn't specified, is given by the
234environment variable
236if that's not set either, then a default default of
237.B "@socketdir@/tripesock"
238is used instead.
74eb47db 239.TP
240.BI "\-T, \-\-trace=" trace-opts
241Allows the enabling or disabling of various internal diagnostics. See
242below for the list of options.
d6623498 243.SS "Setting up a VPN with tripe"
245.B tripe
246server identifies peers by name. While it's
247.I possible
248for each host to maintain its own naming system for its peers, this is
249likely to lead to confusion, and it's more sensible to organize a naming
250system that works everywhere. How you manage this naming is up to you.
251The only restriction on the format of names is that they must be valid
252Catacomb key tags, since this is how
253.B tripe
254identifies which public key to use for a particular peer: they may not
255contain whitespace characters, or a colon
256.RB ` : '
257or dot
258.RB ` . ',
260Allocating IP addresses for VPNs can get quite complicated. I'll
261attempt to illustrate with a relatively simple example. Our objective
262will be to set up a virtual private network between two sites of
263.BR .
264The two sites are using distinct IP address ranges from the private
265address space described in RFC1918: site A is using addresses from
26610.0.1.0/24 and site B is using Each site has a gateway
267host set up with both an address on the site's private network, and an
268externally-routable address from the public IP address space. Site A's
269gateway machine,
270.BR alice ,
271has the addresses and; site B's gateway is
272.B bob
273and has addresses and
d6623498 274.hP 1.
276.B tripe
277on both of the gateway hosts. Create the directory
278.BR /var/lib/tripe .
279.hP 2.
281.BR alice ,
283.B /var/lib/tripe
284the current directory and generate a Diffie-Hellman group:
74eb47db 286.VS
287key add \-adh\-param \-LS \-b2048 \-B256 \e
288 \-eforever \-tparam tripe\-dh\-param
d6623498 290(See
291.BR key (1)
292from the Catacomb distribution for details about the
293.B key
294command.) Also generate a private key for
295.BR alice :
297key add \-adh \-pparam \-talice \e
298 \-e"now + 1 year" tripe\-dh
300Extract the group parameters and
301.BR alice 's
302public key to
303.I separate
304files, and put the public key in
305.BR :
74eb47db 306.VS
307key extract param param
37075862 308key extract \-f\-secret alice
d6623498 309key \ merge
74eb47db 310.VE
d6623498 311Send the files
312.B param
316.B bob
317in some secure way (e.g., in PGP-signed email, or by using SSH), so that
318you can be sure they've not been altered in transit.
320.hP 3.
322.B bob
323now, make
324.B /var/lib/tripe
325the current directory, and import the key material from
326.BR alice :
74eb47db 328.VS
329key merge param
d6623498 330key \ merge
74eb47db 331.VE
d6623498 332Generate a private key for
333.B bob
334and extract the public half, as before:
74eb47db 335.VS
d6623498 336key add \-adh \-pparam \-tbob \e
337 \-e"now + 1 year" tripe\-dh
383f2a0b 338key extract \-f\-secret bob
d6623498 339key \ merge
74eb47db 340.VE
d6623498 341and send
343back to
344.B alice
345using some secure method.
347.hP 4
349.BR alice ,
351.B bob 's
352key into the public keyring. Now, on each host, run
355key \ fingerprint
357and check that the hashes match. If the two sites have separate
358administrators, they should read the hashes to each other over the
359telephone (assuming that they can recognize each other's voices).
361.hP 5.
362Start the
363.B tripe
364servers up. Run
165efde7 367tripectl \-slD
d6623498 368.VE
369on each of
370.B alice
372.BR bob .
d6623498 373.RE
374.hP 6.
375To get
376.B alice
377talking to
378.BR bob ,
379run this shell script (or one like it):
382#! /bin/sh
74eb47db 383
165efde7 384tripectl add bob 4070
d6623498 385ifname=`tripectl ifname bob`
1f68dfc5 386ifconfig $ifname pointopoint
d6623498 387route add -net \e
388 netmask \e
1f68dfc5 389 gw
d6623498 390.VE
392.BR ifconfig (8)
394.BR route (8)
395to find out about your system's variants of these commands. The
396versions shown above assume a Linux system.
397Run a similar script on
398.BR bob ,
399to tell its
400.B tripe
401server to talk to
402.BR alice .
404.hP 7.
405Congratulations. The two servers will exchange keys and begin sending
406packets almost immediately. You've set up a virtual private network.
52c03a2a 407.SS "Using elliptic curve keys"
409.B tripe
410server can use elliptic curve Diffie-Hellman for key exchange, rather
411than traditional integer Diffie-Hellman. Given current public
412knowledge, elliptic curves can provide similar or better security to
413systems based on integer discrete log problems, faster, and with less
414transmitted data. It's a matter of controversy whether this will
415continue to be the case. The author uses elliptic curves.
417The server works out which it
418should be doing based on the key type, which is either
419.B tripe\-dh
420for standard Diffie-Hellman, or
421.B tripe\-ec
422for elliptic curves. To create elliptic curve keys, say something like
424key add \-aec\-param \-Cnist-p192 \-eforever \e
425 \-tparam tripe\-ec\-param
427to construct a parameters key, using your preferred elliptic curve in
429.B \-C
430option (see
431.BR key (1)
432for details); and create the private keys by
434key add \-aec \-pparam \-talice \e
435 \-e"now + 1 year" tripe\-ec
437Now start
438.B tripe
439with the
440.B \-ttripe\-ec
441option, and all should be well.
b5c45da1 442.SS "Using other symmetric algorithms"
443The default symmetric algorithms
444.B tripe
445uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
446(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
447mode, designed by Bellare, Canetti and Krawczyk). These can all be
448overridden by setting attributes on your private key, as follows.
450.B cipher
451Names the symmetric encryption scheme to use. The default is
452.BR blowfish\-cbc .
454.B hash
455Names the hash function to use. The default is
456.BR rmd160 .
458.B mac
459Names the message authentication code to use. The name of the MAC may
460be followed by a
461.RB ` / '
462and the desired tag length in bits. The default is
463.IB hash \-hmac
464at half the underlying hash function's output length.
466.B mgf
467A `mask-generation function', used in the key-exchange. The default is
468.IB hash \-mgf
469and there's no good reason to change it.
b9066fbb 470.SS "Using SLIP interfaces"
471Though not for the faint of heart, it is possible to get
472.B tripe
473to read and write network packets to a pair of file descriptors using
474SLIP encapsulation. No fancy header compression of any kind is
98fdb08d 475supported.
477Two usage modes are supported: a preallocation system, whereby SLIP
478interfaces are created and passed to the
479.B tripe
480server at startup; and a dynamic system, where the server runs a script
481to allocate a new SLIP interface when it needs one. It is possible to
482use a mixture of these two modes, starting
b9066fbb 483.B tripe
98fdb08d 484with a few preallocated interfaces and having it allocate more
485dynamically as it needs them.
487The behaviour of
488.BR tripe 's
489SLIP driver is controlled by the
1f68dfc5 491environment variable. The server will not create SLIP tunnels if this
492variable is not defined. The variable's value is a colon-delimited list
493of preallocated interfaces, followed optionally by the filename of a
494script to run to dynamically allocate more interfaces.
b9066fbb 495.PP
98fdb08d 496A static allocation entry has the form
b9066fbb 497.IR infd [ \c
498.BI , outfd \c
499.RB ] \c
500.BI = \c
98fdb08d 501.IR ifname ,
b9066fbb 502If the
503.I outfd
504is omitted, the same file descriptor is used for input and output.
98fdb08d 506The dynamic allocation script must be named by an absolute or relative
e04c2d50 507pathname, beginning with
98fdb08d 508.RB ` / '
510.RB ` . '.
511The server will pass the script an argument, which is the name of the
512peer for which the interface is being created. The script should
513allocate a new SLIP interface (presumably by creating a pty pair),
514configure it appropriately, and write the interface's name to its
515standard output, followed by a newline. It should then read and write
516SLIP packets on its stdin and stdout. The script's stdin will be closed
517when the interface is no longer needed, and the server will attempt to
518send it a
520signal (though this may fail if the script runs with higher privileges
521than the server).
b9066fbb 523The output file descriptor should not block unless it really needs to:
525.B tripe
1f68dfc5 526daemon assumes that it won't, and will get wedged waiting for it to
527accept output.
74eb47db 528.SS "About the name"
529The program's name is
530.BR tripe ,
531all in lower-case. The name of the protocol it uses is `TrIPE', with
532four capital letters and one lower-case. The name stands for `Trivial
533IP Encryption'.
534.SH "BUGS"
74eb47db 535The code hasn't been audited. It may contain security bugs. If you
536find one, please inform the author
537.IR immediately .
539.BR key (1),
540.BR tripectl (1),
541.BR tripe\-admin (5).
543.IR "The Trivial IP Encryption Protocol" ,
544.IR "The Wrestlers Protocol" .
d36eda2a 546Mark Wooding, <>