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