ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.5.pod
Revision: 1.13
Committed: Wed Nov 2 06:58:35 2016 UTC (8 years, 1 month ago) by root
Branch: MAIN
CVS Tags: rel-3_0, HEAD
Changes since 1.12: +5 -6 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 =head1 NAME
2
3 GNU-VPE - Overview of the GNU Virtual Private Ethernet suite.
4
5 =head1 DESCRIPTION
6
7 GVPE is a suite designed to provide a virtual private network for multiple
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.
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
19 Virtual means that no physical network is created (of course), but a
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
33 nodes.
34
35 In the case of GVPE, even participating nodes cannot sniff packets
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.
38
39 =item Network
40
41 Network means that more than two parties can participate in the network,
42 so for instance it's possible to connect multiple branches of a company
43 into a single network. Many so-called "VPN" solutions only create
44 point-to-point tunnels, which in turn can be used to build larger
45 networks.
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
53 =head2 GVPE DESIGN GOALS
54
55 =over 4
56
57 =item SIMPLE DESIGN
58
59 Cipher, HMAC algorithms and other key parameters must be selected
60 at compile time - this makes it possible to only link in algorithms
61 you actually need. It also makes the crypto part of the source very
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.
67
68 =item EASY TO SETUP
69
70 A few lines of config (the config file is shared unmodified between all
71 hosts) and generating an RSA key-pair on each node suffices to make it
72 work.
73
74 =item MAC-BASED SECURITY
75
76 Since every host has it's own private key, other hosts cannot spoof
77 traffic from this host. That makes it possible to filter packet by MAC
78 address, e.g. to ensure that packets from a specific IP address come, in
79 fact, from a specific host that is associated with that IP and not from
80 another host.
81
82 =back
83
84 =head1 PROGRAMS
85
86 Gvpe comes with two programs: one daemon (C<gvpe>) and one control program
87 (C<gvpectrl>).
88
89 =over 4
90
91 =item gvpectrl
92
93 This program is used to generate the keys, check and give an overview of of the
94 configuration and to control the daemon (restarting etc.).
95
96 =item gvpe
97
98 This is the daemon used to establish and maintain connections to the other
99 network nodes. It should be run on the gateway of each VPN subnet.
100
101 =back
102
103 =head1 COMPILETIME CONFIGURATION
104
105 Please have a look at the C<gvpe.osdep(5)> manpage for platform-specific
106 information.
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
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:
115
116 =head2 AS LOW PACKET OVERHEAD AS POSSIBLE
117
118 ./configure --enable-hmac-length=4 --enable-rand-length=0
119
120 Minimize the header overhead of VPN packets (the above will result in
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.
124
125 =head2 MINIMIZE CPU TIME REQUIRED
126
127 ./configure --enable-cipher=bf --enable-digest=md4
128
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.
132
133 =head2 MAXIMIZE SECURITY
134
135 ./configure --enable-hmac-length=16 --enable-rand-length=12 --enable-digest=ripemd610
136
137 This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12
138 would also be pretty secure ;) and will additionally prefix each packet
139 with 12 bytes of random data.
140
141 In general, remember that AES-128 seems to be as secure but faster than
142 AES-192 or AES-256, more randomness helps against sniffing and a longer
143 HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256
144 are consecutively better, and Blowfish is a fast cipher (and also quite
145 secure).
146
147 =head1 HOW TO SET UP A SIMPLE VPN
148
149 In this section I will describe how to get a simple VPN consisting of
150 three hosts up and running.
151
152 =head2 STEP 1: configuration
153
154 First you have to create a daemon configuration file and put it into the
155 configuration directory. This is usually C</etc/gvpe>, depending on how you
156 configured gvpe, and can be overwritten using the C<-c> command line switch.
157
158 Put the following lines into C</etc/gvpe/gvpe.conf>:
159
160 udp-port = 50000 # the external port to listen on (configure your firewall)
161 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
162 ifname = vpn0 # the local network device name
163
164 node = first # just a nickname
165 hostname = first.example.net # the DNS name or IP address of the host
166
167 node = second
168 hostname = 133.55.82.9
169
170 node = third
171 hostname = third.example.net
172
173 The only other file necessary is the C<if-up> script that initializes the
174 virtual ethernet interface on the local host. Put the following lines into
175 C</etc/gvpe/if-up> and make it executable (C<chmod 755 /etc/gvpe/if-up>):
176
177 #!/bin/sh
178 ip link set $IFNAME address $MAC mtu $MTU up
179 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
180 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
181 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
182 ip route add 10.0.0.0/16 dev $IFNAME
183
184 This script will give each node a different IP address in the C<10.0/16>
185 network. The internal network (if gvpe runs on a router) should then be
186 set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>,
187 C<10.0.2.0/24> on node C<second>, and so on.
188
189 By enabling routing on the gateway host that runs C<gvpe> all nodes will
190 be able to reach the other nodes. You can, of course, also use proxy ARP
191 or other means of pseudo-bridging, or (best) full routing - the choice is
192 yours.
193
194 =head2 STEP 2: create the RSA key pair for each node
195
196 Next you have to generate the RSA keys for the nodes. While you can set
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.
201
202 To do so, run the following command to generate a key pair:
203
204 gvpectrl -c /etc/gvpe -g nodekey
205
206 This will create two files, F<nodekey> and F<nodekey.privkey>. The former
207 should be copied to F<< /etc/gvpe/pubkey/I<nodename> >> on the host where
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
217
218 =head2 STEP 3: distribute the config files to all nodes
219
220 Now distribute the config files and public keys to the other nodes.
221
222 The example uses rsync-over-ssh to copy the config file and all the public
223 keys:
224
225 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkey
226 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkey
227 rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkey
228
229 You should now check the configuration by issuing the command C<gvpectrl
230 -c /etc/gvpe -s> on each node and verify it's output.
231
232 =head2 STEP 4: starting gvpe
233
234 You should then start gvpe on each node by issuing a command like:
235
236 gvpe -D -l info first # first is the nodename
237
238 This will make the gvpe daemon stay in foreground. You should then see
239 "connection established" messages. If you don't see them check your
240 firewall and routing (use tcpdump ;).
241
242 If this works you should check your networking setup by pinging various
243 endpoints.
244
245 To make gvpe run more permanently you can either run it as a daemon (by
246 starting it without the C<-D> switch), or, much better, from your inittab
247 or equivalent. I use a line like this on all my systems:
248
249 t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1
250
251 =head2 STEP 5: enjoy
252
253 ... and play around. Sending a -HUP (C<gvpectrl -kHUP>) to the daemon
254 will make it try to connect to all other nodes again. If you run it from
255 inittab C<gvpectrl -k> (or simply C<killall gvpe>) will kill the daemon,
256 start it again, making it read it's configuration files again.
257
258 To run the GVPE daemon permanently from your SysV init, you can add it to
259 your F<inittab>, e.g.:
260
261 t1:2345:respawn:/bin/sh -c "exec nice -n-20 /path/to/gvpe -D node >/var/log/gvpe.log 2>&1"
262
263 For systems using systemd, you can use a unit file similar to this one:
264
265 [Unit]
266 Description=gvpe
267 After=network.target
268 Before=remote-fs.target
269
270 [Service]
271 ExecStart=/path/to/gvpe -D node
272 KillMode=process
273 Restart=always
274
275 [Install]
276 WantedBy=multi-user.target
277
278 =head1 SEE ALSO
279
280 gvpe.osdep(5) for OS-dependent information, gvpe.conf(5), gvpectrl(8),
281 and for a description of the transports, protocol, and routing algorithm,
282 gvpe.protocol(7).
283
284 The GVPE mailing list, at L<http://lists.schmorp.de/>, or
285 C<gvpe@lists.schmorp.de>.
286
287 =head1 AUTHOR
288
289 Marc Lehmann <gvpe@schmorp.de>
290
291 =head1 COPYRIGHTS AND LICENSES
292
293 GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file
294 COPYING that should be part of your distribution).
295
296 In some configurations it uses modified versions of the tinc vpn suite,
297 which is also available under the GENERAL PUBLIC LICENSE.
298