X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/e99aedcf9373b3305c32e510c086bf3357b4736a..62b5e3ecc77424add00ad4e5dc86e7248751cdf6:/server/tripe.8.in diff --git a/server/tripe.8.in b/server/tripe.8.in index ad71bc91..14ee0ab7 100644 --- a/server/tripe.8.in +++ b/server/tripe.8.in @@ -55,6 +55,8 @@ tripe \- a simple VPN daemon .IR group ] .RB [ \-a .IR socket ] +.RB [ \-m +.IR mode ] .RB [ \-T .IR trace-opts ] .br @@ -117,8 +119,10 @@ admin command (see .BR tripe\-admin (5)). .hP 3. It loads the private key with the tag or type name +.B tripe +(or, failing that, .B tripe\-dh -from the Catacomb-format file +for backwards compatibility reasons) from the Catacomb-format file .BR keyring , and loads the file .B keyring.pub @@ -219,9 +223,13 @@ option. The selected user (and group) will also be the owner of the administration socket. .TP .BI "\-G, \-\-setgid=" group -Set gid to that of +If the current effective uid is zero (i.e., the daemon was invoked as +.BR root ) +then set gid to that of .I group -(either a group name or integer gid) after initialization. +(either a group name or integer gid) after initialization. In any +event, arrange hat the administration socket be owned by the given +.IR group . .TP .BI "\-k, \-\-priv\-keyring=" file Reads the private key from @@ -240,6 +248,8 @@ This can be the same as the private keyring, but that's not recommended. Uses the private key whose tag or type is .I tag rather than the default +.B tripe +or .BR tripe\-dh . .TP .BI "\-a, \-\-admin\-socket=" socket @@ -252,192 +262,80 @@ if that's not set either, then a default default of .B "\*(/s/tripesock" is used instead. .TP +.BI "\-m, \-\-admin\-perms=" mode +Permissions (as an octal number) to set on the administration socket. The +default is 600, which allows only the socket owner. Setting 660 allows +members of the +.I group +configured through the +.B \-G +option to connect to the socket, which may be useful. Allowing world access +is a terrible idea. +.TP .BI "\-T, \-\-trace=" trace-opts Allows the enabling or disabling of various internal diagnostics. See below for the list of options. -.SS "Setting up a VPN with tripe" +.SS "Key exchange group types" The .B tripe -server identifies peers by name. While it's -.I possible -for each host to maintain its own naming system for its peers, this is -likely to lead to confusion, and it's more sensible to organize a naming -system that works everywhere. How you manage this naming is up to you. -The only restriction on the format of names is that they must be valid -Catacomb key tags, since this is how +server uses Diffie\(en\&Hellman key exchange to agree the symmetric keys +used for bulk data transfer. Currently .B tripe -identifies which public key to use for a particular peer: they may not -contain whitespace characters, or a colon -.RB ` : ' -or dot -.RB ` . ', +can do Diffie\(en\&Hellman in two different kinds of cyclic groups: +.I "Schnorr groups" +(denoted +.BR dh ) +and +.I "elliptic curve groups" +(denoted +.BR ec ). .PP -Allocating IP addresses for VPNs can get quite complicated. I'll -attempt to illustrate with a relatively simple example. Our objective -will be to set up a virtual private network between two sites of -.BR example.com . -The two sites are using distinct IP address ranges from the private -address space described in RFC1918: site A is using addresses from -10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway -host set up with both an address on the site's private network, and an -externally-routable address from the public IP address space. Site A's -gateway machine, -.BR alice , -has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is -.B bob -and has addresses 10.0.2.1 and 200.0.2.1. -.hP 1. -Install -.B tripe -on both of the gateway hosts. Create the directory -.BR /var/lib/tripe . -.hP 2. -On -.BR alice , -make -.B /var/lib/tripe -the current directory and generate a Diffie-Hellman group: -.RS +A Schnorr group is a prime-order subgroup of the multiplicative group of +a finite field; this is the usual +.I g\*(ssx\*(se +mod +.I p +kind of Diffie\(en\&Hellman. An elliptic curve group is a prime-order +subgroup of the abelian group of +.BR K -rational +points on an elliptic curve defined over a finite field +.BR K . +.PP +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's +.B kx-group +attribute, which should be either +.B dh +or +.BR ec . +If this attribute isn't present, then the key's type is examined: if +it's of the form +.BR tripe\- group +then the +.I group +is used. If no group is specified, +.B dh +is used as a fallback. +.PP +To create usual Schnorr-group keys, say something like .VS -key add \-adh\-param \-LS \-b2048 \-B256 \e - \-eforever \-tparam tripe\-dh\-param +key add \-adh-param \-LS \-b3072 \-B256 \e + \-eforever \-tparam tripe\-param kx-group=dh .VE -(See -.BR key (1) -from the Catacomb distribution for details about the -.B key -command.) Also generate a private key for -.BR alice : +to construct a parameters key; and create the private keys by .VS key add \-adh \-pparam \-talice \e - \-e"now + 1 year" tripe\-dh + \-e"now + 1 year" tripe .VE -Extract the group parameters and -.BR alice 's -public key to -.I separate -files, and put the public key in -.BR keyring.pub : -.VS -key extract param param -key extract \-f\-secret alice.pub alice -key \-kkeyring.pub merge alice.pub -.VE -Send the files -.B param -and -.B alice.pub -to -.B bob -in some secure way (e.g., in PGP-signed email, or by using SSH), so that -you can be sure they've not been altered in transit. -.RE -.hP 3. -On -.B bob -now, make -.B /var/lib/tripe -the current directory, and import the key material from -.BR alice : -.RS +To create elliptic curve keys, say something like .VS -key merge param -key \-kkeyring.pub merge alice.pub -.VE -Generate a private key for -.B bob -and extract the public half, as before: -.VS -key add \-adh \-pparam \-tbob \e - \-e"now + 1 year" tripe\-dh -key extract \-f\-secret bob.pub bob -key \-kkeyring.pub merge bob.pub -.VE -and send -.B bob.pub -back to -.B alice -using some secure method. -.RE -.hP 4 -On -.BR alice , -merge -.B bob 's -key into the public keyring. Now, on each host, run -.RS -.VS -key \-kkeyring.pub fingerprint -.VE -and check that the hashes match. If the two sites have separate -administrators, they should read the hashes to each other over the -telephone (assuming that they can recognize each other's voices). -.RE -.hP 5. -Start the -.B tripe -servers up. Run -.RS -.VS -tripectl \-slD -.VE -on each of -.B alice -and -.BR bob . -.RE -.hP 6. -To get -.B alice -talking to -.BR bob , -run this shell script (or one like it): -.RS -.VS -#! /bin/sh - -tripectl add bob 200.0.2.1 4070 -ifname=`tripectl ifname bob` -ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1 -route add -net \e - 10.0.2.0 netmask 255.255.255.0 \e - gw 10.0.2.1 -.VE -Read -.BR ifconfig (8) -and -.BR route (8) -to find out about your system's variants of these commands. The -versions shown above assume a Linux system. -Run a similar script on -.BR bob , -to tell its -.B tripe -server to talk to -.BR alice . -.RE -.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 +key add \-aec\-param \-Cnist-p256 \-eforever \e + \-tparam tripe\-param kx-group=ec .VE to construct a parameters key, using your preferred elliptic curve in the @@ -447,13 +345,13 @@ option (see for details); and create the private keys by .VS key add \-aec \-pparam \-talice \e - \-e"now + 1 year" tripe\-ec + \-e"now + 1 year" tripe .VE -Now start -.B tripe -with the -.B \-ttripe\-ec -option, and all should be well. +Note that the +.BR tripe-keys (8) +program provides a rather more convenient means for generating and +managing keys for +.BR tripe . .SS "Using other symmetric algorithms" The default symmetric algorithms .B tripe @@ -559,7 +457,8 @@ find one, please inform the author . .BR key (1), .BR tripectl (1), -.BR tripe\-admin (5). +.BR tripe\-admin (5), +.BR tripe\-keys (8). .PP .IR "The Trivial IP Encryption Protocol" , .IR "The Wrestlers Protocol" .