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.3 by pcg, Thu Jan 27 06:58:48 2005 UTC vs.
Revision 1.13 by root, Wed Nov 2 06:58:35 2016 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.
10
11=head2 WHAT IS A VPN?
12
13VPN is an acronym, it stands for:
9 14
10=over 4 15=over 4
11 16
12=item X<Virtual> 17=item Virtual
13 18
14Virtual means that no physical network is created (of course), but an 19Virtual means that no physical network is created (of course), but a
15ethernet 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 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
16nodes. 33nodes.
17 34
18=item X<Private>
19
20Private means that non-participating nodes cannot decode ("sniff)" nor
21inject ("spoof") packets.
22
23In the case of gvpe, even participating nodes cannot sniff packets send to 35In the case of GVPE, even participating nodes cannot sniff packets
24other 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.
25 38
26=item X<Network> 39=item Network
27 40
28Network means that more than two parties can participate in the network, 41Network means that more than two parties can participate in the network,
29so for instance it's possible to connect multiple branches of a company 42so for instance it's possible to connect multiple branches of a company
30into a single network. Many so-called "vpn" solutions only create 43into a single network. Many so-called "VPN" solutions only create
31point-to-point tunnels. 44point-to-point tunnels, which in turn can be used to build larger
45networks.
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.
32 50
33=back 51=back
34 52
35=head2 DESIGN GOALS 53=head2 GVPE DESIGN GOALS
36 54
37=over 4 55=over 4
38 56
39=item SIMPLE DESIGN 57=item SIMPLE DESIGN
40 58
41Cipher, HMAC algorithms and other key parameters must be selected 59Cipher, HMAC algorithms and other key parameters must be selected
42at compile time - this makes it possible to only link in algorithms 60at compile time - this makes it possible to only link in algorithms
43you 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
44transparent 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.
45 67
46=item EASY TO SETUP 68=item EASY TO SETUP
47 69
48A 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
49hosts) and a single run of C<gvpectrl> to generate the keys suffices to 71hosts) and generating an RSA key-pair on each node suffices to make it
50make it work. 72work.
51 73
52=item MAC-BASED SECURITY 74=item MAC-BASED SECURITY
53 75
54Since every host has it's own private key, other hosts cannot spoof 76Since every host has it's own private key, other hosts cannot spoof
55traffic from this host. That makes it possible to filter packet by MAC 77traffic from this host. That makes it possible to filter packet by MAC
… …
59 81
60=back 82=back
61 83
62=head1 PROGRAMS 84=head1 PROGRAMS
63 85
64Vpe 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
65(C<gvpectrl>). 87(C<gvpectrl>).
66 88
67=over 4 89=over 4
68 90
69=item gvpectrl 91=item gvpectrl
70 92
71Is 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
72configuration and contorl the daemon (restarting etc.). 94configuration and to control the daemon (restarting etc.).
73 95
74=item gvpe 96=item gvpe
75 97
76Is the daemon used to establish and maintain connections to the other 98This is the daemon used to establish and maintain connections to the other
77network members. It should be run on the gateway machine. 99network nodes. It should be run on the gateway of each VPN subnet.
78 100
79=back 101=back
80 102
81=head1 COMPILETIME CONFIGURATION 103=head1 COMPILETIME CONFIGURATION
82 104
83Please 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
84information. 106information.
85 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
86Here 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:
87 115
88=head2 AS LOW PACKET OVERHEAD AS POSSIBLE 116=head2 AS LOW PACKET OVERHEAD AS POSSIBLE
89 117
90 ./configure --enable-hmac-length=4 --enable-rand-length=0 118 ./configure --enable-hmac-length=4 --enable-rand-length=0
91 119
92Minimize the header overhead of VPN packets (the above will result in only 120Minimize the header overhead of VPN packets (the above will result in
934 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 almost
123trivial.
94 124
95=head2 MINIMIZE CPU TIME REQUIRED 125=head2 MINIMIZE CPU TIME REQUIRED
96 126
97 ./configure --enable-cipher=bf --enable-digest=md4 127 ./configure --enable-cipher=bf --enable-digest=md4
98 128
99Use 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.
100 132
101=head2 MAXIMIZE SECURITY 133=head2 MAXIMIZE SECURITY
102 134
103 ./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
104 136
105This 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
106would also be pretty secure ;) and will additionally prefix each packet 138would also be pretty secure ;) and will additionally prefix each packet
107with 8 bytes of random data. In the long run, people should move to 139with 12 bytes of random data.
108SHA-224 and beyond, but support in openssl is missing as of writing this
109document.
110 140
111In general, remember that AES-128 seems to be more secure and faster than 141In general, remember that AES-128 seems to be as secure but faster than
112AES-192 or AES-256, more randomness helps against sniffing and a longer 142AES-192 or AES-256, more randomness helps against sniffing and a longer
113HMAC helps against spoofing. MD4 is a fast digest, SHA1 or RIPEMD160 are 143HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256
114better, and Blowfish is a fast cipher (and also quite secure). 144are consecutively better, and Blowfish is a fast cipher (and also quite
145secure).
115 146
116=head1 HOW TO SET UP A SIMPLE VPN 147=head1 HOW TO SET UP A SIMPLE VPN
117 148
118In this section I will describe how to get a simple VPN consisting of 149In this section I will describe how to get a simple VPN consisting of
119three hosts up and running. 150three hosts up and running.
120 151
121=head2 STEP 1: configuration 152=head2 STEP 1: configuration
122 153
123First you have to create a daemon configuation file and put it into the 154First you have to create a daemon configuration file and put it into the
124configuration directory. This is usually C</etc/gvpe>, depending on how you 155configuration directory. This is usually C</etc/gvpe>, depending on how you
125configured gvpe, and can be overwritten using the C<-c> commandline switch. 156configured gvpe, and can be overwritten using the C<-c> command line switch.
126 157
127Put the following lines into C</etc/gvpe/gvpe.conf>: 158Put the following lines into C</etc/gvpe/gvpe.conf>:
128 159
129 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)
130 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts 161 mtu = 1400 # minimum MTU of all outgoing interfaces on all hosts
… …
137 hostname = 133.55.82.9 168 hostname = 133.55.82.9
138 169
139 node = third 170 node = third
140 hostname = third.example.net 171 hostname = third.example.net
141 172
142The only other file neccessary if the C<if-up> script that initializes the 173The only other file necessary is the C<if-up> script that initializes the
143local ethernet interface. Put the following lines into C</etc/gvpe/if-up> 174virtual ethernet interface on the local host. Put the following lines into
144and make it execute (C<chmod 755 /etc/gvpe/if-up>): 175C</etc/gvpe/if-up> and make it executable (C<chmod 755 /etc/gvpe/if-up>):
145 176
146 #!/bin/sh 177 #!/bin/sh
147 ip link set $IFNAME address $MAC mtu $MTU up 178 ip link set $IFNAME address $MAC mtu $MTU up
148 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME 179 [ $NODENAME = first ] && ip addr add 10.0.1.1 dev $IFNAME
149 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME 180 [ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
150 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME 181 [ $NODENAME = third ] && ip addr add 10.0.3.1 dev $IFNAME
151 ip route add 10.0.0.0/16 dev $IFNAME 182 ip route add 10.0.0.0/16 dev $IFNAME
152 183
153This script will give each node a different IP address in the C<10.0/16> 184This script will give each node a different IP address in the C<10.0/16>
154network. The internal network (e.g. the C<eth0> interface) should then be 185network. The internal network (if gvpe runs on a router) should then be
155set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>, 186set to a subset of that network, e.g. C<10.0.1.0/24> on node C<first>,
156C<10.0.2.0/24> on node C<second>, and so on. 187C<10.0.2.0/24> on node C<second>, and so on.
157 188
158By enabling routing on the gateway host that runs C<gvpe> all nodes will 189By enabling routing on the gateway host that runs C<gvpe> all nodes will
159be able to reach the other nodes. You can, of course, also use proxy arp 190be able to reach the other nodes. You can, of course, also use proxy ARP
160or other means of pseudo-bridging (or even real briding), or (best) full 191or other means of pseudo-bridging, or (best) full routing - the choice is
161routing - the choice is yours. 192yours.
162 193
163=head2 STEP 2: create the RSA key pairs for all hosts 194=head2 STEP 2: create the RSA key pair for each node
164 195
165Run the following command to generate all key pairs (that might take a 196Next you have to generate the RSA keys for the nodes. While you can set
166while): 197up GVPE so you can generate all keys on a single host and centrally
198distribute all keys, it is safer to generate the key for each node on the
199node, so that the secret/private key does not have to be copied over the
200network.
167 201
202To do so, run the following command to generate a key pair:
203
168 gvpectrl -c /etc/gvpe -g 204 gvpectrl -c /etc/gvpe -g nodekey
169 205
170This command will put the public keys into C<< 206This will create two files, F<nodekey> and F<nodekey.privkey>. The former
171/etc/gvpe/pubkeys/I<nodename> >> and the private keys into C<< 207should be copied to F<< /etc/gvpe/pubkey/I<nodename> >> on the host where
172/etc/gvpe/hostkeys/I<nodename> >>. 208your config file is (you will have to create the F<pubkey> directory
209first):
210
211 scp nodekey confighost:/etc/gvpe/pubkey/nodename
212
213The 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
173 217
174=head2 STEP 3: distribute the config files to all nodes 218=head2 STEP 3: distribute the config files to all nodes
175 219
176Now distribute the config files to the other nodes. This should be done in two steps, since the 220Now distribute the config files and public keys to the other nodes.
177private keys should not be distributed. The example uses rsync-over-ssh
178 221
179First all the config files without the hostkeys should be distributed: 222The example uses rsync-over-ssh to copy the config file and all the public
223keys:
180 224
181 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys 225 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkey
182 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys 226 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkey
183 rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkeys 227 rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkey
184 228
185Then the hostkeys should be copied:
186
187 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
188 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
189 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
190
191You should now check the configration by issuing the command C<gvpectrl -c 229You should now check the configuration by issuing the command C<gvpectrl
192/etc/gvpe -s> on each node and verify it's output. 230-c /etc/gvpe -s> on each node and verify it's output.
193 231
194=head2 STEP 4: starting gvpe 232=head2 STEP 4: starting gvpe
195 233
196You should then start gvpe on each node by issuing a command like: 234You should then start gvpe on each node by issuing a command like:
197 235
198 gvpe -D -linfo first # first is the nodename 236 gvpe -D -l info first # first is the nodename
199 237
200This will make the gvpe stay in foreground. You should then see 238This will make the gvpe daemon stay in foreground. You should then see
201"connection established" messages. If you don't see them check your 239"connection established" messages. If you don't see them check your
202firewall and routing (use tcpdump ;). 240firewall and routing (use tcpdump ;).
203 241
204If this works you should check your networking setup by pinging various 242If this works you should check your networking setup by pinging various
205endpoints. 243endpoints.
206 244
207To make gvpe run more permanently you can either run it as a daemon 245To make gvpe run more permanently you can either run it as a daemon (by
208(by starting it without the C<-D> switch), or, much better, from your 246starting it without the C<-D> switch), or, much better, from your inittab
209inittab. I use a line like this on my systems: 247or equivalent. I use a line like this on all my systems:
210 248
211 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
212 250
213=head2 STEP 5: enjoy 251=head2 STEP 5: enjoy
214 252
215... and play around. Sending a -HUP (C<gvpectrl -kHUP>) to the daemon 253... and play around. Sending a -HUP (C<gvpectrl -kHUP>) to the daemon
216will make it try to connect to all other nodes again. If you run it from 254will make it try to connect to all other nodes again. If you run it from
217inittab, as is recommended, C<gvpectrl -k> (or simply C<killall gvpe>) will 255inittab C<gvpectrl -k> (or simply C<killall gvpe>) will kill the daemon,
218kill the daemon, start it again, making it read it's configuration files 256start it again, making it read it's configuration files again.
219again. 257
258To run the GVPE daemon permanently from your SysV init, you can add it to
259your 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
263For 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
220 277
221=head1 SEE ALSO 278=head1 SEE ALSO
222 279
223gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8), and 280gvpe.osdep(5) for OS-dependent information, gvpe.conf(5), gvpectrl(8),
224for a description of the protocol and routing algorithms, gvpe.protocol(7). 281and for a description of the transports, protocol, and routing algorithm,
282gvpe.protocol(7).
283
284The GVPE mailing list, at L<http://lists.schmorp.de/>, or
285C<gvpe@lists.schmorp.de>.
225 286
226=head1 AUTHOR 287=head1 AUTHOR
227 288
228Marc Lehmann <gvpe@plan9.de> 289Marc Lehmann <gvpe@schmorp.de>
229 290
230=head1 COPYRIGHTS AND LICENSES 291=head1 COPYRIGHTS AND LICENSES
231 292
232GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file 293GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file
233COPYING that should be part of your distribution). 294COPYING that should be part of your distribution).

Diff Legend

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