X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/6b6ad6702f305891ced3b9a7cf3061c75eabda86..898975ee8b892cadd04322dc884b3bb8d491c8f8:/server/tripe.8.in diff --git a/server/tripe.8.in b/server/tripe.8.in index c72a3548..f43ab5f8 100644 --- a/server/tripe.8.in +++ b/server/tripe.8.in @@ -1,40 +1,44 @@ .\" -*-nroff-*- .\". -.de hP -.IP -\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c -.. -.de VS -.sp 1 -.RS -.nf -.ft B -.. -.de VE -.ft R -.fi -.RE -.sp 1 -.. -.ie t \{\ -. ds o \(bu -. ds ss \s8\u -. ds se \d\s0 -. if \n(.g \{\ -. fam P -. \} -.\} -.el \{\ -. ds o o -. ds ss ^ -. ds se -.\} +.\" Manual for the server +.\" +.\" (c) 2008 Straylight/Edgeware +.\" +. +.\"----- Licensing notice --------------------------------------------------- +.\" +.\" This file is part of Trivial IP Encryption (TrIPE). +.\" +.\" TrIPE is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" TrIPE is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with TrIPE; if not, write to the Free Software Foundation, +.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +. +.\"-------------------------------------------------------------------------- +.so ../common/defs.man \" @@@PRE@@@ +. +.\"-------------------------------------------------------------------------- .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +. +.\"-------------------------------------------------------------------------- .SH "NAME" +. tripe \- a simple VPN daemon +. +.\"-------------------------------------------------------------------------- .SH "SYNOPSIS" +. .B tripe -.RB [ \-D ] +.RB [ \-DF ] .RB [ \-d .IR dir ] .RB [ \-b @@ -61,7 +65,10 @@ tripe \- a simple VPN daemon .IR pub-keyring ] .RB [ \-t .IR key-tag ] +. +.\"-------------------------------------------------------------------------- .SH "DESCRIPTION" +. The .B tripe program is a server which can provide strong IP-level encryption and @@ -99,7 +106,7 @@ will initialize by following these steps: It sets the directory named by the .B TRIPEDIR environment variable (or -.B "@configdir@" +.B "\*(/c" if the variable is unset) as the current directory. .hP 2. It acquires a UDP socket with an arbitrary kernel-selected port number. @@ -110,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 @@ -166,6 +175,13 @@ standard output. A better way to start in the background is with .BR tripectl (1). .TP +.B "\-F, \-\-foreground" +Runs the server in the `foreground'; i.e., +.B tripe +will quit if it sees end-of-file on its standard input. This is +incompatible with +.BR \-D . +.TP .BI "\-d, \-\-directory=" dir Makes .I dir @@ -173,7 +189,7 @@ the current directory. The default directory to change to is given by the environment variable .BR TRIPEDIR ; if that's not specified, a default default of -.B "@configdir@" +.B "\*(/c" is used. Give a current directory of .B . if you don't want it to change directory at all. @@ -201,7 +217,8 @@ to .IR user 's primary group, unless overridden by a .B \-G -option. +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 @@ -225,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 @@ -234,195 +253,73 @@ The default socket, if this option isn't specified, is given by the environment variable .BR TRIPESOCK ; if that's not set either, then a default default of -.B "@socketdir@/tripesock" +.B "\*(/s/tripesock" is used instead. .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 -.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 -.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 + \-e"now + 1 year" tripe .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 +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 @@ -432,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 @@ -531,16 +428,28 @@ The program's name is 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" +. The code hasn't been audited. It may contain security bugs. If you find one, please inform the author .IR immediately . +. +.\"-------------------------------------------------------------------------- .SH "SEE ALSO" +. .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" . +. +.\"-------------------------------------------------------------------------- .SH "AUTHOR" +. Mark Wooding, +. +.\"----- That's all, folks --------------------------------------------------