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