ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.5
Revision: 1.13
Committed: Wed Mar 30 04:02:50 2016 UTC (8 years, 2 months ago) by root
Branch: MAIN
Changes since 1.12: +38 -29 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C`
34 . ds C'
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 . ds C`
42 . ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el .ds Aq '
48 .\"
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
60 . if \nF \{
61 . de IX
62 . tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 . if !\nF==2 \{
65 . nr % 0
66 . nr F 2
67 . \}
68 . \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
75 .if n \{\
76 . ds #H 0
77 . ds #V .8m
78 . ds #F .3m
79 . ds #[ \f1
80 . ds #] \fP
81 .\}
82 .if t \{\
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 . ds #V .6m
85 . ds #F 0
86 . ds #[ \&
87 . ds #] \&
88 .\}
89 . \" simple accents for nroff and troff
90 .if n \{\
91 . ds ' \&
92 . ds ` \&
93 . ds ^ \&
94 . ds , \&
95 . ds ~ ~
96 . ds /
97 .\}
98 .if t \{\
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 . ds : e
123 . ds 8 ss
124 . ds o a
125 . ds d- d\h'-1'\(ga
126 . ds D- D\h'-1'\(hy
127 . ds th \o'bp'
128 . ds Th \o'LP'
129 . ds ae ae
130 . ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "GVPE 5"
136 .TH GVPE 5 "2015-10-31" "2.25" "GNU Virtual Private Ethernet"
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 GNU\-VPE \- Overview of the GNU Virtual Private Ethernet suite.
143 .SH "DESCRIPTION"
144 .IX Header "DESCRIPTION"
145 \&\s-1GVPE\s0 is a suite designed to provide a virtual private network for multiple
146 nodes over an untrusted network. This document first gives an introduction
147 to VPNs in general and then describes the specific implementation of \s-1GVPE.\s0
148 .SS "\s-1WHAT IS A VPN\s0?"
149 .IX Subsection "WHAT IS A VPN?"
150 \&\s-1VPN\s0 is an acronym, it stands for:
151 .IP "Virtual" 4
152 .IX Item "Virtual"
153 Virtual means that no physical network is created (of course), but a
154 network is \fIemulated\fR by creating multiple tunnels between the member
155 nodes by encapsulating and sending data over another transport network.
156 .Sp
157 Usually the emulated network is a normal \s-1IP\s0 or Ethernet, and the transport
158 network is the Internet. However, using a \s-1VPN\s0 system like \s-1GVPE\s0 to connect
159 nodes over other untrusted networks such as Wireless \s-1LAN\s0 is not uncommon.
160 .IP "Private" 4
161 .IX Item "Private"
162 Private means that non-participating nodes cannot decode (\*(L"sniff)\*(R" nor
163 inject (\*(L"spoof\*(R") packets. This means that nodes can be connected over
164 untrusted networks such as the public Internet without fear of being
165 eavesdropped while at the same time being able to trust data sent by other
166 nodes.
167 .Sp
168 In the case of \s-1GVPE,\s0 even participating nodes cannot sniff packets
169 send to other nodes or spoof packets as if sent from other nodes, so
170 communications between any two nodes is private to those two nodes.
171 .IP "Network" 4
172 .IX Item "Network"
173 Network means that more than two parties can participate in the network,
174 so for instance it's possible to connect multiple branches of a company
175 into a single network. Many so-called \*(L"\s-1VPN\*(R"\s0 solutions only create
176 point-to-point tunnels, which in turn can be used to build larger
177 networks.
178 .Sp
179 \&\s-1GVPE\s0 provides a true multi-point network in which any number of nodes (at
180 least a few dozen in practise, the theoretical limit is 4095 nodes) can
181 participate.
182 .SS "\s-1GVPE DESIGN GOALS\s0"
183 .IX Subsection "GVPE DESIGN GOALS"
184 .IP "\s-1SIMPLE DESIGN\s0" 4
185 .IX Item "SIMPLE DESIGN"
186 Cipher, \s-1HMAC\s0 algorithms and other key parameters must be selected
187 at compile time \- this makes it possible to only link in algorithms
188 you actually need. It also makes the crypto part of the source very
189 transparent and easy to inspect, and last not least this makes it possible
190 to hardcode the layout of all packets into the binary. \s-1GVPE\s0 goes a step
191 further and internally reserves blocks of the same length for all packets,
192 which virtually removes all possibilities of buffer overflows, as there is
193 only a single type of buffer and it's always of fixed length.
194 .IP "\s-1EASY TO SETUP\s0" 4
195 .IX Item "EASY TO SETUP"
196 A few lines of config (the config file is shared unmodified between all
197 hosts) and a single run of \f(CW\*(C`gvpectrl\*(C'\fR to generate the keys suffices to
198 make it work.
199 .IP "MAC-BASED \s-1SECURITY\s0" 4
200 .IX Item "MAC-BASED SECURITY"
201 Since every host has it's own private key, other hosts cannot spoof
202 traffic from this host. That makes it possible to filter packet by \s-1MAC\s0
203 address, e.g. to ensure that packets from a specific \s-1IP\s0 address come, in
204 fact, from a specific host that is associated with that \s-1IP\s0 and not from
205 another host.
206 .SH "PROGRAMS"
207 .IX Header "PROGRAMS"
208 Gvpe comes with two programs: one daemon (\f(CW\*(C`gvpe\*(C'\fR) and one control program
209 (\f(CW\*(C`gvpectrl\*(C'\fR).
210 .IP "gvpectrl" 4
211 .IX Item "gvpectrl"
212 This program is used to generate the keys, check and give an overview of of the
213 configuration and to control the daemon (restarting etc.).
214 .IP "gvpe" 4
215 .IX Item "gvpe"
216 This is the daemon used to establish and maintain connections to the other
217 network nodes. It should be run on the gateway of each \s-1VPN\s0 subnet.
218 .SH "COMPILETIME CONFIGURATION"
219 .IX Header "COMPILETIME CONFIGURATION"
220 Please have a look at the \f(CW\*(C`gvpe.osdep(5)\*(C'\fR manpage for platform-specific
221 information.
222 .PP
223 Gvpe hardcodes most encryption parameters. While this reduces flexibility,
224 it makes the program much simpler and helps making buffer overflows
225 impossible under most circumstances.
226 .PP
227 Here are a few recipes for compiling your gvpe, showing the extremes
228 (fast, small, insecure \s-1OR\s0 slow, large, more secure), between which you
229 should choose:
230 .SS "\s-1AS LOW PACKET OVERHEAD AS POSSIBLE\s0"
231 .IX Subsection "AS LOW PACKET OVERHEAD AS POSSIBLE"
232 .Vb 1
233 \& ./configure \-\-enable\-hmac\-length=4 \-\-enable\-rand\-length=0
234 .Ve
235 .PP
236 Minimize the header overhead of \s-1VPN\s0 packets (the above will result in
237 only 4 bytes of overhead over the raw ethernet frame). This is a insecure
238 configuration because a \s-1HMAC\s0 length of 4 makes collision attacks almost
239 trivial.
240 .SS "\s-1MINIMIZE CPU TIME REQUIRED\s0"
241 .IX Subsection "MINIMIZE CPU TIME REQUIRED"
242 .Vb 1
243 \& ./configure \-\-enable\-cipher=bf \-\-enable\-digest=md4
244 .Ve
245 .PP
246 Use the fastest cipher and digest algorithms currently available in
247 gvpe. \s-1MD4\s0 has been broken and is quite insecure, though, so using another
248 digest algorithm is recommended.
249 .SS "\s-1MAXIMIZE SECURITY\s0"
250 .IX Subsection "MAXIMIZE SECURITY"
251 .Vb 1
252 \& ./configure \-\-enable\-hmac\-length=16 \-\-enable\-rand\-length=12 \-\-enable\-digest=ripemd610
253 .Ve
254 .PP
255 This uses a 16 byte \s-1HMAC\s0 checksum to authenticate packets (I guess 8\-12
256 would also be pretty secure ;) and will additionally prefix each packet
257 with 12 bytes of random data.
258 .PP
259 In general, remember that \s-1AES\-128\s0 seems to be as secure but faster than
260 \&\s-1AES\-192\s0 or \s-1AES\-256,\s0 more randomness helps against sniffing and a longer
261 \&\s-1HMAC\s0 helps against spoofing. \s-1MD4\s0 is a fast digest, \s-1SHA1, RIPEMD160, SHA256\s0
262 are consecutively better, and Blowfish is a fast cipher (and also quite
263 secure).
264 .SH "HOW TO SET UP A SIMPLE VPN"
265 .IX Header "HOW TO SET UP A SIMPLE VPN"
266 In this section I will describe how to get a simple \s-1VPN\s0 consisting of
267 three hosts up and running.
268 .SS "\s-1STEP 1:\s0 configuration"
269 .IX Subsection "STEP 1: configuration"
270 First you have to create a daemon configuration file and put it into the
271 configuration directory. This is usually \f(CW\*(C`/etc/gvpe\*(C'\fR, depending on how you
272 configured gvpe, and can be overwritten using the \f(CW\*(C`\-c\*(C'\fR command line switch.
273 .PP
274 Put the following lines into \f(CW\*(C`/etc/gvpe/gvpe.conf\*(C'\fR:
275 .PP
276 .Vb 3
277 \& udp\-port = 50000 # the external port to listen on (configure your firewall)
278 \& mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
279 \& ifname = vpn0 # the local network device name
280 \&
281 \& node = first # just a nickname
282 \& hostname = first.example.net # the DNS name or IP address of the host
283 \&
284 \& node = second
285 \& hostname = 133.55.82.9
286 \&
287 \& node = third
288 \& hostname = third.example.net
289 .Ve
290 .PP
291 The only other file necessary is the \f(CW\*(C`if\-up\*(C'\fR script that initializes the
292 virtual ethernet interface on the local host. Put the following lines into
293 \&\f(CW\*(C`/etc/gvpe/if\-up\*(C'\fR and make it executable (\f(CW\*(C`chmod 755 /etc/gvpe/if\-up\*(C'\fR):
294 .PP
295 .Vb 6
296 \& #!/bin/sh
297 \& ip link set $IFNAME address $MAC mtu $MTU up
298 \& [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
299 \& [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
300 \& [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
301 \& ip route add 10.0.0.0/16 dev $IFNAME
302 .Ve
303 .PP
304 This script will give each node a different \s-1IP\s0 address in the \f(CW\*(C`10.0/16\*(C'\fR
305 network. The internal network (if gvpe runs on a router) should then be
306 set to a subset of that network, e.g. \f(CW\*(C`10.0.1.0/24\*(C'\fR on node \f(CW\*(C`first\*(C'\fR,
307 \&\f(CW\*(C`10.0.2.0/24\*(C'\fR on node \f(CW\*(C`second\*(C'\fR, and so on.
308 .PP
309 By enabling routing on the gateway host that runs \f(CW\*(C`gvpe\*(C'\fR all nodes will
310 be able to reach the other nodes. You can, of course, also use proxy \s-1ARP\s0
311 or other means of pseudo-bridging, or (best) full routing \- the choice is
312 yours.
313 .SS "\s-1STEP 2:\s0 create the \s-1RSA\s0 key pairs for all hosts"
314 .IX Subsection "STEP 2: create the RSA key pairs for all hosts"
315 Run the following command to generate all key pairs for all nodes (that
316 might take a while):
317 .PP
318 .Vb 1
319 \& gvpectrl \-c /etc/gvpe \-g
320 .Ve
321 .PP
322 This command will put the public keys into \f(CW\*(C`/etc/gvpe/pubkeys/\f(CInodename\f(CW\*(C'\fR and the private keys into \f(CW\*(C`/etc/gvpe/hostkeys/\f(CInodename\f(CW\*(C'\fR.
323 .SS "\s-1STEP 3:\s0 distribute the config files to all nodes"
324 .IX Subsection "STEP 3: distribute the config files to all nodes"
325 Now distribute the config files and private keys to the other nodes. This
326 should be done in two steps, since only the private keys meant for a node
327 should be distributed (so each node has only it's own private key).
328 .PP
329 The example uses rsync-over-ssh
330 .PP
331 First all the config files without the hostkeys should be distributed:
332 .PP
333 .Vb 3
334 \& rsync \-avzessh /etc/gvpe first.example.net:/etc/. \-\-exclude hostkeys
335 \& rsync \-avzessh /etc/gvpe 133.55.82.9:/etc/. \-\-exclude hostkeys
336 \& rsync \-avzessh /etc/gvpe third.example.net:/etc/. \-\-exclude hostkeys
337 .Ve
338 .PP
339 Then the hostkeys should be copied:
340 .PP
341 .Vb 3
342 \& rsync \-avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
343 \& rsync \-avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
344 \& rsync \-avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
345 .Ve
346 .PP
347 You should now check the configuration by issuing the command \f(CW\*(C`gvpectrl \-c
348 /etc/gvpe \-s\*(C'\fR on each node and verify it's output.
349 .SS "\s-1STEP 4:\s0 starting gvpe"
350 .IX Subsection "STEP 4: starting gvpe"
351 You should then start gvpe on each node by issuing a command like:
352 .PP
353 .Vb 1
354 \& gvpe \-D \-l info first # first is the nodename
355 .Ve
356 .PP
357 This will make the gvpe daemon stay in foreground. You should then see
358 \&\*(L"connection established\*(R" messages. If you don't see them check your
359 firewall and routing (use tcpdump ;).
360 .PP
361 If this works you should check your networking setup by pinging various
362 endpoints.
363 .PP
364 To make gvpe run more permanently you can either run it as a daemon (by
365 starting it without the \f(CW\*(C`\-D\*(C'\fR switch), or, much better, from your inittab
366 or equivalent. I use a line like this on all my systems:
367 .PP
368 .Vb 1
369 \& t1:2345:respawn:/opt/gvpe/sbin/gvpe \-D \-L first >/dev/null 2>&1
370 .Ve
371 .SS "\s-1STEP 5:\s0 enjoy"
372 .IX Subsection "STEP 5: enjoy"
373 \&... and play around. Sending a \-HUP (\f(CW\*(C`gvpectrl \-kHUP\*(C'\fR) to the daemon
374 will make it try to connect to all other nodes again. If you run it from
375 inittab, as is recommended, \f(CW\*(C`gvpectrl \-k\*(C'\fR (or simply \f(CW\*(C`killall gvpe\*(C'\fR) will
376 kill the daemon, start it again, making it read it's configuration files
377 again.
378 .SH "SEE ALSO"
379 .IX Header "SEE ALSO"
380 \&\fIgvpe.osdep\fR\|(5) for OS-dependent information, \fIgvpe.conf\fR\|(5), \fIgvpectrl\fR\|(8),
381 and for a description of the transports, protocol, and routing algorithm,
382 \&\fIgvpe.protocol\fR\|(7).
383 .PP
384 The \s-1GVPE\s0 mailing list, at <http://lists.schmorp.de/>, or
385 \&\f(CW\*(C`gvpe@lists.schmorp.de\*(C'\fR.
386 .SH "AUTHOR"
387 .IX Header "AUTHOR"
388 Marc Lehmann <gvpe@schmorp.de>
389 .SH "COPYRIGHTS AND LICENSES"
390 .IX Header "COPYRIGHTS AND LICENSES"
391 \&\s-1GVPE\s0 itself is distributed under the \s-1GENERAL PUBLIC LICENSE \s0(see the file
392 \&\s-1COPYING\s0 that should be part of your distribution).
393 .PP
394 In some configurations it uses modified versions of the tinc vpn suite,
395 which is also available under the \s-1GENERAL PUBLIC LICENSE.\s0