ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.5.pod
(Generate patch)

Comparing gvpe/doc/gvpe.5.pod (file contents):
Revision 1.2 by pcg, Tue Oct 12 11:54:33 2004 UTC vs.
Revision 1.8 by pcg, Mon Sep 1 05:31:28 2008 UTC

… …
3GNU-VPE - Overview of the GNU Virtual Private Ethernet suite. 3GNU-VPE - Overview of the GNU Virtual Private Ethernet suite.
4 4
5=head1 DESCRIPTION 5=head1 DESCRIPTION
6 6
7GVPE is a suite designed to provide a virtual private network for multiple 7GVPE is a suite designed to provide a virtual private network for multiple
8nodes over an untrusted network. 8nodes over an untrusted network. This document first gives an introduction
9to VPNs in general and then describes the specific implementation of GVPE.
9 10
11=head2 WHAT IS A VPN?
12
13VPN is an acronym, it stands for:
14
15=over 4
16
17=item X<Virtual>
18
10"Virtual"X<Virtual> means that no physical network is created (of course), but an 19Virtual means that no physical network is created (of course), but a
11ethernet is emulated by creating multiple tunnels between the member 20network is I<emulated> by creating multiple tunnels between the member
21nodes by encapsulating and sending data over another transport network.
22
23Usually the emulated network is a normal IP or Ethernet, and the transport
24network is the Internet. However, using a VPN system like GVPE to connect
25nodes over other untrusted networks such as Wireless LAN is not uncommon.
26
27=item X<Private>
28
29Private means that non-participating nodes cannot decode ("sniff)" nor
30inject ("spoof") packets. This means that nodes can be connected over
31untrusted networks such as the public Internet without fear of being
32eavesdropped while at the same time being able to trust data sent by other
12nodes. 33nodes.
13 34
14"Private"X<Private> means that non-participating nodes cannot decode ("sniff)" nor
15inject ("spoof") packets.
16
17In the case of gvpe, even participating nodes cannot sniff packets send to 35In the case of GVPE, even participating nodes cannot sniff packets
18other nodes or spoof packets as if sent from other nodes. 36send to other nodes or spoof packets as if sent from other nodes, so
37communications between any two nodes is private to those two nodes.
19 38
39=item X<Network>
40
20"Network"X<Network> means that more than two parties can participate in the 41Network means that more than two parties can participate in the network,
21network, so for instance it's possible to connect multiple branches of a 42so for instance it's possible to connect multiple branches of a company
22company into a single network. Many so-called "vpn" solutions only create 43into a single network. Many so-called "VPN" solutions only create
23point-to-point tunnels. 44point-to-point tunnels, which in turn can be used to build larger
45networks.
24 46
47GVPE provides a true multi-point network in which any number of nodes (at
48least a few dozen in practise, the theoretical limit is 4095 nodes) can
49participate.
50
51=back
52
25=head2 DESIGN GOALS 53=head2 GVPE DESIGN GOALS
26 54
27=over 4 55=over 4
28 56
29=item SIMPLE DESIGN 57=item SIMPLE DESIGN
30 58
31Cipher, HMAC algorithms and other key parameters must be selected 59Cipher, HMAC algorithms and other key parameters must be selected
32at compile time - this makes it possible to only link in algorithms 60at compile time - this makes it possible to only link in algorithms
33you actually need. It also makes the crypto part of the source very 61you actually need. It also makes the crypto part of the source very
34transparent and easy to inspect. 62transparent and easy to inspect, and last not least this makes it possible
63to hardcode the layout of all packets into the binary. GVPE goes a step
64further and internally reserves blocks of the same length for all packets,
65which virtually removes all possibilities of buffer overflows, as there is
66only a single type of buffer and it's always of fixed length.
35 67
36=item EASY TO SETUP 68=item EASY TO SETUP
37 69
38A few lines of config (the config file is shared unmodified between all 70A few lines of config (the config file is shared unmodified between all
39hosts) and a single run of C<gvpectrl> to generate the keys suffices to 71hosts) and a single run of C<gvpectrl> to generate the keys suffices to
… …
49 81
50=back 82=back
51 83
52=head1 PROGRAMS 84=head1 PROGRAMS
53 85
54Vpe comes with two programs: one daemon (C<gvpe>) and one control program 86Gvpe comes with two programs: one daemon (C<gvpe>) and one control program
55(C<gvpectrl>). 87(C<gvpectrl>).
56 88
57=over 4 89=over 4
58 90
59=item gvpectrl 91=item gvpectrl
60 92
61Is used to generate the keys, check and give an overview of of the 93This program is used to generate the keys, check and give an overview of of the
62configuration and contorl the daemon (restarting etc.). 94configuration and to control the daemon (restarting etc.).
63 95
64=item gvpe 96=item gvpe
65 97
66Is the daemon used to establish and maintain connections to the other 98This is the daemon used to establish and maintain connections to the other
67network members. It should be run on the gateway machine. 99network nodes. It should be run on the gateway of each VPN subnet.
68 100
69=back 101=back
70 102
71=head1 COMPILETIME CONFIGURATION 103=head1 COMPILETIME CONFIGURATION
72 104
73Please have a look at the C<gvpe.osdep(5)> manpage for platform-specific 105Please have a look at the C<gvpe.osdep(5)> manpage for platform-specific
74information. 106information.
75 107
108Gvpe hardcodes most encryption parameters. While this reduces flexibility,
109it makes the program much simpler and helps making buffer overflows
110impossible under most circumstances.
111
76Here are a few recipes for compiling your gvpe: 112Here are a few recipes for compiling your gvpe, showing the extremes
113(fast, small, insecure OR slow, large, more secure), between which you
114should choose:
77 115
78=head2 AS LOW PACKET OVERHEAD AS POSSIBLE 116=head2 AS LOW PACKET OVERHEAD AS POSSIBLE
79 117
80 ./configure --enable-hmac-length=4 --enable-rand-length=0 118 ./configure --enable-hmac-length=4 --enable-rand-length=0
81 119
82Minimize the header overhead of VPN packets (the above will result in only 120Minimize the header overhead of VPN packets (the above will result in
834 bytes of overhead over the raw ethernet frame). 121only 4 bytes of overhead over the raw ethernet frame). This is a insecure
122configuration because a HMAC length of 4 makes collision attacks based on
123the birthday paradox pretty easy.
84 124
85=head2 MINIMIZE CPU TIME REQUIRED 125=head2 MINIMIZE CPU TIME REQUIRED
86 126
87 ./configure --enable-cipher=bf --enable-digest=md4 127 ./configure --enable-cipher=bf --enable-digest=md4
88 128
89Use the fastest cipher and digest algorithms currently available in gvpe. 129Use the fastest cipher and digest algorithms currently available in
130gvpe. MD4 has been broken and is quite insecure, though, so using another
131digest algorithm is recommended.
90 132
91=head2 MAXIMIZE SECURITY 133=head2 MAXIMIZE SECURITY
92 134
93 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1 135 ./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1
94 136
95This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 137This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12
96would also be pretty secure ;) and will additionally prefix each packet 138would also be pretty secure ;) and will additionally prefix each packet
97with 8 bytes of random data. In the long run, people should move to 139with 8 bytes of random data. In the long run, people should move to
98SHA-224 and beyond, but support in openssl is missing as of writing this 140SHA-256 and beyond).
99document.
100 141
101In general, remember that AES-128 seems to be more secure and faster than 142In general, remember that AES-128 seems to be as secure but faster than
102AES-192 or AES-256, more randomness helps against sniffing and a longer 143AES-192 or AES-256, more randomness helps against sniffing and a longer
103HMAC helps against spoofing. MD4 is a fast digest, SHA1 or RIPEMD160 are 144HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256
104better, and Blowfish is a fast cipher (and also quite secure). 145are consecutively better, and Blowfish is a fast cipher (and also quite
146secure).
105 147
106=head1 HOW TO SET UP A SIMPLE VPN 148=head1 HOW TO SET UP A SIMPLE VPN
107 149
108In this section I will describe how to get a simple VPN consisting of 150In this section I will describe how to get a simple VPN consisting of
109three hosts up and running. 151three hosts up and running.
110 152
111=head2 STEP 1: configuration 153=head2 STEP 1: configuration
112 154
113First you have to create a daemon configuation file and put it into the 155First you have to create a daemon configuration file and put it into the
114configuration directory. This is usually C</etc/gvpe>, depending on how you 156configuration directory. This is usually C</etc/gvpe>, depending on how you
115configured gvpe, and can be overwritten using the C<-c> commandline switch. 157configured gvpe, and can be overwritten using the C<-c> command line switch.
116 158
117Put the following lines into C</etc/gvpe/gvpe.conf>: 159Put the following lines into C</etc/gvpe/gvpe.conf>:
118 160
119 udp-port = 50000 # the external port to listen on (configure your firewall) 161 udp-port = 50000 # the external port to listen on (configure your firewall)
120 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts 162 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
… …
127 hostname = 133.55.82.9 169 hostname = 133.55.82.9
128 170
129 node = third 171 node = third
130 hostname = third.example.net 172 hostname = third.example.net
131 173
132The only other file neccessary if the C<if-up> script that initializes the 174The only other file necessary is the C<if-up> script that initializes the
133local ethernet interface. Put the following lines into C</etc/gvpe/if-up> 175virtual ethernet interface on the local host. Put the following lines into
134and make it execute (C<chmod 755 /etc/gvpe/if-up>): 176C</etc/gvpe/if-up> and make it executable (C<chmod 755 /etc/gvpe/if-up>):
135 177
136 #!/bin/sh 178 #!/bin/sh
137 ip link set $IFNAME address $MAC mtu $MTU up 179 ip link set $IFNAME address $MAC mtu $MTU up
138 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME 180 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
139 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME 181 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
140 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME 182 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
141 ip route add 10.0.0.0/16 dev $IFNAME 183 ip route add 10.0.0.0/16 dev $IFNAME
142 184
143This script will give each node a different IP address in the C<10.0/16> 185This script will give each node a different IP address in the C<10.0/16>
144network. The internal network (e.g. the C<eth0> interface) should then be 186network. The internal network (if gvpe runs on a router) should then be
145set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>, 187set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>,
146C<10.0.2.0/24> on node C<second>, and so on. 188C<10.0.2.0/24> on node C<second>, and so on.
147 189
148By enabling routing on the gateway host that runs C<gvpe> all nodes will 190By enabling routing on the gateway host that runs C<gvpe> all nodes will
149be able to reach the other nodes. You can, of course, also use proxy arp 191be able to reach the other nodes. You can, of course, also use proxy ARP
150or other means of pseudo-bridging (or even real briding), or (best) full 192or other means of pseudo-bridging, or (best) full routing - the choice is
151routing - the choice is yours. 193yours.
152 194
153=head2 STEP 2: create the RSA key pairs for all hosts 195=head2 STEP 2: create the RSA key pairs for all hosts
154 196
155Run the following command to generate all key pairs (that might take a 197Run the following command to generate all key pairs for all nodes (that
156while): 198might take a while):
157 199
158 gvpectrl -c /etc/gvpe -g 200 gvpectrl -c /etc/gvpe -g
159 201
160This command will put the public keys into C<< 202This command will put the public keys into C<<
161/etc/gvpe/pubkeys/I<nodename> >> and the private keys into C<< 203/etc/gvpe/pubkeys/I<nodename> >> and the private keys into C<<
162/etc/gvpe/hostkeys/I<nodename> >>. 204/etc/gvpe/hostkeys/I<nodename> >>.
163 205
164=head2 STEP 3: distribute the config files to all nodes 206=head2 STEP 3: distribute the config files to all nodes
165 207
166Now distribute the config files to the other nodes. This should be done in two steps, since the 208Now distribute the config files and private keys to the other nodes. This
167private keys should not be distributed. The example uses rsync-over-ssh 209should be done in two steps, since only the private keys meant for a node
210should be distributed (so each node has only it's own private key).
211
212The example uses rsync-over-ssh
168 213
169First all the config files without the hostkeys should be distributed: 214First all the config files without the hostkeys should be distributed:
170 215
171 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys 216 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys
172 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys 217 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys
… …
176 221
177 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey 222 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
178 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey 223 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
179 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey 224 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
180 225
181You should now check the configration by issuing the command C<gvpectrl -c 226You should now check the configuration by issuing the command C<gvpectrl -c
182/etc/gvpe -s> on each node and verify it's output. 227/etc/gvpe -s> on each node and verify it's output.
183 228
184=head2 STEP 4: starting gvpe 229=head2 STEP 4: starting gvpe
185 230
186You should then start gvpe on each node by issuing a command like: 231You should then start gvpe on each node by issuing a command like:
187 232
188 gvpe -D -linfo first # first is the nodename 233 gvpe -D -l info first # first is the nodename
189 234
190This will make the gvpe stay in foreground. You should then see 235This will make the gvpe daemon stay in foreground. You should then see
191"connection established" messages. If you don't see them check your 236"connection established" messages. If you don't see them check your
192firewall and routing (use tcpdump ;). 237firewall and routing (use tcpdump ;).
193 238
194If this works you should check your networking setup by pinging various 239If this works you should check your networking setup by pinging various
195endpoints. 240endpoints.
196 241
197To make gvpe run more permanently you can either run it as a daemon 242To make gvpe run more permanently you can either run it as a daemon (by
198(by starting it without the C<-D> switch), or, much better, from your 243starting it without the C<-D> switch), or, much better, from your inittab
199inittab. I use a line like this on my systems: 244or equivalent. I use a line like this on all my systems:
200 245
201 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1 246 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
202 247
203=head2 STEP 5: enjoy 248=head2 STEP 5: enjoy
204 249
… …
208kill the daemon, start it again, making it read it's configuration files 253kill the daemon, start it again, making it read it's configuration files
209again. 254again.
210 255
211=head1 SEE ALSO 256=head1 SEE ALSO
212 257
213gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8), and 258gvpe.osdep(5) for OS-dependent information, gvpe.conf(5), gvpectrl(8),
214for a description of the protocol and routing algorithms, gvpe.protocol(7). 259and for a description of the transports, protocol, and routing algorithm,
260gvpe.protocol(7).
261
262The GVPE mailing list, at L<http://lists.schmorp.de/>, or
263C<gvpe@lists.schmorp.de>.
215 264
216=head1 AUTHOR 265=head1 AUTHOR
217 266
218Marc Lehmann <gvpe@plan9.de> 267Marc Lehmann <gvpe@schmorp.de>
219 268
220=head1 COPYRIGHTS AND LICENSES 269=head1 COPYRIGHTS AND LICENSES
221 270
222GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file 271GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file
223COPYING that should be part of your distribution). 272COPYING that should be part of your distribution).

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines