chiark / gitweb /
debian/: Bump to Debhelper 10.
[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.\"
11ad66c2
MW
12.\" TrIPE is free software: you can redistribute it and/or modify it under
13.\" the terms of the GNU General Public License as published by the Free
14.\" Software Foundation; either version 3 of the License, or (at your
15.\" option) any later version.
fc916a09 16.\"
11ad66c2
MW
17.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
18.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20.\" for more details.
fc916a09
MW
21.\"
22.\" You should have received a copy of the GNU General Public License
11ad66c2 23.\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
fc916a09
MW
24.
25.\"--------------------------------------------------------------------------
e99aedcf 26.so ../common/defs.man \" @@@PRE@@@
fc916a09
MW
27.
28.\"--------------------------------------------------------------------------
0647ba7c 29.TH tripe 8tripe "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
fc916a09
MW
30.
31.\"--------------------------------------------------------------------------
74eb47db 32.SH "NAME"
fc916a09 33.
74eb47db 34tripe \- a simple VPN daemon
fc916a09
MW
35.
36.\"--------------------------------------------------------------------------
74eb47db 37.SH "SYNOPSIS"
fc916a09 38.
74eb47db 39.B tripe
47828bd9 40.RB [ \-46DF ]
74eb47db 41.RB [ \-d
42.IR dir ]
d13e5724 43.RB [ \-b
44.IR addr ]
33ced0d3 45.RB [ \-p
46.IR port ]
42da2a58 47.RB [ \-n
48.IR tunnel ]
d13e5724 49.br
85b1ebd6 50 \c
33ced0d3 51.RB [ \-U
52.IR user ]
53.RB [ \-G
54.IR group ]
d13e5724 55.RB [ \-a
56.IR socket ]
a9279e37
MW
57.RB [ \-m
58.IR mode ]
d13e5724 59.RB [ \-T
60.IR trace-opts ]
74eb47db 61.br
85b1ebd6 62 \c
74eb47db 63.RB [ \-k
64.IR priv-keyring ]
65.RB [ \-K
66.IR pub-keyring ]
67.RB [ \-t
68.IR key-tag ]
fc916a09
MW
69.
70.\"--------------------------------------------------------------------------
74eb47db 71.SH "DESCRIPTION"
fc916a09 72.
74eb47db 73The
74.B tripe
75program is a server which can provide strong IP-level encryption and
1a19f865 76authentication between co-operating hosts. The program and its protocol
77are deliberately very simple, to make analysing them easy and to help
78build trust rapidly in the system.
74eb47db 79.SS "Overview"
80The
81.B tripe
82server manages a number of secure connections to other `peer' hosts.
83Each daemon is given a private key of its own, and a file of public keys
84for the peers with which it is meant to communicate. It is responsible
85for negotiating sets of symmetric keys with its peers, and for
86encrypting, encapsulating and sending IP packets to its peers, and
87decrypting, checking and de-encapsulating packets it receives from
88them.
89.PP
90When the server starts, it creates a Unix-domain socket on which it
91listens for administration commands. It also logs warnings and
92diagnostic information to the programs connected to its admin socket.
93Clients connected to the socket can add new peers, and remove or find
94out about existing peers. The textual protocol used to give the
95.B tripe
96server admin commands is described in
97.BR tripe\-admin (5).
98A client program
99.BR tripectl (1)
100is provided to allow commands to be sent to the server either
101interactively or by simple scripts.
102.SS "Command-line arguments"
103If not given any command-line arguments,
104.B tripe
105will initialize by following these steps:
1a19f865 106.hP 1.
107It sets the directory named by the
108.B TRIPEDIR
109environment variable (or
f7b5d108 110.B "\*(/c"
1a19f865 111if the variable is unset) as the current directory.
112.hP 2.
f492fa0b 113It acquires a UDP socket. The default port is 4070
74eb47db 114It will use this socket to send and receive all communications with its
115peer servers. The port chosen may be discovered by means of the
116.B PORT
117admin command (see
118.BR tripe\-admin (5)).
1a19f865 119.hP 3.
74eb47db 120It loads the private key with the tag or type name
fc5f4823
MW
121.B tripe
122(or, failing that,
74eb47db 123.B tripe\-dh
fc5f4823 124for backwards compatibility reasons) from the Catacomb-format file
74eb47db 125.BR keyring ,
126and loads the file
127.B keyring.pub
128ready for extracting the public keys of peers as they're introduced.
129(The format of these files is described in
130.BR keyring (5).
131They are maintained using the program
132.BR key (1)
133provided with the Catacomb distribution.)
1a19f865 134.hP 4.
74eb47db 135It creates and listens to the Unix-domain socket
136.BR tripesock .
137.PP
138Following this, the server enters its main loop, accepting admin
139connections and obeying any administrative commands, and communicating
140with peers. It also treats its standard input and standard output
141streams as an admin connection, reading commands from standard input and
33ced0d3 142writing responses and diagnostics messages to standard output. Finally,
143it will reload keys from its keyring files if it notices that they've
144changed (it checks inode number and modification time) \- there's no
145need to send a signal.
74eb47db 146.PP
147Much of this behaviour may be altered by giving
148.B tripe
149suitable command-line options:
150.TP
151.B "\-h, \-\-help"
152Writes a brief description of the command-line options available to
153standard output and exits with status 0.
154.TP
155.B "\-v, \-\-version"
156Writes
157.BR tripe 's
158version number to standard output and exits with status 0.
159.TP
160.B "\-u, \-\-usage"
161Writes a brief usage summary to standard output and exits with status 0.
162.TP
42da2a58 163.B "\-\-tunnels"
164Writes to standard output a list of the configured tunnel drivers, one
165per line, and exits with status 0. This is intended for the use of the
3cdc3f3a 166start-up script, so that it can check that it will actually work.
167.TP
47828bd9
MW
168.B "\-4, \-\-ipv4"
169Use only IPv4 addresses. The server will resolve names only to IPv4
170addresses, and not attempt to create IPv6 sockets.
171.TP
172.B "\-6, \-\-ipv6"
173Use only IPv6 addresses. The server will resolve names only to IPv6
174addresses, and not attempt to create IPv4 sockets. Note that v6-mapped
175IPv4 addresses won't work either.
176.TP
74eb47db 177.B "\-D, \-\-daemon"
178Dissociates from its terminal and starts running in the background after
179completing the initialization procedure described above. If running as
180a daemon,
181.B tripe
182will not read commands from standard input or write diagnostics to
183standard output. A better way to start
184.B tripe
185in the background is with
186.BR tripectl (1).
187.TP
46dde080
MW
188.B "\-F, \-\-foreground"
189Runs the server in the `foreground'; i.e.,
190.B tripe
191will quit if it sees end-of-file on its standard input. This is
192incompatible with
193.BR \-D .
194.TP
74eb47db 195.BI "\-d, \-\-directory=" dir
196Makes
197.I dir
797cf76b
MW
198the current directory. The default directory to change to is given by
199the environment variable
200.BR TRIPEDIR ;
201if that's not specified, a default default of
f7b5d108 202.B "\*(/c"
797cf76b 203is used. Give a current directory of
74eb47db 204.B .
205if you don't want it to change directory at all.
206.TP
d13e5724 207.BI "\-b, \-\-bind-address="addr
208Bind the UDP socket to IP address
209.I addr
210rather than the default of
211.BR INADDR_ANY .
212This is useful if your main globally-routable IP address is one you want
213to tunnel through the VPN.
214.TP
74eb47db 215.BI "\-p, \-\-port=" port
216Use the specified UDP port for all communications with peers, rather
f492fa0b
MW
217than the default port 4070. If this is zero, the kernel will assign a
218free port, which can be determined using the
219.B PORT
220administration command (see
221.BR tripe-admin (5)).
74eb47db 222.TP
42da2a58 223.BI "\-n, \-\-tunnel=" tunnel
224Use the specified tunnel driver for new peers by default.
225.TP
33ced0d3 226.BI "\-U, \-\-setuid=" user
227Set uid to that of
228.I user
229(either a user name or integer uid) after initialization. Also set gid
230to
231.IR user 's
232primary group, unless overridden by a
233.B \-G
aa2405e8
MW
234option. The selected user (and group) will also be the owner of the
235administration socket.
33ced0d3 236.TP
237.BI "\-G, \-\-setgid=" group
ec9b8aed
MW
238If the current effective uid is zero (i.e., the daemon was invoked as
239.BR root )
240then set gid to that of
33ced0d3 241.I group
ec9b8aed
MW
242(either a group name or integer gid) after initialization. In any
243event, arrange hat the administration socket be owned by the given
244.IR group .
33ced0d3 245.TP
74eb47db 246.BI "\-k, \-\-priv\-keyring=" file
247Reads the private key from
248.I file
249rather than the default
250.BR keyring .
251.TP
252.BI "\-K, \-\-pub\-keyring=" file
253Reads public keys from
254.I file
255rather than the default
256.BR keyring.pub .
257This can be the same as the private keyring, but that's not recommended.
258.TP
259.BI "\-t, \-\-tag=" tag
260Uses the private key whose tag or type is
261.I tag
262rather than the default
fc5f4823
MW
263.B tripe
264or
74eb47db 265.BR tripe\-dh .
266.TP
267.BI "\-a, \-\-admin\-socket=" socket
268Accept admin connections to a Unix-domain socket named
797cf76b
MW
269.IR socket .
270The default socket, if this option isn't specified, is given by the
271environment variable
272.BR TRIPESOCK ;
273if that's not set either, then a default default of
f7b5d108 274.B "\*(/s/tripesock"
797cf76b 275is used instead.
74eb47db 276.TP
a9279e37
MW
277.BI "\-m, \-\-admin\-perms=" mode
278Permissions (as an octal number) to set on the administration socket. The
279default is 600, which allows only the socket owner. Setting 660 allows
280members of the
281.I group
282configured through the
283.B \-G
284option to connect to the socket, which may be useful. Allowing world access
285is a terrible idea.
286.TP
74eb47db 287.BI "\-T, \-\-trace=" trace-opts
288Allows the enabling or disabling of various internal diagnostics. See
289below for the list of options.
fc5f4823 290.SS "Key exchange group types"
d6623498 291The
292.B tripe
fc5f4823 293server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys
b86e6f3f 294used for bulk data transfer.
fc5f4823
MW
295.PP
296The server works out which it should be doing based on the key's
297.B kx-group
b86e6f3f 298attribute.
fc5f4823
MW
299If this attribute isn't present, then the key's type is examined: if
300it's of the form
1a0b1e9f 301.BI tripe\- group
fc5f4823
MW
302then the
303.I group
304is used. If no group is specified,
305.B dh
306is used as a fallback.
b86e6f3f
MW
307The following groups are defined.
308.TP
309.B dh
310.RS
311Use traditional Diffie\(enHellman in a
312.IR "Schnorr group" :
313a prime-order subgroup of the multiplicative group of
314a finite field; this is the usual
315.I g\*(ssx\*(se
316mod
317.I p
318kind of Diffie\(en\&Hellman.
fc5f4823
MW
319.PP
320To create usual Schnorr-group keys, say something like
74eb47db 321.VS
fc5f4823
MW
322key add \-adh-param \-LS \-b3072 \-B256 \e
323 \-eforever \-tparam tripe\-param kx-group=dh
74eb47db 324.VE
fc5f4823 325to construct a parameters key; and create the private keys by
d6623498 326.VS
327key add \-adh \-pparam \-talice \e
fc5f4823 328 \-e"now + 1 year" tripe
d6623498 329.VE
b86e6f3f
MW
330.RE
331.sv -1
332.TP
333.B ec
334.RS
335Use elliptic curve Diffie\(enHellman.
336An elliptic curve group is a prime-order
337subgroup of the abelian group of
338.BR K -rational
339points on an elliptic curve defined over a finite field
340.BR K .
341.PP
342Given current public knowledge, elliptic curves can provide similar or
343better security to systems based on integer discrete log problems,
344faster, and with less transmitted data. It's a matter of controversy
345whether this will continue to be the case. The author uses elliptic
346curves.
347.PP
fc5f4823 348To create elliptic curve keys, say something like
d6623498 349.VS
fc5f4823
MW
350key add \-aec\-param \-Cnist-p256 \-eforever \e
351 \-tparam tripe\-param kx-group=ec
52c03a2a 352.VE
353to construct a parameters key, using your preferred elliptic curve in
354the
355.B \-C
356option (see
357.BR key (1)
358for details); and create the private keys by
359.VS
360key add \-aec \-pparam \-talice \e
fc5f4823 361 \-e"now + 1 year" tripe
52c03a2a 362.VE
b86e6f3f 363.RE
26936c83
MW
364.sv -1
365.TP
366.B x25519
367.RS
368Use Bernstein's X25519 Diffie\(enHellman function.
369This is technically a variant on
370the general elliptic curve Diffie\(enHellman
371available through the
372.B ec
373setting,
374but carefully designed and heavily optimized.
375.PP
376To create
377.B x25519
378keys,
379say something like
380.VS
381key add \-aempty \-eforever \e
382 \-tparam tripe\-param kx-group=x25519
383.VE
384to construct a parameters key
385(see
386.BR key (1)
387for details);
388and create the private keys by
389.VS
390key add \-ax25519 \-pparam \-talice \e
391 \-e"now + 1 year" tripe
392.VE
393.RE
394.sv -1
395.TP
396.B x448
397.RS
398Use Hamburg's X448 Diffie\(enHellman function.
399Like
400.B x25519
401above,
402this is technically a variant on
403the general elliptic curve Diffie\(enHellman
404available through the
405.B ec
406setting,
407but carefully designed and heavily optimized.
408.PP
409To create
410.B x448
411keys,
412say something like
413.VS
414key add \-aempty \-eforever \e
415 \-tparam tripe\-param kx-group=x448
416.VE
417to construct a parameters key
418(see
419.BR key (1)
420for details);
421and create the private keys by
422.VS
423key add \-ax448 \-pparam \-talice \e
424 \-e"now + 1 year" tripe
425.VE
426.RE
fc5f4823
MW
427Note that the
428.BR tripe-keys (8)
429program provides a rather more convenient means for generating and
430managing keys for
431.BR tripe .
b5c45da1 432.SS "Using other symmetric algorithms"
433The default symmetric algorithms
434.B tripe
435uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160
436(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC
437mode, designed by Bellare, Canetti and Krawczyk). These can all be
438overridden by setting attributes on your private key, as follows.
439.TP
a93aacce 440.B bulk
b87bffcb
MW
441Names the bulk-crypto transform to use. See below.
442.TP
443.B blkc
b2177d04 444Names a blockcipher, used by some bulk-crypto transforms (e.g.,
a305982d 445.BR iiv ).
b2177d04 446The default is to use the blockcipher underlying the chosen
b87bffcb
MW
447.BR cipher ,
448if any.
a93aacce 449.TP
b5c45da1 450.B cipher
451Names the symmetric encryption scheme to use. The default is
452.BR blowfish\-cbc .
453.TP
454.B hash
455Names the hash function to use. The default is
456.BR rmd160 .
457.TP
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.
73d383c0
MW
465If the MAC's name contains a
466.RB ` / '
467character,
468e.g.,
469.RB ` sha512/256 ',
470then an
471.I additional
472.RB ` / '
473and the tag size is required to disambiguate,
474so, e.g.,
475one might write
476.RB ` sha512/256/256 '.
b5c45da1 477.TP
478.B mgf
479A `mask-generation function', used in the key-exchange. The default is
480.IB hash \-mgf
481and there's no good reason to change it.
b87bffcb
MW
482.PP
483The available bulk-crypto transforms are as follows.
484.TP
485.B v0
486Originally this was the only transform available. It's a standard
487generic composition of a CPA-secure symmetric encryption scheme with a
488MAC; initialization vectors for symmetric encryption are chosen at
489random and included explicitly in the cryptogram.
490.TP
491.B iiv
492A newer `implicit-IV' transform. Rather than having an explicit random
b2177d04 493IV, the IV is computed from the sequence number using a blockcipher.
b87bffcb
MW
494This has two advantages over the
495.B v0
496transform. Firstly, it adds less overhead to encrypted messages
497(because the IV no longer needs to be sent explicitly). Secondly, and
498more significantly, the transform is entirely deterministic, so (a) it
499doesn't need the (possibly slow) random number generator, and (b) it
500closes a kleptographic channel, over which a compromised implementation
501could leak secret information to a third party.
de8edc7f 502.TP
e53273ef
MW
503.B aead
504A transform based on an all-in-one `authenticated encryption with
505additional data' scheme. The scheme is named in the
506.B cipher
507attribute; the default is
508.BR rijndael-ocb3 .
509If the
510.B mac
511attribute is given, it must be either
512.B aead
513or
514.BR aead/ \c
515.IR tagsz ,
516where
517.I tagsz
518is the desired tag length in bits; alternatively, the tag length can be
519set in the
520.B tagsz
521attribute. The chosen AEAD scheme must accept at least a 64-bit nonce
522(this rules out OCB3 and CCM with 64-bit blockciphers); it mustn't
523require an absurdly large nonce size (none of the schemes implemented in
524Catacomb present a problem here, but it bears mentioning); it must
525actually support additional header data (which rules out the
526.B naclbox
527schemes, but see the
528.B naclbox
529transform below); and it must produce an empty ciphertext when
530encrypting an empty message (again, all of Catacomb's schemes meet this
531requirement).
532.TP
de8edc7f
MW
533.B naclbox
534A transform based on the NaCl
535.B crypto_secretbox
536transformation.
537The main difference is that NaCl uses XSalsa20,
538while TrIPE uses plain Salsa20 or ChaCha,
539because it doesn't need the larger nonce space.
540You can set the
541.B cipher
542key attribute to one of
543.BR salsa20 ,
544.BR salsa20/12 ,
545.BR salsa20/8 ,
546.BR chacha20 ,
547.BR chacha12 ,
548or
549.B chacha8
550to select the main cipher.
551You can set the
552.B mac
553key attribute to
554.B poly1305
555or
556.B poly1305/128
557but these are the default and no other choice is permitted.
558(This is for forward compatibility,
559in case other MACs and/or tag sizes are allowed later.)
07bdda1f
MW
560.SS "Other key attributes"
561The following attributes can also be set on keys.
562.TP
563.B serialization
564Selects group-element serialization formats.
565The recommended setting is
566.BR constlen ,
567which selects a constant-length encoding when hashing group elements.
568The default,
569for backwards compatibility, is
570.BR v0 ;
571but this is deprecated.
572(The old format uses a variable length format for hashing,
573which can leak information through timing.)
b9066fbb 574.SS "Using SLIP interfaces"
575Though not for the faint of heart, it is possible to get
576.B tripe
577to read and write network packets to a pair of file descriptors using
578SLIP encapsulation. No fancy header compression of any kind is
98fdb08d 579supported.
580.PP
581Two usage modes are supported: a preallocation system, whereby SLIP
582interfaces are created and passed to the
583.B tripe
584server at startup; and a dynamic system, where the server runs a script
585to allocate a new SLIP interface when it needs one. It is possible to
586use a mixture of these two modes, starting
b9066fbb 587.B tripe
98fdb08d 588with a few preallocated interfaces and having it allocate more
589dynamically as it needs them.
590.PP
591The behaviour of
592.BR tripe 's
593SLIP driver is controlled by the
594.B TRIPE_SLIPIF
1f68dfc5 595environment variable. The server will not create SLIP tunnels if this
596variable is not defined. The variable's value is a colon-delimited list
597of preallocated interfaces, followed optionally by the filename of a
598script to run to dynamically allocate more interfaces.
b9066fbb 599.PP
98fdb08d 600A static allocation entry has the form
b9066fbb 601.IR infd [ \c
602.BI , outfd \c
603.RB ] \c
604.BI = \c
98fdb08d 605.IR ifname ,
b9066fbb 606If the
607.I outfd
608is omitted, the same file descriptor is used for input and output.
609.PP
98fdb08d 610The dynamic allocation script must be named by an absolute or relative
e04c2d50 611pathname, beginning with
98fdb08d 612.RB ` / '
613or
614.RB ` . '.
615The server will pass the script an argument, which is the name of the
616peer for which the interface is being created. The script should
617allocate a new SLIP interface (presumably by creating a pty pair),
618configure it appropriately, and write the interface's name to its
619standard output, followed by a newline. It should then read and write
620SLIP packets on its stdin and stdout. The script's stdin will be closed
621when the interface is no longer needed, and the server will attempt to
622send it a
623.B SIGTERM
624signal (though this may fail if the script runs with higher privileges
625than the server).
626.PP
b9066fbb 627The output file descriptor should not block unless it really needs to:
628the
629.B tripe
1f68dfc5 630daemon assumes that it won't, and will get wedged waiting for it to
631accept output.
74eb47db 632.SS "About the name"
633The program's name is
634.BR tripe ,
635all in lower-case. The name of the protocol it uses is `TrIPE', with
636four capital letters and one lower-case. The name stands for `Trivial
637IP Encryption'.
fc916a09
MW
638.
639.\"--------------------------------------------------------------------------
74eb47db 640.SH "BUGS"
fc916a09 641.
74eb47db 642The code hasn't been audited. It may contain security bugs. If you
643find one, please inform the author
644.IR immediately .
fc916a09
MW
645.
646.\"--------------------------------------------------------------------------
74eb47db 647.SH "SEE ALSO"
fc916a09 648.
74eb47db 649.BR key (1),
650.BR tripectl (1),
fc5f4823
MW
651.BR tripe\-admin (5),
652.BR tripe\-keys (8).
74eb47db 653.PP
654.IR "The Trivial IP Encryption Protocol" ,
655.IR "The Wrestlers Protocol" .
fc916a09
MW
656.
657.\"--------------------------------------------------------------------------
74eb47db 658.SH "AUTHOR"
fc916a09 659.
d36eda2a 660Mark Wooding, <mdw@distorted.org.uk>
fc916a09
MW
661.
662.\"----- That's all, folks --------------------------------------------------