--- gvpe/doc/gvpe.5 2005/01/27 06:58:48 1.3
+++ gvpe/doc/gvpe.5 2008/09/03 04:58:46 1.11
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -25,11 +25,11 @@
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. | will give a
-.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
@@ -48,22 +48,25 @@
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
@@ -129,39 +132,64 @@
.\" ========================================================================
.\"
.IX Title "GVPE 5"
-.TH GVPE 5 "2005-01-27" "1.7" "GNU Virtual Private Ethernet"
+.TH GVPE 5 "2008-09-01" "2.2" "GNU Virtual Private Ethernet"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
GNU\-VPE \- Overview of the GNU Virtual Private Ethernet suite.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1GVPE\s0 is a suite designed to provide a virtual private network for multiple
-nodes over an untrusted network.
-.IP "\(bu" 4
-.IX Xref "Virtual"
-Virtual means that no physical network is created (of course), but an
-ethernet is emulated by creating multiple tunnels between the member
-nodes.
-.IP "\(bu" 4
-.IX Xref "Private"
+nodes over an untrusted network. This document first gives an introduction
+to VPNs in general and then describes the specific implementation of \s-1GVPE\s0.
+.Sh "\s-1WHAT\s0 \s-1IS\s0 A \s-1VPN\s0?"
+.IX Subsection "WHAT IS A VPN?"
+\&\s-1VPN\s0 is an acronym, it stands for:
+.IP "Virtual" 4
+.IX Item "Virtual"
+Virtual means that no physical network is created (of course), but a
+network is \fIemulated\fR by creating multiple tunnels between the member
+nodes by encapsulating and sending data over another transport network.
+.Sp
+Usually the emulated network is a normal \s-1IP\s0 or Ethernet, and the transport
+network is the Internet. However, using a \s-1VPN\s0 system like \s-1GVPE\s0 to connect
+nodes over other untrusted networks such as Wireless \s-1LAN\s0 is not uncommon.
+.IP "Private" 4
+.IX Item "Private"
Private means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
-inject (\*(L"spoof\*(R") packets.
+inject (\*(L"spoof\*(R") packets. This means that nodes can be connected over
+untrusted networks such as the public Internet without fear of being
+eavesdropped while at the same time being able to trust data sent by other
+nodes.
.Sp
-In the case of gvpe, even participating nodes cannot sniff packets send to
-other nodes or spoof packets as if sent from other nodes.
-.IP "\(bu" 4
-.IX Xref "Network"
+In the case of \s-1GVPE\s0, even participating nodes cannot sniff packets
+send to other nodes or spoof packets as if sent from other nodes, so
+communications between any two nodes is private to those two nodes.
+.IP "Network" 4
+.IX Item "Network"
Network means that more than two parties can participate in the network,
so for instance it's possible to connect multiple branches of a company
-into a single network. Many so-called \*(L"vpn\*(R" solutions only create
-point-to-point tunnels.
-.Sh "\s-1DESIGN\s0 \s-1GOALS\s0"
-.IX Subsection "DESIGN GOALS"
+into a single network. Many so-called \*(L"\s-1VPN\s0\*(R" solutions only create
+point-to-point tunnels, which in turn can be used to build larger
+networks.
+.Sp
+\&\s-1GVPE\s0 provides a true multi-point network in which any number of nodes (at
+least a few dozen in practise, the theoretical limit is 4095 nodes) can
+participate.
+.Sh "\s-1GVPE\s0 \s-1DESIGN\s0 \s-1GOALS\s0"
+.IX Subsection "GVPE DESIGN GOALS"
.IP "\s-1SIMPLE\s0 \s-1DESIGN\s0" 4
.IX Item "SIMPLE DESIGN"
Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
at compile time \- this makes it possible to only link in algorithms
you actually need. It also makes the crypto part of the source very
-transparent and easy to inspect.
+transparent and easy to inspect, and last not least this makes it possible
+to hardcode the layout of all packets into the binary. \s-1GVPE\s0 goes a step
+further and internally reserves blocks of the same length for all packets,
+which virtually removes all possibilities of buffer overflows, as there is
+only a single type of buffer and it's always of fixed length.
.IP "\s-1EASY\s0 \s-1TO\s0 \s-1SETUP\s0" 4
.IX Item "EASY TO SETUP"
A few lines of config (the config file is shared unmodified between all
@@ -176,89 +204,93 @@
another host.
.SH "PROGRAMS"
.IX Header "PROGRAMS"
-Vpe comes with two programs: one daemon (\f(CW\*(C`gvpe\*(C'\fR) and one control program
+Gvpe comes with two programs: one daemon (\f(CW\*(C`gvpe\*(C'\fR) and one control program
(\f(CW\*(C`gvpectrl\*(C'\fR).
.IP "gvpectrl" 4
.IX Item "gvpectrl"
-Is used to generate the keys, check and give an overview of of the
-configuration and contorl the daemon (restarting etc.).
+This program is used to generate the keys, check and give an overview of of the
+configuration and to control the daemon (restarting etc.).
.IP "gvpe" 4
.IX Item "gvpe"
-Is the daemon used to establish and maintain connections to the other
-network members. It should be run on the gateway machine.
+This is the daemon used to establish and maintain connections to the other
+network nodes. It should be run on the gateway of each \s-1VPN\s0 subnet.
.SH "COMPILETIME CONFIGURATION"
.IX Header "COMPILETIME CONFIGURATION"
Please have a look at the \f(CW\*(C`gvpe.osdep(5)\*(C'\fR manpage for platform-specific
information.
.PP
-Here are a few recipes for compiling your gvpe:
+Gvpe hardcodes most encryption parameters. While this reduces flexibility,
+it makes the program much simpler and helps making buffer overflows
+impossible under most circumstances.
+.PP
+Here are a few recipes for compiling your gvpe, showing the extremes
+(fast, small, insecure \s-1OR\s0 slow, large, more secure), between which you
+should choose:
.Sh "\s-1AS\s0 \s-1LOW\s0 \s-1PACKET\s0 \s-1OVERHEAD\s0 \s-1AS\s0 \s-1POSSIBLE\s0"
.IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
.Vb 1
-\& ./configure --enable-hmac-length=4 --enable-rand-length=0
+\& ./configure \-\-enable\-hmac\-length=4 \-\-enable\-rand\-length=0
.Ve
.PP
-Minimize the header overhead of \s-1VPN\s0 packets (the above will result in only
-4 bytes of overhead over the raw ethernet frame).
+Minimize the header overhead of \s-1VPN\s0 packets (the above will result in
+only 4 bytes of overhead over the raw ethernet frame). This is a insecure
+configuration because a \s-1HMAC\s0 length of 4 makes collision attacks based on
+the birthday paradox pretty easy.
.Sh "\s-1MINIMIZE\s0 \s-1CPU\s0 \s-1TIME\s0 \s-1REQUIRED\s0"
.IX Subsection "MINIMIZE CPU TIME REQUIRED"
.Vb 1
-\& ./configure --enable-cipher=bf --enable-digest=md4
+\& ./configure \-\-enable\-cipher=bf \-\-enable\-digest=md4
.Ve
.PP
-Use the fastest cipher and digest algorithms currently available in gvpe.
+Use the fastest cipher and digest algorithms currently available in
+gvpe. \s-1MD4\s0 has been broken and is quite insecure, though, so using another
+digest algorithm is recommended.
.Sh "\s-1MAXIMIZE\s0 \s-1SECURITY\s0"
.IX Subsection "MAXIMIZE SECURITY"
.Vb 1
-\& ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
+\& ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=8 \-\-enable\-digest=sha1
.Ve
.PP
This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
would also be pretty secure ;) and will additionally prefix each packet
with 8 bytes of random data. In the long run, people should move to
-\&\s-1SHA\-224\s0 and beyond, but support in openssl is missing as of writing this
-document.
+\&\s-1SHA\-256\s0 and beyond).
.PP
-In general, remember that \s-1AES\-128\s0 seems to be more secure and faster than
+In general, remember that \s-1AES\-128\s0 seems to be as secure but faster than
\&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer
-\&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0 or \s-1RIPEMD160\s0 are
-better, and Blowfish is a fast cipher (and also quite secure).
+\&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1\s0, \s-1RIPEMD160\s0, \s-1SHA256\s0
+are consecutively better, and Blowfish is a fast cipher (and also quite
+secure).
.SH "HOW TO SET UP A SIMPLE VPN"
.IX Header "HOW TO SET UP A SIMPLE VPN"
In this section I will describe how to get a simple \s-1VPN\s0 consisting of
three hosts up and running.
.Sh "\s-1STEP\s0 1: configuration"
.IX Subsection "STEP 1: configuration"
-First you have to create a daemon configuation file and put it into the
+First you have to create a daemon configuration file and put it into the
configuration directory. This is usually \f(CW\*(C`/etc/gvpe\*(C'\fR, depending on how you
-configured gvpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR commandline switch.
+configured gvpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR command line switch.
.PP
Put the following lines into \f(CW\*(C`/etc/gvpe/gvpe.conf\*(C'\fR:
.PP
.Vb 3
-\& udp-port = 50000 # the external port to listen on (configure your firewall)
+\& udp\-port = 50000 # the external port to listen on (configure your firewall)
\& mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
\& ifname = vpn0 # the local network device name
-.Ve
-.PP
-.Vb 2
+\&
\& node = first # just a nickname
\& hostname = first.example.net # the DNS name or IP address of the host
-.Ve
-.PP
-.Vb 2
+\&
\& node = second
\& hostname = 133.55.82.9
-.Ve
-.PP
-.Vb 2
+\&
\& node = third
\& hostname = third.example.net
.Ve
.PP
-The only other file neccessary if the \f(CW\*(C`if\-up\*(C'\fR script that initializes the
-local ethernet interface. Put the following lines into \f(CW\*(C`/etc/gvpe/if\-up\*(C'\fR
-and make it execute (\f(CW\*(C`chmod 755 /etc/gvpe/if\-up\*(C'\fR):
+The only other file necessary is the \f(CW\*(C`if\-up\*(C'\fR script that initializes the
+virtual ethernet interface on the local host. Put the following lines into
+\&\f(CW\*(C`/etc/gvpe/if\-up\*(C'\fR and make it executable (\f(CW\*(C`chmod 755 /etc/gvpe/if\-up\*(C'\fR):
.PP
.Vb 6
\& #!/bin/sh
@@ -270,68 +302,71 @@
.Ve
.PP
This script will give each node a different \s-1IP\s0 address in the \f(CW\*(C`10.0/16\*(C'\fR
-network. The internal network (e.g. the \f(CW\*(C`eth0\*(C'\fR interface) should then be
+network. The internal network (if gvpe runs on a router) should then be
set to a subset of that network, e.g. \f(CW\*(C`10.0.1.0/24\*(C'\fR on node \f(CW\*(C`first\*(C'\fR,
\&\f(CW\*(C`10.0.2.0/24\*(C'\fR on node \f(CW\*(C`second\*(C'\fR, and so on.
.PP
By enabling routing on the gateway host that runs \f(CW\*(C`gvpe\*(C'\fR all nodes will
-be able to reach the other nodes. You can, of course, also use proxy arp
-or other means of pseudo-bridging (or even real briding), or (best) full
-routing \- the choice is yours.
+be able to reach the other nodes. You can, of course, also use proxy \s-1ARP\s0
+or other means of pseudo-bridging, or (best) full routing \- the choice is
+yours.
.Sh "\s-1STEP\s0 2: create the \s-1RSA\s0 key pairs for all hosts"
.IX Subsection "STEP 2: create the RSA key pairs for all hosts"
-Run the following command to generate all key pairs (that might take a
-while):
+Run the following command to generate all key pairs for all nodes (that
+might take a while):
.PP
.Vb 1
-\& gvpectrl -c /etc/gvpe -g
+\& gvpectrl \-c /etc/gvpe \-g
.Ve
.PP
This command will put the public keys into \f(CW\*(C`/etc/gvpe/pubkeys/\f(CInodename\f(CW\*(C'\fR and the private keys into \f(CW\*(C`/etc/gvpe/hostkeys/\f(CInodename\f(CW\*(C'\fR.
.Sh "\s-1STEP\s0 3: distribute the config files to all nodes"
.IX Subsection "STEP 3: distribute the config files to all nodes"
-Now distribute the config files to the other nodes. This should be done in two steps, since the
-private keys should not be distributed. The example uses rsync-over-ssh
+Now distribute the config files and private keys to the other nodes. This
+should be done in two steps, since only the private keys meant for a node
+should be distributed (so each node has only it's own private key).
+.PP
+The example uses rsync-over-ssh
.PP
First all the config files without the hostkeys should be distributed:
.PP
.Vb 3
-\& rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys
-\& rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys
-\& rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkeys
+\& rsync \-avzessh /etc/gvpe first.example.net:/etc/. \-\-exclude hostkeys
+\& rsync \-avzessh /etc/gvpe 133.55.82.9:/etc/. \-\-exclude hostkeys
+\& rsync \-avzessh /etc/gvpe third.example.net:/etc/. \-\-exclude hostkeys
.Ve
.PP
Then the hostkeys should be copied:
.PP
.Vb 3
-\& rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
-\& rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
-\& rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
+\& rsync \-avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
+\& rsync \-avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
+\& rsync \-avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
.Ve
.PP
-You should now check the configration by issuing the command \f(CW\*(C`gvpectrl \-c
+You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl \-c
/etc/gvpe \-s\*(C'\fR on each node and verify it's output.
.Sh "\s-1STEP\s0 4: starting gvpe"
.IX Subsection "STEP 4: starting gvpe"
You should then start gvpe on each node by issuing a command like:
.PP
.Vb 1
-\& gvpe -D -linfo first # first is the nodename
+\& gvpe \-D \-l info first # first is the nodename
.Ve
.PP
-This will make the gvpe stay in foreground. You should then see
+This will make the gvpe daemon stay in foreground. You should then see
\&\*(L"connection established\*(R" messages. If you don't see them check your
firewall and routing (use tcpdump ;).
.PP
If this works you should check your networking setup by pinging various
endpoints.
.PP
-To make gvpe run more permanently you can either run it as a daemon
-(by starting it without the \f(CW\*(C`\-D\*(C'\fR switch), or, much better, from your
-inittab. I use a line like this on my systems:
+To make gvpe run more permanently you can either run it as a daemon (by
+starting it without the \f(CW\*(C`\-D\*(C'\fR switch), or, much better, from your inittab
+or equivalent. I use a line like this on all my systems:
.PP
.Vb 1
-\& t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
+\& t1:2345:respawn:/opt/gvpe/sbin/gvpe \-D \-L first >/dev/null 2>&1
.Ve
.Sh "\s-1STEP\s0 5: enjoy"
.IX Subsection "STEP 5: enjoy"
@@ -342,11 +377,15 @@
again.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
-\&\fIgvpe.osdep\fR\|(5) for OS-depedendent information, \fIgvpe.conf\fR\|(5), \fIgvpectrl\fR\|(8), and
-for a description of the protocol and routing algorithms, \fIgvpe.protocol\fR\|(7).
+\&\fIgvpe.osdep\fR\|(5) for OS-dependent information, \fIgvpe.conf\fR\|(5), \fIgvpectrl\fR\|(8),
+and for a description of the transports, protocol, and routing algorithm,
+\&\fIgvpe.protocol\fR\|(7).
+.PP
+The \s-1GVPE\s0 mailing list, at , or
+\&\f(CW\*(C`gvpe@lists.schmorp.de\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
-Marc Lehmann
+Marc Lehmann
.SH "COPYRIGHTS AND LICENSES"
.IX Header "COPYRIGHTS AND LICENSES"
\&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL\s0 \s-1PUBLIC\s0 \s-1LICENSE\s0 (see the file