[ViewVC] Diff of: cvs/gvpe/doc/gvpe.5.pod

Comparing gvpe/doc/gvpe.5.pod (file contents):
Revision 1.2 by pcg, Tue Oct 12 11:54:33 2004 UTC vs.
Revision 1.13 by root, Wed Nov 2 06:58:35 2016 UTC

…		…
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
205	... 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
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 C<gvpectrl -k> (or simply C<killall gvpe>) will kill the daemon,
208	kill the daemon, start it again, making it read it's configuration files	256	start it again, making it read it's configuration files again.
209	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
210		277
211	=head1 SEE ALSO	278	=head1 SEE ALSO
212		279
213	gvpe.osdep(5) for OS-depedendent information, gvpe.conf(5), gvpectrl(8), and	280	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).	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>.
215		286
216	=head1 AUTHOR	287	=head1 AUTHOR
217		288
218	Marc Lehmann <gvpe@plan9.de>	289	Marc Lehmann <gvpe@schmorp.de>
219		290
220	=head1 COPYRIGHTS AND LICENSES	291	=head1 COPYRIGHTS AND LICENSES
221		292
222	GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file	293	GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file
223	COPYING that should be part of your distribution).	294	COPYING that should be part of your distribution).

Diff Legend

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

Comparing gvpe/doc/gvpe.5.pod (file contents): Revision 1.2 by pcg, Tue Oct 12 11:54:33 2004 UTC vs. Revision 1.13 by root, Wed Nov 2 06:58:35 2016 UTC

Diff Legend

Comparing gvpe/doc/gvpe.5.pod (file contents):
Revision 1.2 by pcg, Tue Oct 12 11:54:33 2004 UTC vs.
Revision 1.13 by root, Wed Nov 2 06:58:35 2016 UTC