X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/c7211b0d98a2485c859133b2dc129cdfd93eb67f..fc5f482398c76a2d1e81f88f2ce3e750ad029c19:/server/tripe.8.in diff --git a/server/tripe.8.in b/server/tripe.8.in index ad71bc91..f43ab5f8 100644 --- a/server/tripe.8.in +++ b/server/tripe.8.in @@ -117,8 +117,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 @@ -240,6 +242,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 @@ -255,189 +259,67 @@ is used instead. .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 -.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 -.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 + \-e"now + 1 year" tripe .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 +To create elliptic curve keys, say something like .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 +329,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 +441,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" .