X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/74eb47db34cb72d98808afb40caced375f348f11..f736d02fda94ac7fd4a40ec6adacffe4244e548b:/doc/tripe.8 diff --git a/doc/tripe.8 b/doc/tripe.8 index 4c031500..fd73144d 100644 --- a/doc/tripe.8 +++ b/doc/tripe.8 @@ -27,7 +27,7 @@ .el \{\ . ds o o . ds ss ^ -. ds se _ +. ds se .\} .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" .SH "NAME" @@ -186,46 +186,192 @@ rather than the default .BI "\-T, \-\-trace=" trace-opts Allows the enabling or disabling of various internal diagnostics. See below for the list of options. -.SS "Key management" -The TrIPE protocol requires all cooperating hosts to be using keys -with the same group parameters. A suitable group may be created with the -command: +.SS "Setting up a VPN with tripe" +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 +.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 ` . ', +.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. +.PP +This isn't quite complicated enough. Each of +.B alice +and +.B bob +needs an extra IP address which we'll use when setting up the +point-to-point link. These addresses need to be routable, at least +within the virtual private network: unfortunately, you can't just use +the same pair everywhere. We'll assign +.B alice +the point-to-point address 192.168.0.1, and +.B bob +the address 192.168.0.2. +.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 .VS key add \-adh\-param \-LS \-b2048 \-B256 \e \-eforever \-tparam tripe\-dh\-param .VE -This creates a `parameters' key labelled -.B param -in your keyring file: it doesn't contain any secrets. You may vary the -security parameters -.B \-b -and -.B \-B -to taste: the ones given provide good security, at the expense of -performance. Even so, from a cryptographic point of view, these keys -will be the weak point in the security of the system. Generation of the -group parameters can take a few minutes. -.PP -You should extract the parameters from your keyring and distribute them -(securely) to the other administrators. The parameters may be extracted -from your keyring with the command: +(See +.BR key (1) +from the Catacomb distribution for details about the +.B key +command.) Also generate a private key for +.BR alice : +.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 alice.pub +key \-kkeyring.pub merge alice.pub .VE -This may be merged into a keyring with: +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 -Once your keyring contains the parameters, a suitable key can be created -with the command: +Generate a private key for +.B bob +and extract the public half, as before: .VS -key add \-adh \-pparam \-e"now + 1 year" tripe\-dh +key add \-adh \-pparam \-tbob \e + \-e"now + 1 year" tripe\-dh +key extract \-f\-secret bob bob.pub +key \-kkeyring.pub merge bob.pub .VE -This creates a Diffie-Hellman key using the parameters from key -.B param -which expires in one year. The new key has type -.BR tripe\-dh . +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 \-S\-P23169 +.VE +on each of +.B alice +and +.BR bob . +(The +.RB ` \-P23169 ' +forces the server to use UDP port 23169: use some other number if 23169 +is inappropriate for your requirements. I chose it by reducing the +RIPEMD160 hash of +.RB ` tripe\-port\-number\e0 ' +modulo 2\*(ss16\*(se.) +.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 23169 +ifname=`tripectl ifname bob` +ifconfig $ifname \e + 192.168.0.1 \e + pointopoint 192.168.0.2 +route add -net \e + 10.0.2.0 netmask 255.255.255.0 \e + gw 192.168.0.2 +.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 "About the name" The program's name is .BR tripe , @@ -233,11 +379,6 @@ all in lower-case. The name of the protocol it uses is `TrIPE', with four capital letters and one lower-case. The name stands for `Trivial IP Encryption'. .SH "BUGS" -It's too easy to deny service during key exchange. If both ends are -honest, they'll notice any interference and resend their packets, but -it's possible to delay successful negotation for as long as desired by -sending bogus key exchange messages. -.PP The code hasn't been audited. It may contain security bugs. If you find one, please inform the author .IR immediately .