--- gvpe/doc/gvpe.5 2004/06/11 15:56:12 1.1
+++ gvpe/doc/gvpe.5 2005/03/23 21:55:39 1.8
@@ -129,39 +129,60 @@
.\" ========================================================================
.\"
.IX Title "GVPE 5"
-.TH GVPE 5 "2004-06-11" "1.7" "GNU Virtual Private Ethernet"
+.TH GVPE 5 "2005-03-23" "1.9" "GNU Virtual Private Ethernet"
.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.
-.PP
-\&\*(L"Virtual\*(R" means that no physical network is created (of course), but an
-ethernet is emulated by creating multiple tunnels between the member
-nodes.
+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 "\(bu" 4
.IX Xref "Virtual"
-.PP
-\&\*(L"Private\*(R" means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
-inject (\*(L"spoof\*(R") packets.
+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 "\(bu" 4
.IX Xref "Private"
-.PP
-In the case of gvpe, even participating nodes cannot sniff packets send to
-other nodes or spoof packets as if sent from other nodes.
-.PP
-\&\*(L"Network\*(R" 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.
+Private means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
+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 \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 "\(bu" 4
.IX Xref "Network"
-.Sh "\s-1DESIGN\s0 \s-1GOALS\s0"
-.IX Subsection "DESIGN GOALS"
+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, which in turn can be used to build larger
+networks.
+.Sp
+\&\s-1GVPE\s0 provides a true multi-point network in wich 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
@@ -191,22 +212,27 @@
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:
+Here are a few recipes for compiling your gvpe, showing the extremes
+(fast, small, insecure \s-1OR\s0 slow, large, more secure), between 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
.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 easy, though.
.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
.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.
.Sh "\s-1MAXIMIZE\s0 \s-1SECURITY\s0"
.IX Subsection "MAXIMIZE SECURITY"
.Vb 1
@@ -215,7 +241,9 @@
.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.
+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.
.PP
In general, remember that \s-1AES\-128\s0 seems to be more secure and faster than
\&\s-1AES\-192\s0 or \s-1AES\-256\s0, more randomness helps against sniffing and a longer
@@ -340,11 +368,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-depedendent 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 mailinglist, 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