--- gvpe/README 2004/06/07 03:21:16 1.6 +++ gvpe/README 2005/03/18 01:53:05 1.8 @@ -6,65 +6,95 @@ ==== 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 ==== - Please have a look at the ``vpe.osdep(5)'' manpage for platform-specific - information. + Please have a look at the ``gvpe.osdep(5)'' manpage for + platform-specific information. - Here are a few recipes for compiling your vpe: + 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 == @@ -72,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 == @@ -88,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 @@ -106,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 @@ -127,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 @@ -141,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. @@ -152,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 == @@ -167,88 +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.osdep(5) for OS-depedendent information, vped.conf(5), vpectrl(8), - and for a description of the protocol and routing algorithms, - vpe.protocol(7). + 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 ==== - Vpe itself is distributed under the GENERAL PUBLIC LICENSE (see the file - COPYING that should be part of your distribution). + 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. - In some configurations (notably darwin), it uses a poll emulation - library that comes with the following license notice: - - Copyright (c) 1995-2002 Brian M. Clapper - All rights reserved. - - Redistribution and use in source and binary forms are permitted - provided that: (1) source distributions retain this entire - copyright notice and comment; (2) modifications made to the - software are prominently mentioned, and a copy of the original - software (or a pointer to its location) are included; and (3) - distributions including binaries display the following - acknowledgement: "This product includes software developed by Brian - M. Clapper " in the documentation or other - materials provided with the distribution. The name of the author - may not be used to endorse or promote products derived from this - software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED - WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. -