chiark / gitweb /
server/tripe.h: Allow `break' from FOREACH_PEER.
[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.\"--------------------------------------------------------------------------
e99aedcf 27.so ../common/defs.man \" @@@PRE@@@
fc916a09
MW
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 ]
a9279e37
MW
58.RB [ \-m
59.IR mode ]
d13e5724 60.RB [ \-T
61.IR trace-opts ]
74eb47db 62.br
85b1ebd6 63 \c
74eb47db 64.RB [ \-k
65.IR priv-keyring ]
66.RB [ \-K
67.IR pub-keyring ]
68.RB [ \-t
69.IR key-tag ]
fc916a09
MW
70.
71.\"--------------------------------------------------------------------------
74eb47db 72.SH "DESCRIPTION"
fc916a09 73.
74eb47db 74The
75.B tripe
76program is a server which can provide strong IP-level encryption and
1a19f865 77authentication between co-operating hosts. The program and its protocol
78are deliberately very simple, to make analysing them easy and to help
79build trust rapidly in the system.
74eb47db 80.SS "Overview"
81The
82.B tripe
83server manages a number of secure connections to other `peer' hosts.
84Each daemon is given a private key of its own, and a file of public keys
85for the peers with which it is meant to communicate. It is responsible
86for negotiating sets of symmetric keys with its peers, and for
87encrypting, encapsulating and sending IP packets to its peers, and
88decrypting, checking and de-encapsulating packets it receives from
89them.
90.PP
91When the server starts, it creates a Unix-domain socket on which it
92listens for administration commands. It also logs warnings and
93diagnostic information to the programs connected to its admin socket.
94Clients connected to the socket can add new peers, and remove or find
95out about existing peers. The textual protocol used to give the
96.B tripe
97server admin commands is described in
98.BR tripe\-admin (5).
99A client program
100.BR tripectl (1)
101is provided to allow commands to be sent to the server either
102interactively or by simple scripts.
103.SS "Command-line arguments"
104If not given any command-line arguments,
105.B tripe
106will initialize by following these steps:
1a19f865 107.hP 1.
108It sets the directory named by the
109.B TRIPEDIR
110environment variable (or
f7b5d108 111.B "\*(/c"
1a19f865 112if the variable is unset) as the current directory.
113.hP 2.
74eb47db 114It acquires a UDP socket with an arbitrary kernel-selected port number.
115It will use this socket to send and receive all communications with its
116peer servers. The port chosen may be discovered by means of the
117.B PORT
118admin command (see
119.BR tripe\-admin (5)).
1a19f865 120.hP 3.
74eb47db 121It loads the private key with the tag or type name
fc5f4823
MW
122.B tripe
123(or, failing that,
74eb47db 124.B tripe\-dh
fc5f4823 125for backwards compatibility reasons) from the Catacomb-format file
74eb47db 126.BR keyring ,
127and loads the file
128.B keyring.pub
129ready for extracting the public keys of peers as they're introduced.
130(The format of these files is described in
131.BR keyring (5).
132They are maintained using the program
133.BR key (1)
134provided with the Catacomb distribution.)
1a19f865 135.hP 4.
74eb47db 136It creates and listens to the Unix-domain socket
137.BR tripesock .
138.PP
139Following this, the server enters its main loop, accepting admin
140connections and obeying any administrative commands, and communicating
141with peers. It also treats its standard input and standard output
142streams as an admin connection, reading commands from standard input and
33ced0d3 143writing responses and diagnostics messages to standard output. Finally,
144it will reload keys from its keyring files if it notices that they've
145changed (it checks inode number and modification time) \- there's no
146need to send a signal.
74eb47db 147.PP
148Much of this behaviour may be altered by giving
149.B tripe
150suitable command-line options:
151.TP
152.B "\-h, \-\-help"
153Writes a brief description of the command-line options available to
154standard output and exits with status 0.
155.TP
156.B "\-v, \-\-version"
157Writes
158.BR tripe 's
159version number to standard output and exits with status 0.
160.TP
161.B "\-u, \-\-usage"
162Writes a brief usage summary to standard output and exits with status 0.
163.TP
42da2a58 164.B "\-\-tunnels"
165Writes to standard output a list of the configured tunnel drivers, one
166per line, and exits with status 0. This is intended for the use of the
3cdc3f3a 167start-up script, so that it can check that it will actually work.
168.TP
74eb47db 169.B "\-D, \-\-daemon"
170Dissociates from its terminal and starts running in the background after
171completing the initialization procedure described above. If running as
172a daemon,
173.B tripe
174will not read commands from standard input or write diagnostics to
175standard output. A better way to start
176.B tripe
177in the background is with
178.BR tripectl (1).
179.TP
46dde080
MW
180.B "\-F, \-\-foreground"
181Runs the server in the `foreground'; i.e.,
182.B tripe
183will quit if it sees end-of-file on its standard input. This is
184incompatible with
185.BR \-D .
186.TP
74eb47db 187.BI "\-d, \-\-directory=" dir
188Makes
189.I dir
797cf76b
MW
190the current directory. The default directory to change to is given by
191the environment variable
192.BR TRIPEDIR ;
193if that's not specified, a default default of
f7b5d108 194.B "\*(/c"
797cf76b 195is used. Give a current directory of
74eb47db 196.B .
197if you don't want it to change directory at all.
198.TP
d13e5724 199.BI "\-b, \-\-bind-address="addr
200Bind the UDP socket to IP address
201.I addr
202rather than the default of
203.BR INADDR_ANY .
204This is useful if your main globally-routable IP address is one you want
205to tunnel through the VPN.
206.TP
74eb47db 207.BI "\-p, \-\-port=" port
208Use the specified UDP port for all communications with peers, rather
209than an arbitarary kernel-assigned port.
210.TP
42da2a58 211.BI "\-n, \-\-tunnel=" tunnel
212Use the specified tunnel driver for new peers by default.
213.TP
33ced0d3 214.BI "\-U, \-\-setuid=" user
215Set uid to that of
216.I user
217(either a user name or integer uid) after initialization. Also set gid
218to
219.IR user 's
220primary group, unless overridden by a
221.B \-G
aa2405e8
MW
222option. The selected user (and group) will also be the owner of the
223administration socket.
33ced0d3 224.TP
225.BI "\-G, \-\-setgid=" group
ec9b8aed
MW
226If the current effective uid is zero (i.e., the daemon was invoked as
227.BR root )
228then set gid to that of
33ced0d3 229.I group
ec9b8aed
MW
230(either a group name or integer gid) after initialization. In any
231event, arrange hat the administration socket be owned by the given
232.IR group .
33ced0d3 233.TP
74eb47db 234.BI "\-k, \-\-priv\-keyring=" file
235Reads the private key from
236.I file
237rather than the default
238.BR keyring .
239.TP
240.BI "\-K, \-\-pub\-keyring=" file
241Reads public keys from
242.I file
243rather than the default
244.BR keyring.pub .
245This can be the same as the private keyring, but that's not recommended.
246.TP
247.BI "\-t, \-\-tag=" tag
248Uses the private key whose tag or type is
249.I tag
250rather than the default
fc5f4823
MW
251.B tripe
252or
74eb47db 253.BR tripe\-dh .
254.TP
255.BI "\-a, \-\-admin\-socket=" socket
256Accept admin connections to a Unix-domain socket named
797cf76b
MW
257.IR socket .
258The default socket, if this option isn't specified, is given by the
259environment variable
260.BR TRIPESOCK ;
261if that's not set either, then a default default of
f7b5d108 262.B "\*(/s/tripesock"
797cf76b 263is used instead.
74eb47db 264.TP
a9279e37
MW
265.BI "\-m, \-\-admin\-perms=" mode
266Permissions (as an octal number) to set on the administration socket. The
267default is 600, which allows only the socket owner. Setting 660 allows
268members of the
269.I group
270configured through the
271.B \-G
272option to connect to the socket, which may be useful. Allowing world access
273is a terrible idea.
274.TP
74eb47db 275.BI "\-T, \-\-trace=" trace-opts
276Allows the enabling or disabling of various internal diagnostics. See
277below for the list of options.
fc5f4823 278.SS "Key exchange group types"
d6623498 279The
280.B tripe
fc5f4823
MW
281server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
282used for bulk data transfer. Currently
d6623498 283.B tripe
fc5f4823
MW
284can do Diffie\(en\&Hellman in two different kinds of cyclic groups:
285.I "Schnorr groups"
286(denoted
287.BR dh )
288and
289.I "elliptic curve groups"
290(denoted
291.BR ec ).
d6623498 292.PP
fc5f4823
MW
293A Schnorr group is a prime-order subgroup of the multiplicative group of
294a finite field; this is the usual
295.I g\*(ssx\*(se
296mod
297.I p
298kind of Diffie\(en\&Hellman. An elliptic curve group is a prime-order
299subgroup of the abelian group of
300.BR K -rational
301points on an elliptic curve defined over a finite field
302.BR K .
303.PP
304Given current public knowledge, elliptic curves can provide similar or
305better security to systems based on integer discrete log problems,
306faster, and with less transmitted data. It's a matter of controversy
307whether this will continue to be the case. The author uses elliptic
308curves.
309.PP
310The server works out which it should be doing based on the key's
311.B kx-group
312attribute, which should be either
313.B dh
314or
315.BR ec .
316If this attribute isn't present, then the key's type is examined: if
317it's of the form
318.BR tripe\- group
319then the
320.I group
321is used. If no group is specified,
322.B dh
323is used as a fallback.
324.PP
325To create usual Schnorr-group keys, say something like
74eb47db 326.VS
fc5f4823
MW
327key add \-adh-param \-LS \-b3072 \-B256 \e
328 \-eforever \-tparam tripe\-param kx-group=dh
74eb47db 329.VE
fc5f4823 330to construct a parameters key; and create the private keys by
d6623498 331.VS
332key add \-adh \-pparam \-talice \e
fc5f4823 333 \-e"now + 1 year" tripe
d6623498 334.VE
fc5f4823 335To create elliptic curve keys, say something like
d6623498 336.VS
fc5f4823
MW
337key add \-aec\-param \-Cnist-p256 \-eforever \e
338 \-tparam tripe\-param kx-group=ec
52c03a2a 339.VE
340to construct a parameters key, using your preferred elliptic curve in
341the
342.B \-C
343option (see
344.BR key (1)
345for details); and create the private keys by
346.VS
347key add \-aec \-pparam \-talice \e
fc5f4823 348 \-e"now + 1 year" tripe
52c03a2a 349.VE
fc5f4823
MW
350Note that the
351.BR tripe-keys (8)
352program provides a rather more convenient means for generating and
353managing keys for
354.BR tripe .
b5c45da1 355.SS "Using other symmetric algorithms"
356The default symmetric algorithms
357.B tripe
358uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
359(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
360mode, designed by Bellare, Canetti and Krawczyk). These can all be
361overridden by setting attributes on your private key, as follows.
362.TP
363.B cipher
364Names the symmetric encryption scheme to use. The default is
365.BR blowfish\-cbc .
366.TP
367.B hash
368Names the hash function to use. The default is
369.BR rmd160 .
370.TP
371.B mac
372Names the message authentication code to use. The name of the MAC may
373be followed by a
374.RB ` / '
375and the desired tag length in bits. The default is
376.IB hash \-hmac
377at half the underlying hash function's output length.
378.TP
379.B mgf
380A `mask-generation function', used in the key-exchange. The default is
381.IB hash \-mgf
382and there's no good reason to change it.
b9066fbb 383.SS "Using SLIP interfaces"
384Though not for the faint of heart, it is possible to get
385.B tripe
386to read and write network packets to a pair of file descriptors using
387SLIP encapsulation. No fancy header compression of any kind is
98fdb08d 388supported.
389.PP
390Two usage modes are supported: a preallocation system, whereby SLIP
391interfaces are created and passed to the
392.B tripe
393server at startup; and a dynamic system, where the server runs a script
394to allocate a new SLIP interface when it needs one. It is possible to
395use a mixture of these two modes, starting
b9066fbb 396.B tripe
98fdb08d 397with a few preallocated interfaces and having it allocate more
398dynamically as it needs them.
399.PP
400The behaviour of
401.BR tripe 's
402SLIP driver is controlled by the
403.B TRIPE_SLIPIF
1f68dfc5 404environment variable. The server will not create SLIP tunnels if this
405variable is not defined. The variable's value is a colon-delimited list
406of preallocated interfaces, followed optionally by the filename of a
407script to run to dynamically allocate more interfaces.
b9066fbb 408.PP
98fdb08d 409A static allocation entry has the form
b9066fbb 410.IR infd [ \c
411.BI , outfd \c
412.RB ] \c
413.BI = \c
98fdb08d 414.IR ifname ,
b9066fbb 415If the
416.I outfd
417is omitted, the same file descriptor is used for input and output.
418.PP
98fdb08d 419The dynamic allocation script must be named by an absolute or relative
e04c2d50 420pathname, beginning with
98fdb08d 421.RB ` / '
422or
423.RB ` . '.
424The server will pass the script an argument, which is the name of the
425peer for which the interface is being created. The script should
426allocate a new SLIP interface (presumably by creating a pty pair),
427configure it appropriately, and write the interface's name to its
428standard output, followed by a newline. It should then read and write
429SLIP packets on its stdin and stdout. The script's stdin will be closed
430when the interface is no longer needed, and the server will attempt to
431send it a
432.B SIGTERM
433signal (though this may fail if the script runs with higher privileges
434than the server).
435.PP
b9066fbb 436The output file descriptor should not block unless it really needs to:
437the
438.B tripe
1f68dfc5 439daemon assumes that it won't, and will get wedged waiting for it to
440accept output.
74eb47db 441.SS "About the name"
442The program's name is
443.BR tripe ,
444all in lower-case. The name of the protocol it uses is `TrIPE', with
445four capital letters and one lower-case. The name stands for `Trivial
446IP Encryption'.
fc916a09
MW
447.
448.\"--------------------------------------------------------------------------
74eb47db 449.SH "BUGS"
fc916a09 450.
74eb47db 451The code hasn't been audited. It may contain security bugs. If you
452find one, please inform the author
453.IR immediately .
fc916a09
MW
454.
455.\"--------------------------------------------------------------------------
74eb47db 456.SH "SEE ALSO"
fc916a09 457.
74eb47db 458.BR key (1),
459.BR tripectl (1),
fc5f4823
MW
460.BR tripe\-admin (5),
461.BR tripe\-keys (8).
74eb47db 462.PP
463.IR "The Trivial IP Encryption Protocol" ,
464.IR "The Wrestlers Protocol" .
fc916a09
MW
465.
466.\"--------------------------------------------------------------------------
74eb47db 467.SH "AUTHOR"
fc916a09 468.
d36eda2a 469Mark Wooding, <mdw@distorted.org.uk>
fc916a09
MW
470.
471.\"----- That's all, folks --------------------------------------------------