X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/1a19f86595b5c07ebf7ca7193093c54a75a15310..0e6502d3341dd870293dacc1aafea005c6dadf0d:/doc/tripe.8 diff --git a/doc/tripe.8 b/doc/tripe.8 index caacbe79..40a5b657 100644 --- a/doc/tripe.8 +++ b/doc/tripe.8 @@ -37,12 +37,22 @@ tripe \- a simple VPN daemon .RB [ \-D ] .RB [ \-d .IR dir ] +.RB [ \-b +.IR addr ] .RB [ \-p .IR port ] +.RB [ \-n +.IR tunnel ] +.br + .RB [ \-U .IR user ] .RB [ \-G .IR group ] +.RB [ \-a +.IR socket ] +.RB [ \-T +.IR trace-opts ] .br .RB [ \-k @@ -51,12 +61,6 @@ tripe \- a simple VPN daemon .IR pub-keyring ] .RB [ \-t .IR key-tag ] -.br - -.RB [ \-a -.IR socket ] -.RB [ \-T -.IR trace-opts ] .SH "DESCRIPTION" The .B tripe @@ -146,6 +150,11 @@ version number to standard output and exits with status 0. .B "\-u, \-\-usage" Writes a brief usage summary to standard output and exits with status 0. .TP +.B "\-\-tunnels" +Writes to standard output a list of the configured tunnel drivers, one +per line, and exits with status 0. This is intended for the use of the +start-up script, so that it can check that it will actually work. +.TP .B "\-D, \-\-daemon" Dissociates from its terminal and starts running in the background after completing the initialization procedure described above. If running as @@ -166,10 +175,21 @@ Give a current directory of .B . if you don't want it to change directory at all. .TP +.BI "\-b, \-\-bind-address="addr +Bind the UDP socket to IP address +.I addr +rather than the default of +.BR INADDR_ANY . +This is useful if your main globally-routable IP address is one you want +to tunnel through the VPN. +.TP .BI "\-p, \-\-port=" port Use the specified UDP port for all communications with peers, rather than an arbitarary kernel-assigned port. .TP +.BI "\-n, \-\-tunnel=" tunnel +Use the specified tunnel driver for new peers by default. +.TP .BI "\-U, \-\-setuid=" user Set uid to that of .I user @@ -399,6 +419,126 @@ server to talk to .hP 7. Congratulations. The two servers will exchange keys and begin sending packets almost immediately. You've set up a virtual private network. +.SS "Using elliptic curve keys" +The +.B tripe +server can use elliptic curve Diffie-Hellman for key exchange, rather +than traditional integer Diffie-Hellman. Given current public +knowledge, elliptic curves can provide similar or better security to +systems based on integer discrete log problems, faster, and with less +transmitted data. It's a matter of controversy whether this will +continue to be the case. The author uses elliptic curves. +.PP +The server works out which it +should be doing based on the key type, which is either +.B tripe\-dh +for standard Diffie-Hellman, or +.B tripe\-ec +for elliptic curves. To create elliptic curve keys, say something like +.VS +key add \-aec\-param \-Cnist-p192 \-eforever \e + \-tparam tripe\-ec\-param +.VE +to construct a parameters key, using your preferred elliptic curve in +the +.B \-C +option (see +.BR key (1) +for details); and create the private keys by +.VS +key add \-aec \-pparam \-talice \e + \-e"now + 1 year" tripe\-ec +.VE +Now start +.B tripe +with the +.B \-ttripe\-ec +option, and all should be well. +.SS "Using other symmetric algorithms" +The default symmetric algorithms +.B tripe +uses are Blowfish (by Schneier) for symmetric encryption, and RIPEMD-160 +(by Dobbertin, Bosselaers and Preneel) for hashing and as a MAC (in HMAC +mode, designed by Bellare, Canetti and Krawczyk). These can all be +overridden by setting attributes on your private key, as follows. +.TP +.B cipher +Names the symmetric encryption scheme to use. The default is +.BR blowfish\-cbc . +.TP +.B hash +Names the hash function to use. The default is +.BR rmd160 . +.TP +.B mac +Names the message authentication code to use. The name of the MAC may +be followed by a +.RB ` / ' +and the desired tag length in bits. The default is +.IB hash \-hmac +at half the underlying hash function's output length. +.TP +.B mgf +A `mask-generation function', used in the key-exchange. The default is +.IB hash \-mgf +and there's no good reason to change it. +.SS "Using SLIP interfaces" +Though not for the faint of heart, it is possible to get +.B tripe +to read and write network packets to a pair of file descriptors using +SLIP encapsulation. No fancy header compression of any kind is +supported. +.PP +Two usage modes are supported: a preallocation system, whereby SLIP +interfaces are created and passed to the +.B tripe +server at startup; and a dynamic system, where the server runs a script +to allocate a new SLIP interface when it needs one. It is possible to +use a mixture of these two modes, starting +.B tripe +with a few preallocated interfaces and having it allocate more +dynamically as it needs them. +.PP +The behaviour of +.BR tripe 's +SLIP driver is controlled by the +.B TRIPE_SLIPIF +environment variable. The server will fail to start if this variable is +not defined. The variable's value is a colon-delimited list of +preallocated interfaces, followed optionally by the filename of a script +to run to dynamically allocate more interfaces. +.PP +A static allocation entry has the form +.IR infd [ \c +.BI , outfd \c +.RB ] \c +.BI = \c +.IR ifname , +If the +.I outfd +is omitted, the same file descriptor is used for input and output. +.PP +The dynamic allocation script must be named by an absolute or relative +pathname, beginning with +.RB ` / ' +or +.RB ` . '. +The server will pass the script an argument, which is the name of the +peer for which the interface is being created. The script should +allocate a new SLIP interface (presumably by creating a pty pair), +configure it appropriately, and write the interface's name to its +standard output, followed by a newline. It should then read and write +SLIP packets on its stdin and stdout. The script's stdin will be closed +when the interface is no longer needed, and the server will attempt to +send it a +.B SIGTERM +signal (though this may fail if the script runs with higher privileges +than the server). +.PP +The output file descriptor should not block unless it really needs to: +the +.B tripe +daemon assumes that it won't, and will get wait for it to accept output. .SS "About the name" The program's name is .BR tripe , @@ -417,4 +557,4 @@ find one, please inform the author .IR "The Trivial IP Encryption Protocol" , .IR "The Wrestlers Protocol" . .SH "AUTHOR" -Mark Wooding, +Mark Wooding,