chiark / gitweb /
server/tests.at (AWAIT_KXDONE): Ignore the correct server messages.
[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.\"--------------------------------------------------------------------------
0647ba7c 30.TH tripe 8tripe "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
a93aacce 363.B bulk
b87bffcb
MW
364Names the bulk-crypto transform to use. See below.
365.TP
366.B blkc
367Names a block cipher, used by some bulk-crypto transforms (e.g.,
368.BR iiv ). The default is to use the block cipher underlying the chosen
369.BR cipher ,
370if any.
a93aacce 371.TP
b5c45da1 372.B cipher
373Names the symmetric encryption scheme to use. The default is
374.BR blowfish\-cbc .
375.TP
376.B hash
377Names the hash function to use. The default is
378.BR rmd160 .
379.TP
380.B mac
381Names the message authentication code to use. The name of the MAC may
382be followed by a
383.RB ` / '
384and the desired tag length in bits. The default is
385.IB hash \-hmac
386at half the underlying hash function's output length.
387.TP
388.B mgf
389A `mask-generation function', used in the key-exchange. The default is
390.IB hash \-mgf
391and there's no good reason to change it.
b87bffcb
MW
392.PP
393The available bulk-crypto transforms are as follows.
394.TP
395.B v0
396Originally this was the only transform available. It's a standard
397generic composition of a CPA-secure symmetric encryption scheme with a
398MAC; initialization vectors for symmetric encryption are chosen at
399random and included explicitly in the cryptogram.
400.TP
401.B iiv
402A newer `implicit-IV' transform. Rather than having an explicit random
403IV, the IV is computed from the sequence number using a block cipher.
404This has two advantages over the
405.B v0
406transform. Firstly, it adds less overhead to encrypted messages
407(because the IV no longer needs to be sent explicitly). Secondly, and
408more significantly, the transform is entirely deterministic, so (a) it
409doesn't need the (possibly slow) random number generator, and (b) it
410closes a kleptographic channel, over which a compromised implementation
411could leak secret information to a third party.
b9066fbb 412.SS "Using SLIP interfaces"
413Though not for the faint of heart, it is possible to get
414.B tripe
415to read and write network packets to a pair of file descriptors using
416SLIP encapsulation. No fancy header compression of any kind is
98fdb08d 417supported.
418.PP
419Two usage modes are supported: a preallocation system, whereby SLIP
420interfaces are created and passed to the
421.B tripe
422server at startup; and a dynamic system, where the server runs a script
423to allocate a new SLIP interface when it needs one. It is possible to
424use a mixture of these two modes, starting
b9066fbb 425.B tripe
98fdb08d 426with a few preallocated interfaces and having it allocate more
427dynamically as it needs them.
428.PP
429The behaviour of
430.BR tripe 's
431SLIP driver is controlled by the
432.B TRIPE_SLIPIF
1f68dfc5 433environment variable. The server will not create SLIP tunnels if this
434variable is not defined. The variable's value is a colon-delimited list
435of preallocated interfaces, followed optionally by the filename of a
436script to run to dynamically allocate more interfaces.
b9066fbb 437.PP
98fdb08d 438A static allocation entry has the form
b9066fbb 439.IR infd [ \c
440.BI , outfd \c
441.RB ] \c
442.BI = \c
98fdb08d 443.IR ifname ,
b9066fbb 444If the
445.I outfd
446is omitted, the same file descriptor is used for input and output.
447.PP
98fdb08d 448The dynamic allocation script must be named by an absolute or relative
e04c2d50 449pathname, beginning with
98fdb08d 450.RB ` / '
451or
452.RB ` . '.
453The server will pass the script an argument, which is the name of the
454peer for which the interface is being created. The script should
455allocate a new SLIP interface (presumably by creating a pty pair),
456configure it appropriately, and write the interface's name to its
457standard output, followed by a newline. It should then read and write
458SLIP packets on its stdin and stdout. The script's stdin will be closed
459when the interface is no longer needed, and the server will attempt to
460send it a
461.B SIGTERM
462signal (though this may fail if the script runs with higher privileges
463than the server).
464.PP
b9066fbb 465The output file descriptor should not block unless it really needs to:
466the
467.B tripe
1f68dfc5 468daemon assumes that it won't, and will get wedged waiting for it to
469accept output.
74eb47db 470.SS "About the name"
471The program's name is
472.BR tripe ,
473all in lower-case. The name of the protocol it uses is `TrIPE', with
474four capital letters and one lower-case. The name stands for `Trivial
475IP Encryption'.
fc916a09
MW
476.
477.\"--------------------------------------------------------------------------
74eb47db 478.SH "BUGS"
fc916a09 479.
74eb47db 480The code hasn't been audited. It may contain security bugs. If you
481find one, please inform the author
482.IR immediately .
fc916a09
MW
483.
484.\"--------------------------------------------------------------------------
74eb47db 485.SH "SEE ALSO"
fc916a09 486.
74eb47db 487.BR key (1),
488.BR tripectl (1),
fc5f4823
MW
489.BR tripe\-admin (5),
490.BR tripe\-keys (8).
74eb47db 491.PP
492.IR "The Trivial IP Encryption Protocol" ,
493.IR "The Wrestlers Protocol" .
fc916a09
MW
494.
495.\"--------------------------------------------------------------------------
74eb47db 496.SH "AUTHOR"
fc916a09 497.
d36eda2a 498Mark Wooding, <mdw@distorted.org.uk>
fc916a09
MW
499.
500.\"----- That's all, folks --------------------------------------------------