--- gvpe/doc/gvpe.5.pod 2005/01/27 06:58:48 1.3 +++ gvpe/doc/gvpe.5.pod 2013/07/10 01:51:40 1.10 @@ -5,43 +5,65 @@ =head1 DESCRIPTION GVPE is a suite designed to provide a virtual private network for multiple -nodes over an untrusted network. +nodes over an untrusted network. This document first gives an introduction +to VPNs in general and then describes the specific implementation of GVPE. + +=head2 WHAT IS A VPN? + +VPN is an acronym, it stands for: =over 4 -=item X +=item Virtual -Virtual means that no physical network is created (of course), but an -ethernet is emulated by creating multiple tunnels between the member -nodes. +Virtual means that no physical network is created (of course), but a +network is I 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. -=item X +=item Private Private means that non-participating nodes cannot decode ("sniff)" nor -inject ("spoof") packets. +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. +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. -=item X +=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 "vpn" solutions only create -point-to-point tunnels. +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 which any number of nodes (at +least a few dozen in practise, the theoretical limit is 4095 nodes) can +participate. =back -=head2 DESIGN GOALS +=head2 GVPE DESIGN GOALS -=over 4 +=over 4 =item 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. =item EASY TO SETUP @@ -61,20 +83,20 @@ =head1 PROGRAMS -Vpe comes with two programs: one daemon (C) and one control program +Gvpe comes with two programs: one daemon (C) and one control program (C). =over 4 =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.). =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 VPN subnet. =back @@ -83,35 +105,44 @@ Please have a look at the C manpage for platform-specific information. -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. + +Here are a few recipes for compiling your gvpe, showing the extremes +(fast, small, insecure OR slow, large, more secure), between which you +should choose: =head2 AS LOW PACKET OVERHEAD AS POSSIBLE ./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). +Minimize the header overhead of VPN packets (the above will result in +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 pretty easy. =head2 MINIMIZE CPU TIME REQUIRED ./configure --enable-cipher=bf --enable-digest=md4 -Use the fastest cipher and digest algorithms currently available in gvpe. +Use the fastest cipher and digest algorithms currently available in +gvpe. MD4 has been broken and is quite insecure, though, so using another +digest algorithm is recommended. =head2 MAXIMIZE SECURITY - ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 + ./configure --enable-hmac-length=16 --enable-rand-length=16 --enable-digest=sha384 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. In the long run, people should move to -SHA-224 and beyond, but support in openssl is missing as of writing this -document. +with 16 bytes of random data. -In general, remember that AES-128 seems to be more secure and faster than +In general, remember that AES-128 seems to be as secure but faster than AES-192 or AES-256, more randomness helps against sniffing and a longer -HMAC helps against spoofing. MD4 is a fast digest, SHA1 or RIPEMD160 are -better, and Blowfish is a fast cipher (and also quite secure). +HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256 +are consecutively better, and Blowfish is a fast cipher (and also quite +secure). =head1 HOW TO SET UP A SIMPLE VPN @@ -120,9 +151,9 @@ =head2 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 C, depending on how you -configured gvpe, and can be overwritten using the C<-c> commandline switch. +configured gvpe, and can be overwritten using the C<-c> command line switch. Put the following lines into C: @@ -139,9 +170,9 @@ node = third hostname = third.example.net -The only other file neccessary if the C script that initializes the -local ethernet interface. Put the following lines into C -and make it execute (C): +The only other file necessary is the C script that initializes the +virtual ethernet interface on the local host. Put the following lines into +C and make it executable (C): #!/bin/sh ip link set $IFNAME address $MAC mtu $MTU up @@ -151,19 +182,19 @@ ip route add 10.0.0.0/16 dev $IFNAME This script will give each node a different IP address in the C<10.0/16> -network. The internal network (e.g. the C 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. C<10.0.1.0/24> on node C, C<10.0.2.0/24> on node C, and so on. By enabling routing on the gateway host that runs C 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 ARP +or other means of pseudo-bridging, or (best) full routing - the choice is +yours. =head2 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): gvpectrl -c /etc/gvpe -g @@ -173,8 +204,11 @@ =head2 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). + +The example uses rsync-over-ssh First all the config files without the hostkeys should be distributed: @@ -188,25 +222,25 @@ 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 C on each node and verify it's output. =head2 STEP 4: starting gvpe You should then start gvpe on each node by issuing a command like: - gvpe -D -linfo first # first is the nodename + gvpe -D -l info first # first is the nodename -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 "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 gvpe run more permanently you can either run it as a daemon -(by starting it without the C<-D> 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 C<-D> switch), or, much better, from your inittab +or equivalent. I use a line like this on all my systems: t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1 @@ -220,12 +254,16 @@ =head1 SEE ALSO -gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8), and -for a description of the protocol and routing algorithms, gvpe.protocol(7). +gvpe.osdep(5) for OS-dependent information, gvpe.conf(5), gvpectrl(8), +and for a description of the transports, protocol, and routing algorithm, +gvpe.protocol(7). + +The GVPE mailing list, at L, or +C. =head1 AUTHOR -Marc Lehmann +Marc Lehmann =head1 COPYRIGHTS AND LICENSES