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