--- gvpe/README 2003/03/28 20:30:54 1.5
+++ gvpe/README 2005/03/18 01:53:05 1.8
@@ -1,67 +1,100 @@
==== NAME ====
- vpe - Overview of the virtual private ethernet suite.
+ GNU-VPE - Overview of the GNU Virtual Private Ethernet suite.
==== DESCRIPTION ====
- Vpe is a suite designed to provide a virtual private network for
- multiple nodes over an untrusted network.
+ GVPE is a suite designed to provide a virtual private network for
+ multiple nodes over an untrusted network. This document first gives an
+ introduction to VPNs in general and then describes the specific
+ implementation of GVPE.
- "Virtual" means that no physical network is created (of course), but an
- ethernet is emulated by creating multiple tunnels between the member
- nodes.
- "Private" means that non-participating nodes cannot decode ("sniff)" nor
- inject ("spoof") packets.
+== WHAT IS A VPN? ==
- In the case of vpe, even participating nodes cannot sniff packets send
- to other nodes or spoof packets as if sent from other nodes.
+ VPN is an acronym, it stands for:
- "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 "vpn" solutions only
- create point-to-point tunnels.
+: Virtual means that no physical network is created (of course), but a
+ network is *emulated* by creating multiple tunnels between the
+ member nodes by encapsulating and sending data over another
+ transport network.
+ Usually the emulated network is a normal IP or Ethernet, and the
+ transport network is the Internet. However, using a VPN system like
+ GVPE to connect nodes over other untrusted networks such as Wireless
+ LAN is not uncommon.
-== DESIGN GOALS ==
+: Private means that non-participating nodes cannot decode ("sniff)"
+ nor inject ("spoof") 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.
+
+ In the case of GVPE, 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.
+
+: 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 "vpn" solutions
+ only create point-to-point tunnels, which in turn can be used to
+ build larger networks.
+
+ GVPE 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.
+
+
+== GVPE DESIGN GOALS ==
: SIMPLE DESIGN
Cipher, HMAC 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. GVPE
+ 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.
: EASY TO SETUP
A few lines of config (the config file is shared unmodified between
- all hosts) and a single run of ``vpectrl'' to generate the keys
+ all hosts) and a single run of ``gvpectrl'' to generate the keys
suffices to make it work.
: MAC-BASED SECURITY
Since every host has it's own private key, other hosts cannot spoof
- traffic from this host. That makes it possible to filter packest by
+ traffic from this host. That makes it possible to filter packet by
MAC address, e.g. to ensure that packets from a specific IP address
- come, in fact, from a specific host.
+ come, in fact, from a specific host that is associated with that IP
+ and not from another host.
==== PROGRAMS ====
- Vpe comes with two programs: one daemon (``vped'') and one control
- program (``vpectrl'').
+ Vpe comes with two programs: one daemon (``gvpe'') and one control
+ program (``gvpectrl'').
-: vpectrl
+: gvpectrl
Is used to generate the keys, check and give an overview of of the
configuration and contorl the daemon (restarting etc.).
-: vped
- Is the daemon used to establish and maintain conenctions to the
+: gvpe
+ Is the daemon used to establish and maintain connections to the
other network members. It should be run on the gateway machine.
==== COMPILETIME CONFIGURATION ====
- Here are a few recipes for compiling your vpe:
+ Please have a look at the ``gvpe.osdep(5)'' manpage for
+ platform-specific information.
+
+ Here are a few recipes for compiling your gvpe, showing the extremes
+ (fast, small, insecure OR slow, large, more secure), between you should
+ choose:
== AS LOW PACKET OVERHEAD AS POSSIBLE ==
@@ -69,14 +102,17 @@
./configure --enable-hmac-length=4 --enable-rand-length=0
Minimize the header overhead of VPN packets (the above will result in
- only 4 bytes of overhead over the raw ethernet frame).
+ only 4 bytes of overhead over the raw ethernet frame). This is a
+ insecure configuration because a HMAC length of 4 makes collision
+ attacks based on the birthday paradox easy, though.
== MINIMIZE CPU TIME REQUIRED ==
./configure --enable-cipher=bf --enable-digest=md4
- Use the fastest cipher and digest algorithms currently available in vpe.
+ Use the fastest cipher and digest algorithms currently available in
+ gvpe. MD4 has been broken and is quite insecure, though.
== MAXIMIZE SECURITY ==
@@ -85,7 +121,9 @@
This uses a 16 byte HMAC 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
+ SHA-224 and beyond, but support in openssl is missing as of writing this
+ document.
In general, remember that AES-128 seems to be more secure and faster
than AES-192 or AES-256, more randomness helps against sniffing and a
@@ -103,11 +141,11 @@
== STEP 1: configuration ==
First you have to create a daemon configuation file and put it into the
- configuration directory. This is usually ``/etc/vpe'', depending on how
- you configured vpe, and can be overwritten using the ``-c'' commandline
+ configuration directory. This is usually ``/etc/gvpe'', depending on how
+ you configured gvpe, and can be overwritten using the ``-c'' commandline
switch.
- Put the following lines into ``/etc/vpe/vped.conf'':
+ Put the following lines into ``/etc/gvpe/gvpe.conf'':
udp-port = 50000 # the external port to listen on (configure your firewall)
mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
@@ -124,7 +162,7 @@
The only other file neccessary if the ``if-up'' script that initializes
the local ethernet interface. Put the following lines into
- ``/etc/vpe/if-up'' and make it execute (``chmod 755 /etc/vpe/if-up''):
+ ``/etc/gvpe/if-up'' and make it execute (``chmod 755 /etc/gvpe/if-up''):
#!/bin/sh
ip link set $IFNAME address $MAC mtu $MTU up
@@ -138,7 +176,7 @@
should then be set to a subset of that network, e.g. ``10.0.1.0/24'' on
node ``first'', ``10.0.2.0/24'' on node ``second'', and so on.
- By enabling routing on the gateway host that runs ``vped'' all nodes
+ By enabling routing on the gateway host that runs ``gvpe'' 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.
@@ -149,11 +187,11 @@
Run the following command to generate all key pairs (that might take a
while):
- vpectrl -c /etc/vpe -g
+ gvpectrl -c /etc/gvpe -g
This command will put the public keys into
- ``/etc/vpe/pubkeys/*nodename*'' and the private keys into
- ``/etc/vpe/hostkeys/*nodename*''.
+ ``/etc/gvpe/pubkeys/*nodename*'' and the private keys into
+ ``/etc/gvpe/hostkeys/*nodename*''.
== STEP 3: distribute the config files to all nodes ==
@@ -164,55 +202,69 @@
First all the config files without the hostkeys should be distributed:
- rsync -avzessh /etc/vpe first.example.net:/etc/. --exclude hostkeys
- rsync -avzessh /etc/vpe 133.55.82.9:/etc/. --exclude hostkeys
- rsync -avzessh /etc/vpe 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
Then the hostkeys should be copied:
- rsync -avzessh /etc/vpe/hostkeys/first first.example.net:/etc/hostkey
- rsync -avzessh /etc/vpe/hostkeys/second 133.55.82.9:/etc/hostkey
- rsync -avzessh /etc/vpe/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
- You should now check the configration by issuing the command ``vpectrl
- -c /etc/vpe -s'' on each node and verify it's output.
+ You should now check the configration by issuing the command ``gvpectrl
+ -c /etc/gvpe -s'' on each node and verify it's output.
-== STEP 4: starting vped ==
+== STEP 4: starting gvpe ==
- You should then start vped on each node by issuing a command like:
+ You should then start gvpe on each node by issuing a command like:
- vped -D -linfo first # first is the nodename
+ gvpe -D -linfo first # first is the nodename
- This will make the vped stay in foreground. You should then see
+ This will make the gvpe stay in foreground. You should then see
"connection established" messages. If you don't see them check your
firewall and routing (use tcpdump ;).
If this works you should check your networking setup by pinging various
endpoints.
- To make vped run more permanently you can either run it as a daemon (by
+ To make gvpe run more permanently you can either run it as a daemon (by
starting it without the ``-D'' switch), or, much better, from your
inittab. I use a line like this on my systems:
- t1:2345:respawn:/opt/vpe/sbin/vped -D -L first >/dev/null 2>&1
+ t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
== STEP 5: enjoy ==
- ... and play around. Sending a -HUP (``vpectrl -kHUP'') to the daemon
+ ... and play around. Sending a -HUP (``gvpectrl -kHUP'') to the daemon
will make it try to connect to all other nodes again. If you run it from
- inittab, as is recommended, ``vpectrl -k'' (or simply ``killall vped'')
+ inittab, as is recommended, ``gvpectrl -k'' (or simply ``killall gvpe'')
will kill the daemon, start it again, making it read it's configuration
files again.
==== SEE ALSO ====
- vpe(5), vped.conf(5), vpectrl(8).
+ gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8),
+ and for a description of the transports, protocol, and routing
+ algorithm, gvpe.protocol(7).
+
+ The GVPE mailinglist, at , or
+ ``gvpe@lists.schmorp.de''.
==== AUTHOR ====
- Marc Lehmann
+ Marc Lehmann
+
+
+==== COPYRIGHTS AND LICENSES ====
+
+ GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the
+ file COPYING that should be part of your distribution).
+
+ In some configurations it uses modified versions of the tinc vpn suite,
+ which is also available under the GENERAL PUBLIC LICENSE.