.el \{\
. ds o o
. ds ss ^
-. ds se _
+. ds se
.\}
.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "NAME"
.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 ,
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 .