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