[ViewVC] Diff of: cvs/gvpe/doc/gvpe.texi

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.5 by root, Tue Feb 15 13:31:22 2011 UTC vs.
Revision 1.8 by root, Thu Nov 10 15:15:23 2016 UTC

…		…
142		142
143		143
144	@item	144	@item
145	EASY TO SETUP	145	EASY TO SETUP
146		146
147	A few lines of config (the config file is shared unmodified between all hosts) and a single run of @t{gvpectrl} to generate the keys suffices to make it work.	147	A few lines of config (the config file is shared unmodified between all hosts) and generating an RSA key-pair on each node suffices to make it work.
148	@refill	148	@refill
149		149
150		150
151	@item	151	@item
152	MAC-BASED SECURITY	152	MAC-BASED SECURITY
…		…
195		195
196	@example	196	@example
197	./configure --enable-hmac-length=4 --enable-rand-length=0	197	./configure --enable-hmac-length=4 --enable-rand-length=0
198	@end example	198	@end example
199		199
200	Minimize the header overhead of VPN packets (the above will result in only 4 bytes of overhead over the raw ethernet frame). This is a insecure configuration because a HMAC length of 4 makes collision attacks based on the birthday paradox pretty easy.	200	Minimize the header overhead of VPN packets (the above will result in only 4 bytes of overhead over the raw ethernet frame). This is a insecure configuration because a HMAC length of 4 makes collision attacks almost trivial.
201	@refill	201	@refill
202		202
203		203
204	@subsection MINIMIZE CPU TIME REQUIRED	204	@subsection MINIMIZE CPU TIME REQUIRED
205		205
…		…
214		214
215	@subsection MAXIMIZE SECURITY	215	@subsection MAXIMIZE SECURITY
216		216
217		217
218	@example	218	@example
219	./configure --enable-hmac-length=16 --enable-rand-length=8 --enable-digest=sha1	219	./configure --enable-hmac-length=16 --enable-rand-length=12 --enable-digest=ripemd610
220	@end example	220	@end example
221		221
222	This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 would also be pretty secure ;) and will additionally prefix each packet with 8 bytes of random data. In the long run, people should move to SHA-256 and beyond).	222	This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 would also be pretty secure ;) and will additionally prefix each packet with 12 bytes of random data.
223	@refill	223	@refill
224	In general, remember that AES-128 seems to be as secure but faster than AES-192 or AES-256, more randomness helps against sniffing and a longer HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256 are consecutively better, and Blowfish is a fast cipher (and also quite secure).	224	In general, remember that AES-128 seems to be as secure but faster than AES-192 or AES-256, more randomness helps against sniffing and a longer HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256 are consecutively better, and Blowfish is a fast cipher (and also quite secure).
225	@refill	225	@refill
226		226
227		227
…		…
269	@refill	269	@refill
270	By enabling routing on the gateway host that runs @t{gvpe} all nodes will be able to reach the other nodes. You can, of course, also use proxy ARP or other means of pseudo-bridging, or (best) full routing - the choice is yours.	270	By enabling routing on the gateway host that runs @t{gvpe} all nodes will be able to reach the other nodes. You can, of course, also use proxy ARP or other means of pseudo-bridging, or (best) full routing - the choice is yours.
271	@refill	271	@refill
272		272
273		273
274	@subsection STEP 2: create the RSA key pairs for all hosts	274	@subsection STEP 2: create the RSA key pair for each node
275	Run the following command to generate all key pairs for all nodes (that might take a while):	275	Next you have to generate the RSA keys for the nodes. While you can set up GVPE so you can generate all keys on a single host and centrally distribute all keys, it is safer to generate the key for each node on the node, so that the secret/private key does not have to be copied over the network.
276	@refill	276	@refill
		277	To do so, run the following command to generate a key pair:
		278	@refill
277		279
278		280
279	@example	281	@example
280	gvpectrl -c /etc/gvpe -g	282	gvpectrl -c /etc/gvpe -g nodekey
		283	@end example
		284
		285	This will create two files, @file{nodekey} and @file{nodekey.privkey}. The former should be copied to @file{/etc/gvpe/pubkey/@emph{nodename}} on the host where your config file is (you will have to create the @file{pubkey} directory first):
		286	@refill
		287
		288
281	@end example	289	@example
		290	scp nodekey confighost:/etc/gvpe/pubkey/nodename
		291	@end example
282		292
283	This command will put the public keys into @t{/etc/gvpe/pubkeys/@emph{nodename}} and the private keys into @t{/etc/gvpe/hostkeys/@emph{nodename}}.	293	The private key @file{nodekey.privkey} should be moved to @file{/etc/gvpe/hostkey}:
284	@refill	294	@refill
		295
		296
		297	@example
		298	mkdir -p /etc/gvpe
		299	mv nodekey.privkey /etc/gvpe/hostkey
		300	@end example
		301
285		302
286		303
287	@subsection STEP 3: distribute the config files to all nodes	304	@subsection STEP 3: distribute the config files to all nodes
288	Now distribute the config files and private keys to the other nodes. This should be done in two steps, since only the private keys meant for a node should be distributed (so each node has only it's own private key).	305	Now distribute the config files and public keys to the other nodes.
289	@refill	306	@refill
290	The example uses rsync-over-ssh	307	The example uses rsync-over-ssh to copy the config file and all the public keys:
291	@refill	308	@refill
292	First all the config files without the hostkeys should be distributed:
293	@refill
294		309
295		310
296	@example	311	@example
297	rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys	312	rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkey
298	rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys	313	rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkey
299	rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkeys	314	rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkey
300	@end example
301
302	Then the hostkeys should be copied:
303	@refill
304
305
306	@example
307	rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
308	rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
309	rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
310	@end example	315	@end example
311		316
312	You should now check the configuration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output.	317	You should now check the configuration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output.
313	@refill	318	@refill
314		319
…		…
335	@end example	340	@end example
336		341
337		342
338		343
339	@subsection STEP 5: enjoy	344	@subsection STEP 5: enjoy
340	... and play around. Sending a -HUP (@t{gvpectrl -kHUP}) to the daemon will make it try to connect to all other nodes again. If you run it from inittab, as is recommended, @t{gvpectrl -k} (or simply @t{killall gvpe}) will kill the daemon, start it again, making it read it's configuration files again.	345	... and play around. Sending a -HUP (@t{gvpectrl -kHUP}) to the daemon will make it try to connect to all other nodes again. If you run it from inittab @t{gvpectrl -k} (or simply @t{killall gvpe}) will kill the daemon, start it again, making it read it's configuration files again.
341	@refill	346	@refill
		347	To run the GVPE daemon permanently from your SysV init, you can add it to your @file{inittab}, e.g.:
		348	@refill
		349
		350
		351	@example
		352	t1:2345:respawn:/bin/sh -c "exec nice -n-20 /path/to/gvpe -D node >/var/log/gvpe.log 2>&1"
		353	@end example
		354
		355	For systems using systemd, you can use a unit file similar to this one:
		356	@refill
		357
		358
		359	@example
		360	[Unit]
		361	Description=gvpe
		362	After=network.target
		363	Before=remote-fs.target
		364
		365	[Service]
		366	ExecStart=/path/to/gvpe -D node
		367	KillMode=process
		368	Restart=always
		369
		370	[Install]
		371	WantedBy=multi-user.target
		372	@end example
		373
342		374
343		375
344	@section COPYRIGHTS AND LICENSES	376	@section COPYRIGHTS AND LICENSES
345	GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution).	377	GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution).
346	@refill	378	@refill
…		…
606		638
607		639
608	@section DESCRIPTION	640	@section DESCRIPTION
609	The gvpe config file consists of a series of lines that contain @t{variable = value} pairs. Empty lines are ignored. Comments start with a @t{#} and extend to the end of the line. They can be used on their own lines, or after any directives. Whitespace is allowed around the @t{=} sign or after values, but not within the variable names or values themselves.	641	The gvpe config file consists of a series of lines that contain @t{variable = value} pairs. Empty lines are ignored. Comments start with a @t{#} and extend to the end of the line. They can be used on their own lines, or after any directives. Whitespace is allowed around the @t{=} sign or after values, but not within the variable names or values themselves.
610	@refill	642	@refill
611	The only exception to the above is the "on" directive that can prefix any @t{name = value} setting and will only "execute" it on the named node, or (if the nodename starts with "!") on all nodes except the named one.	643	All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones.
612	@refill	644	@refill
		645	The only exceptions to the above are the following directives:
		646	@refill
		647
		648
		649	@itemize
		650
		651
		652	@item
		653	node nodename
		654
		655	Introduces a node section. The nodename is used to select the right configuration section and is the same string as is passed as an argument to the gvpe daemon.
		656	@refill
		657	Multiple @t{node} statements with the same node name are supported and will be merged together.
		658	@refill
		659
		660
		661	@item
		662	global
		663
		664	This statement switches back to the global section, which is mainly useful if you want to include a second config file, e..g for local customisations. To do that, simply include this at the very end of your config file:
		665	@refill
		666
		667
		668	@example
		669	global
		670	include local.conf
		671	@end example
		672
		673
		674
		675	@item
		676	on nodename ...
		677
		678
		679
		680	@item
		681	on !nodename ...
		682
		683	You can prefix any configuration directive with @t{on} and a nodename. GVPE will will only "execute" it on the named node, or (if the nodename starts with @t{!}) on all nodes except the named one.
		684	@refill
613	For example, set the MTU to @t{1450} everywhere, loglevel to @t{noise} on branch1, and connect to @t{ondemand} everywhere but on branch2:	685	Example: set the MTU to @t{1450} everywhere, @t{loglevel} to @t{noise} on @t{branch1}, and @t{connect} to @t{ondemand} everywhere but on branch2.
614	@refill	686	@refill
615		687
616		688
617	@example	689	@example
618	mtu = 1450	690	mtu = 1450
619	on branch1 loglevel = noise	691	on branch1 loglevel = noise
620	on !branch2 connect = ondemand	692	on !branch2 connect = ondemand
621	@end example	693	@end example
622		694
623	All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones.	695
		696
		697	@item
		698	include relative-or-absolute-path
		699
		700	Reads the specified file (the path must not contain whitespace or @t{=} characters) and evaluate all config directives in it as if they were spelled out in place of the @t{include} directive.
624	@refill	701	@refill
		702	The path is a printf format string, that is, you must escape any @t{%} by doubling it, and you can have a single @t{%s} inside, which will be replaced by the current nodename.
		703	@refill
		704	Relative paths are interpreted relative to the GVPE config directory.
		705	@refill
		706	Example: include the file @file{local.conf} in the config directory on every node.
		707	@refill
		708
		709
		710	@example
		711	include local.conf
		712	@end example
		713
		714	Example: include a file @file{conf/}nodename@file{.conf}
		715	@refill
		716
		717
		718	@example
		719	include conf/%s.conf
		720	@end example
		721
		722	@end itemize
		723
625		724
626		725
627	@section ANATOMY OF A CONFIG FILE	726	@section ANATOMY OF A CONFIG FILE
628	Usually, a config file starts with a few global settings (like the UDP port to listen on), followed by node-specific sections that begin with a @t{node = nickname} line.	727	Usually, a config file starts with a few global settings (like the UDP port to listen on), followed by node-specific sections that begin with a @t{node = nickname} line.
629	@refill	728	@refill
…		…
643		742
644	@itemize	743	@itemize
645		744
646		745
647	@item	746	@item
		747	chroot = path or /
		748
		749	@cindex chroot
		750	Tells GVPE to chroot(2) to the specified path after reading all necessary files, binding to sockets and running the @t{if-up} script, but before running @t{node-up} or any other scripts.
		751	@refill
		752	The special path @file{/} instructs GVPE to create (and remove) an empty temporary directory to use as new root. This is most secure, but makes it impossible to use any scripts other than the @t{if-up} one.
		753	@refill
		754
		755
		756	@item
		757	chuid = numerical-uid
		758
		759	@cindex chuid
		760
		761
		762	@item
		763	chgid = numerical-gid
		764
		765	@cindex chgid
		766	These two options tell GVPE to change to the given user and/or group id after reading all necessary files, binding to sockets and running the @t{if-up} script.
		767	@refill
		768	Other scripts, such as @t{node-up}, are run with the new user id or group id.
		769	@refill
		770
		771
		772	@item
		773	chuser = username
		774
		775	@cindex chuser
		776	Alternative to @t{chuid} and @t{chgid}: Sets both @t{chuid} and @t{chgid} to the user and (primary) group ids of the specified user (for example, @t{nobody}).
		777	@refill
		778
		779
		780	@item
648	dns-forw-host = hostname/ip	781	dns-forw-host = hostname/ip
649		782
650	@cindex dns-forw-host	783	@cindex dns-forw-host
651	The DNS server to forward DNS requests to for the DNS tunnel protocol (default: @t{127.0.0.1}, changing it is highly recommended).	784	The DNS server to forward DNS requests to for the DNS tunnel protocol (default: @t{127.0.0.1}, changing it is highly recommended).
652	@refill	785	@refill
…		…
655	@item	788	@item
656	dns-forw-port = port-number	789	dns-forw-port = port-number
657		790
658	@cindex dns-forw-port	791	@cindex dns-forw-port
659	The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases).	792	The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases).
		793	@refill
		794
		795
		796	@item
		797	dns-case-preserving = yes\|true\|on \| no\|false\|off
		798
		799	@cindex dns-case-preserving
		800	Sets whether the DNS transport forwarding server preserves case (DNS servers have to, but some access systems are even more broken than others) (default: true).
		801	@refill
		802	Normally, when the forwarding server changes the case of domain names then GVPE will automatically set this to false.
660	@refill	803	@refill
661		804
662		805
663	@item	806	@item
664	dns-max-outstanding = integer-number-of-requests	807	dns-max-outstanding = integer-number-of-requests
…		…
894		1037
895	@item	1038	@item
896	keepalive = seconds	1039	keepalive = seconds
897		1040
898	@cindex keepalive	1041	@cindex keepalive
899	Sets the keepalive probe interval in seconds (default: @t{60}). After this many seconds of inactivity the daemon will start to send keepalive probe every 3 seconds until it receives a reply from the other end. If no reply is received within 15 seconds, the peer is considered unreachable and the connection is closed.	1042	Sets the keepalive probe interval in seconds (default: @t{60}). After this many seconds of inactivity the daemon will start to send keepalive probe every 3 seconds until it receives a reply from the other end. If no reply is received within 15 seconds, the peer is considered unreachable and the connection is closed.
900	@refill	1043	@refill
901		1044
902		1045
903	@item	1046	@item
904	loglevel = noise\|trace\|debug\|info\|notice\|warn\|error\|critical	1047	loglevel = noise\|trace\|debug\|info\|notice\|warn\|error\|critical
…		…
919	This value must be the minimum of the MTU values of all nodes.	1062	This value must be the minimum of the MTU values of all nodes.
920	@refill	1063	@refill
921		1064
922		1065
923	@item	1066	@item
924	node = nickname	1067	nfmark = integer
925		1068
926	@cindex node	1069	@cindex nfmark
927	Not really a config setting but introduces a node section. The nickname is used to select the right configuration section and must be passed as an argument to the gvpe daemon.	1070	This advanced option, when set to a nonzero value (default: @t{0}), tries to set the netfilter mark (or fwmark) value on all sockets gvpe uses to send packets.
928	@refill	1071	@refill
		1072	This can be used to make gvpe use a different set of routing rules. For example, on GNU/Linux, the @t{if-up} could set @t{nfmark} to 1000 and then put all routing rules into table @t{99} and then use an ip rule to make gvpe traffic avoid that routing table, in effect routing normal traffic via gvpe and gvpe traffic via the normal system routing tables:
		1073	@refill
		1074
		1075
		1076	@example
		1077	ip rule add not fwmark 1000 lookup 99
		1078	@end example
		1079
929		1080
930		1081
931	@item	1082	@item
932	node-up = relative-or-absolute-path	1083	node-up = relative-or-absolute-path
933		1084
…		…
996	@example	1147	@example
997	#!/bin/sh	1148	#!/bin/sh
998	@{	1149	@{
999	echo update delete $DESTNODE.lowttl.example.net. a	1150	echo update delete $DESTNODE.lowttl.example.net. a
1000	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP	1151	echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP
1001	echo	1152	echo
1002	@} \| nsupdate -d -k $CONFBASE:key.example.net.	1153	@} \| nsupdate -d -k $CONFBASE:key.example.net.
1003	@end example	1154	@end example
1004		1155
1005		1156
1006		1157
…		…
1022		1173
1023	@item	1174	@item
1024	pid-file = path	1175	pid-file = path
1025		1176
1026	@cindex pid-file	1177	@cindex pid-file
1027	The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}).	1178	The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}). The first @t{%s} is replaced by the nodename - any other use of @t{%} must be written as @t{%%}.
1028	@refill	1179	@refill
1029		1180
1030		1181
1031	@item	1182	@item
1032	private-key = relative-path-to-key	1183	private-key = relative-path-to-key
1033		1184
1034	@cindex private-key	1185	@cindex private-key
1035	Sets the path (relative to the config directory) to the private key (default: @t{hostkey}). This is a printf format string so every @t{%} must be doubled. A single @t{%s} is replaced by the hostname, so you could use paths like @t{hostkeys/%s} to fetch the files at the location where @t{gvpectrl} puts them.	1186	Sets the path (relative to the config directory) to the private key (default: @t{hostkey}). This is a printf format string so every @t{%} must be doubled. A single @t{%s} is replaced by the hostname, so you could use paths like @t{hostkeys/%s} to be able to share the same config directory between nodes.
1036	@refill	1187	@refill
1037	Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofing, it is not recommended to use this feature.	1188	Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofing, it is not recommended to use this feature this way though.
1038	@refill	1189	@refill
1039		1190
1040		1191
1041	@item	1192	@item
1042	rekey = seconds	1193	rekey = seconds
1043		1194
1044	@cindex rekey	1195	@cindex rekey
1045	Sets the rekeying interval in seconds (default: @t{3600}). Connections are reestablished every @t{rekey} seconds, making them use a new encryption key.	1196	Sets the rekeying interval in seconds (default: @t{3607}). Connections are reestablished every @t{rekey} seconds, making them use a new encryption key.
1046	@refill	1197	@refill
1047		1198
1048		1199
1049	@item	1200	@item
1050	nfmark = integer	1201	seed-device = path
1051		1202
1052	@cindex nfmark	1203	@cindex seed-device
1053	This advanced option, when set to a nonzero value (default: @t{0}), tries to set the netfilter mark (or fwmark) value on all sockets gvpe uses to send packets.	1204	The random device used to initially and regularly seed the random number generator (default: @file{/dev/urandom}). Randomness is of paramount importance to the security of the algorithms used in gvpe.
1054	@refill	1205	@refill
1055	This can be used to make gvpe use a different set of routing rules. For example, on GNU/Linux, the @t{if-up} could set @t{nfmark} to 1000 and then put all routing rules into table @t{99} and then use an ip rule to make gvpe traffic avoid that routing table, in effect routing normal traffic via gvpe and gvpe traffic via the normal system routing tables:	1206	On program start and every seed-interval, gvpe will read 64 octets.
1056	@refill	1207	@refill
		1208	Setting this path to the empty string will disable this functionality completely (the underlying crypto library will likely look for entropy sources on it's own though, so not all is lost).
		1209	@refill
1057		1210
1058		1211
1059	@example	1212	@item
1060	ip rule add not fwmark 1000 lookup 99	1213	seed-interval = seconds
1061	@end example
1062		1214
		1215	@cindex seed-interval
		1216	The number of seconds between reseeds of the random number generator (default: @t{3613}). A value of @t{0} disables this regular reseeding.
		1217	@refill
		1218
		1219
		1220	@item
		1221	serial = string
		1222
		1223	@cindex serial
		1224	The configuration serial number. This can be any string up to 16 bytes length. Only when the serial matches on both sides of a conenction will the connection succeed. This is @emph{not} a security mechanism and eay to spoof, this mechanism exists to alert users that their config is outdated.
		1225	@refill
		1226	It's recommended to specify this is a date string such as @t{2013-05-05} or @t{20121205084417}.
		1227	@refill
		1228	The exact algorithm is as this: if a connection request is received form a node with an identical serial, then it succeeds normally.
		1229	@refill
		1230	If the remote serial is lower than the local serial, it is ignored.
		1231	@refill
		1232	If the remote serial is higher than the local serial, a warning message is logged.
		1233	@refill
1063	@end itemize	1234	@end itemize
1064		1235
1065		1236
1066		1237
1067	@subsection NODE SPECIFIC SETTINGS	1238	@subsection NODE SPECIFIC SETTINGS
…		…
1206	enable-udp = yes\|true\|on \| no\|false\|off	1377	enable-udp = yes\|true\|on \| no\|false\|off
1207		1378
1208	@cindex enable-udp	1379	@cindex enable-udp
1209	See gvpe.protocol(7) for a description of the UDP transport protocol.	1380	See gvpe.protocol(7) for a description of the UDP transport protocol.
1210	@refill	1381	@refill
1211	Enable the UDPv4 transport using the @t{udp-port} port (default: @t{no}, unless no other protocol is enabled for a node, in which case this protocol is enabled automatically).	1382	Enable the UDPv4 transport using the @t{udp-port} port (default: @t{no}).
1212	@refill
1213	NOTE: Please specify @t{enable-udp = yes} if you want to use it even though it might get switched on automatically, as some future version might default to another default protocol.
1214	@refill	1383	@refill
1215		1384
1216		1385
1217	@item	1386	@item
1218	hostname = hostname \| ip [can not be defaulted]	1387	hostname = hostname \| ip [can not be defaulted]
…		…
1249	Whether to inherit the TOS settings of packets sent to the tunnel when sending packets to this node (default: @t{yes}). If set to @t{yes} then outgoing tunnel packets will have the same TOS setting as the packets sent to the tunnel device, which is usually what you want.	1418	Whether to inherit the TOS settings of packets sent to the tunnel when sending packets to this node (default: @t{yes}). If set to @t{yes} then outgoing tunnel packets will have the same TOS setting as the packets sent to the tunnel device, which is usually what you want.
1250	@refill	1419	@refill
1251		1420
1252		1421
1253	@item	1422	@item
		1423	low-power = yes\|true\|on \| no\|false\|off
		1424
		1425	@cindex low-power
		1426	If true, designates a node as a low-power node. Low-power nodes use larger timeouts and try to reduce cpu time. Other nodes talking to a low-power node will also use larger timeouts, and will use less aggressive optimisations, in the hope of reducing load. Security is not compromised.
		1427	@refill
		1428	The typical low-power node would be a mobile phone, where wakeups and encryption can significantly increase power drain.
		1429	@refill
		1430
		1431
		1432	@item
1254	max-retry = positive-number	1433	max-retry = positive-number
1255		1434
1256	@cindex max-retry	1435	@cindex max-retry
1257	The maximum interval in seconds (default: @t{3600}, one hour) between retries to establish a connection to this node. When a connection cannot be established, gvpe uses exponential back-off capped at this value. It's sometimes useful to set this to a much lower value (e.g. @t{120}) on connections to routers that usually are stable but sometimes are down, to assure quick reconnections even after longer downtimes.	1436	The maximum interval in seconds (default: @t{3600}, one hour) between retries to establish a connection to this node. When a connection cannot be established, gvpe uses exponential back-off capped at this value. It's sometimes useful to set this to a much lower value (e.g. @t{120}) on connections to routers that usually are stable but sometimes are down, to assure quick reconnections even after longer downtimes.
1258	@refill	1437	@refill
…		…
1340		1519
1341		1520
1342	@item	1521	@item
1343	hostkey	1522	hostkey
1344		1523
1345	The private key (taken from @t{hostkeys/nodename}) of the current host.	1524	The (default path of the) private key of the current host.
1346	@refill	1525	@refill
1347		1526
1348		1527
1349	@item	1528	@item
1350	pubkey/nodename	1529	pubkey/nodename
…		…
1387	Read configuration options from @emph{DIR}.	1566	Read configuration options from @emph{DIR}.
1388	@refill	1567	@refill
1389		1568
1390		1569
1391	@item	1570	@item
		1571	@strong{-g}, @strong{--generate-key=path}
		1572
		1573	Generates a single RSA key-pair. The public key will be stored in @file{@emph{path}} while the private key will be stored in @file{@emph{path} .privkey}. Neither file must be non-empty for this to succeed.
		1574	@refill
		1575	The public key file @file{@emph{path}} is normally copied to @file{pubkey/nodename} in the config directory on all nodes, while the private key @file{@emph{path}.privkey} should be copied to the file @file{hostkey} on the node the key is for.
		1576	@refill
		1577	It's recommended to generate the keypair on the node where it will be used, so that the private key file does not have to travel over the network.
		1578	@refill
		1579
		1580
		1581	@item
1392	@strong{-g}, @strong{--generate-keys}	1582	@strong{-G}, @strong{--generate-keys}
1393		1583
1394	Generate public/private RSA key-pair and exit.	1584	Generate public/private RSA key-pairs for all nodes not having a key and exit.
		1585	@refill
		1586	Note that in normal configurations this will fail, as there cna only be one private key per host. To make this configuration work you need to specify separate keyfiles for hostkeys in your config file, e.g.:
		1587	@refill
		1588
		1589
		1590	@example
		1591	private-key = hostkeys/%s
		1592	@end example
		1593
		1594	Such a configuration makes it easier to distribute a configuration centrally but requires private keys to be transported securely over the network.
1395	@refill	1595	@refill
1396		1596
1397		1597
1398	@item	1598	@item
1399	@strong{-q}, @strong{--quiet}	1599	@strong{-q}, @strong{--quiet}
…		…
1595		1795
1596		1796
1597	@item	1797	@item
1598	@t{/etc/gvpe/pubkey/*}	1798	@t{/etc/gvpe/pubkey/*}
1599		1799
1600	The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}.	1800	The directory containing the public keys for every node, one file per node with the name of the node.
		1801	@refill
		1802
		1803
		1804	@item
		1805	@t{/etc/gvpe/hostkey}
		1806
		1807	The file containing the private key of the node GVPE runs on. Unlike all the other files in the @file{/etc/gvpe} directory, this file usually differes for each node that GVPE runs on.
1601	@refill	1808	@refill
1602		1809
1603		1810
1604	@item	1811	@item
1605	@t{/var/run/gvpe.pid}	1812	@t{/var/run/gvpe.pid}
…		…
1626		1833
1627		1834
1628	@section Overview	1835	@section Overview
1629	GVPE can make use of a number of protocols. One of them is the GNU VPE protocol which is used to authenticate tunnels and send encrypted data packets. This protocol is described in more detail the second part of this document.	1836	GVPE can make use of a number of protocols. One of them is the GNU VPE protocol which is used to authenticate tunnels and send encrypted data packets. This protocol is described in more detail the second part of this document.
1630	@refill	1837	@refill
1631	The first part of this document describes the transport protocols which are used by GVPE to send it's data packets over the network.	1838	The first part of this document describes the transport protocols which are used by GVPE to send its data packets over the network.
1632	@refill	1839	@refill
1633		1840
1634		1841
1635	@section PART 1: Transport protocols	1842	@section PART 1: Transport protocols
1636	GVPE offers a wide range of transport protocols that can be used to interchange data between nodes. Protocols differ in their overhead, speed, reliability, and robustness.	1843	GVPE offers a wide range of transport protocols that can be used to interchange data between nodes. Protocols differ in their overhead, speed, reliability, and robustness.
…		…
1663	It should be used if RAW IP is not available.	1870	It should be used if RAW IP is not available.
1664	@refill	1871	@refill
1665		1872
1666		1873
1667	@subsection TCP	1874	@subsection TCP
1668	This protocol is a very bad choice, as it not only has high overhead (more than 60 bytes), but the transport also retries on it's own, which leads to congestion when the link has moderate packet loss (as both the TCP transport and the tunneled traffic will retry, increasing congestion more and more). It also has high latency and is quite inefficient.	1875	This protocol is a very bad choice, as it not only has high overhead (more than 60 bytes), but the transport also retries on its own, which leads to congestion when the link has moderate packet loss (as both the TCP transport and the tunneled traffic will retry, increasing congestion more and more). It also has high latency and is quite inefficient.
1669	@refill	1876	@refill
1670	It's only useful when tunneling through firewalls that block better protocols. If a node doesn't have direct internet access but a HTTP proxy that supports the CONNECT method it can be used to tunnel through a web proxy. For this to work, the @t{tcp-port} should be @t{443} (@t{https}), as most proxies do not allow connections to other ports.	1877	It's only useful when tunneling through firewalls that block better protocols. If a node doesn't have direct internet access but a HTTP proxy that supports the CONNECT method it can be used to tunnel through a web proxy. For this to work, the @t{tcp-port} should be @t{443} (@t{https}), as most proxies do not allow connections to other ports.
1671	@refill	1878	@refill
1672	It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE.	1879	It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE.
1673	@refill	1880	@refill
…		…
1680	@refill	1887	@refill
1681	This is the worst choice of transport protocol with respect to overhead (overhead can be 2-3 times higher than the transferred data), and latency (which can be many seconds). Some DNS servers might not be prepared to handle the traffic and drop or corrupt packets. The client also has to constantly poll the server for data, so the client will constantly create traffic even if it doesn't need to transport packets.	1888	This is the worst choice of transport protocol with respect to overhead (overhead can be 2-3 times higher than the transferred data), and latency (which can be many seconds). Some DNS servers might not be prepared to handle the traffic and drop or corrupt packets. The client also has to constantly poll the server for data, so the client will constantly create traffic even if it doesn't need to transport packets.
1682	@refill	1889	@refill
1683	In addition, the same problems as the TCP transport also plague this protocol.	1890	In addition, the same problems as the TCP transport also plague this protocol.
1684	@refill	1891	@refill
1685	It's only use is to tunnel through firewalls that do not allow direct internet access. Similar to using a HTTP proxy (as the TCP transport does), it uses a local DNS server/forwarder (given by the @t{dns-forw-host} configuration value) as a proxy to send and receive data as a client, and an @t{NS} record pointing to the GVPE server (as given by the @t{dns-hostname} directive).	1892	Its only use is to tunnel through firewalls that do not allow direct internet access. Similar to using a HTTP proxy (as the TCP transport does), it uses a local DNS server/forwarder (given by the @t{dns-forw-host} configuration value) as a proxy to send and receive data as a client, and an @t{NS} record pointing to the GVPE server (as given by the @t{dns-hostname} directive).
1686	@refill	1893	@refill
1687	The only good side of this protocol is that it can tunnel through most firewalls mostly undetected, iff the local DNS server/forwarder is sane (which is true for most routers, wireless LAN gateways and nameservers).	1894	The only good side of this protocol is that it can tunnel through most firewalls mostly undetected, iff the local DNS server/forwarder is sane (which is true for most routers, wireless LAN gateways and nameservers).
1688	@refill	1895	@refill
1689	Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly.	1896	Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly.
1690	@refill	1897	@refill
…		…
1704	+------+------+--------+------+	1911	+------+------+--------+------+
1705	\| HMAC \| TYPE \| SRCDST \| DATA \|	1912	\| HMAC \| TYPE \| SRCDST \| DATA \|
1706	+------+------+--------+------+	1913	+------+------+--------+------+
1707	@end example	1914	@end example
1708		1915
1709	The HMAC field is present in all packets, even if not used (e.g. in auth request packets), in which case it is set to all zeroes. The checksum itself is calculated over the TYPE, SRCDST and DATA fields in all cases.	1916	The HMAC field is present in all packets, even if not used (e.g. in auth request packets), in which case it is set to all zeroes. The MAC itself is calculated over the TYPE, SRCDST and DATA fields in all cases.
1710	@refill	1917	@refill
1711	The TYPE field is a single byte and determines the purpose of the packet (e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, CONNECT REQUEST/INFO etc.).	1918	The TYPE field is a single byte and determines the purpose of the packet (e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, CONNECT REQUEST/INFO etc.).
1712	@refill	1919	@refill
1713	SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).	1920	SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).
1714	@refill	1921	@refill
1715	The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown:	1922	The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown:
1716	@refill	1923	@refill
1717		1924
1718		1925
1719	@example	1926	@example
1720	+------+------+--------+------+-------+------+	1927	+------+------+--------+-------+------+
1721	\| HMAC \| TYPE \| SRCDST \| RAND \| SEQNO \| DATA \|	1928	\| HMAC \| TYPE \| SRCDST \| SEQNO \| DATA \|
1722	+------+------+--------+------+-------+------+	1929	+------+------+--------+-------+------+
1723	@end example	1930	@end example
1724		1931
1725	RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes.
1726	@refill
1727	SEQNO is a 32-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. VPE currently uses a sliding window of 512 packets/sequence numbers to detect reordering, duplication and replay attacks.	1932	SEQNO is a 32-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. GVPE currently uses a sliding window of 512 packets/sequence numbers to detect reordering, duplication and replay attacks.
1728	@refill	1933	@refill
		1934	The encryption is done on SEQNO+DATA in CTR mode with IV generated from the seqno (for AES: seqno \|\| seqno \|\| seqno \|\| (u32)0), which ensures uniqueness for a given key.
		1935	@refill
1729		1936
1730		1937
1731	@subsection The authentication protocol	1938	@subsection The authentication/key exchange protocol
1732	Before nodes can exchange packets, they need to establish authenticity of the other side and a key. Every node has a private RSA key and the public RSA keys of all other nodes.	1939	Before nodes can exchange packets, they need to establish authenticity of the other side and a key. Every node has a private RSA key and the public RSA keys of all other nodes.
1733	@refill	1940	@refill
1734	A host establishes a simplex connection by sending the other node an RSA encrypted challenge containing a random challenge (consisting of the encryption key to use when sending packets, more random data and PKCS1_OAEP padding) and a random 16 byte "challenge-id" (used to detect duplicate auth packets). The destination node will respond by replying with an (unencrypted) RIPEMD160 hash of the decrypted challenge, which will authenticate that node. The destination node will also set the outgoing encryption parameters as given in the packet.	1941	When a node wants to establish a connection to another node, it sends an RSA-OEAP-encrypted challenge and an ECDH (curve25519) key. The other node replies with its own ECDH key and a HKDF of the challenge and both ECDH keys to prove its identity.
1735	@refill	1942	@refill
1736	When the source node receives a correct auth reply (by verifying the hash and the id, which will expire after 120 seconds), it will start to accept data packets from the destination node.	1943	The remote node enganges in exactly the same protocol. When both nodes have exchanged their challenge and verified the response, they calculate a cipher key and a HMAC key and start exchanging data packets.
1737	@refill	1944	@refill
1738	This means that a node can only initiate a simplex connection, telling the other side the key it has to use when it sends packets. The challenge reply is only used to set the current IP address of the other side and protocol parameters.	1945	In detail, the challenge consist of:
1739	@refill	1946	@refill
1740	This protocol is completely symmetric, so to be able to send packets the destination node must send a challenge in the exact same way as already described (so, in essence, two simplex connections are created per node pair).	1947
		1948
		1949	@example
		1950	RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
		1951	@end example
		1952
		1953	That is, it encrypts (with the public key of the remote node) an initial sequence number for data packets, key material for the HMAC key, key material for the cipher key, a salt used by the HKDF (as shown later) and some extra random bytes that are unused except for authentication. It also sends the public key of a curve25519 exchange.
		1954	@refill
		1955	The remote node decrypts the RSA data, generates its own ECDH key (ECDH2), and replies with:
		1956	@refill
		1957
		1958
		1959	@example
		1960	HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
		1961	@end example
		1962
		1963	That is, it extracts from the decrypted RSA challenge, using its ECDH key as salt, and then expands using the requesting node's ECDH1 key. The resulting hash is returned as a proof that the node could decrypt the RSA challenge data, together with the ECDH key.
		1964	@refill
		1965	After both nodes have done this to each other, they calculate the shared ECDH secret, cipher and HMAC keys for the session (each node generates two cipher and HMAC keys, one for sending and one for receiving).
		1966	@refill
		1967	The HMAC key for sending is generated as follow:
		1968	@refill
		1969
		1970
		1971	@example
		1972	HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
		1973	@end example
		1974
		1975	It extracts from MAC and ECDH_SECRET using the @emph{remote} SALT, then expands using a static info string.
		1976	@refill
		1977	The cipher key is generated in the same way, except using the CIPHER part of the original challenge.
		1978	@refill
		1979	The result of this process is to authenticate each node to the other node, while exchanging keys using both RSA and ECDH, the latter providing perfect forward secrecy.
		1980	@refill
		1981	The protocol has been overdesigned where this was possible without increasing implementation complexity, in an attempt to protect against implementation or protocol failures. For example, if the ECDH challenge was found to be flawed, perfect forward secrecy would be lost, but the data would likely still be protected. Likewise, standard algorithms and implementations are used where possible.
1741	@refill	1982	@refill
1742		1983
1743		1984
1744	@subsection Retrying	1985	@subsection Retrying
1745	When there is no response to an auth request, the node will send auth requests in bursts with an exponential back-off. After some time it will resort to PING packets, which are very small (8 bytes + protocol header) and lightweight (no RSA operations required). A node that receives ping requests from an unconnected peer will respond by trying to create a connection.	1986	When there is no response to an auth request, the node will send auth requests in bursts with an exponential back-off. After some time it will resort to PING packets, which are very small (8 bytes + protocol header) and lightweight (no RSA operations required). A node that receives ping requests from an unconnected peer will respond by trying to create a connection.
…		…
1751	Sending packets over the VPN will reset the retry intervals as well, which means as long as somebody is trying to send packets to a given node, GVPE will try to connect every few seconds.	1992	Sending packets over the VPN will reset the retry intervals as well, which means as long as somebody is trying to send packets to a given node, GVPE will try to connect every few seconds.
1752	@refill	1993	@refill
1753		1994
1754		1995
1755	@subsection Routing and Protocol translation	1996	@subsection Routing and Protocol translation
1756	The GVPE routing algorithm is easy: there isn't much routing to speak of: When routing packets to another node, GVPE trues the following options, in order:	1997	The GVPE routing algorithm is easy: there isn't much routing to speak of: When routing packets to another node, GVPE tries the following options, in order:
1757	@refill	1998	@refill
1758		1999
1759		2000
1760	@itemize	2001	@itemize
1761		2002
…		…
1783	@item	2024	@item
1784	Failing all that, the packet will be dropped.	2025	Failing all that, the packet will be dropped.
1785		2026
1786	@end itemize	2027	@end itemize
1787		2028
1788	A host can usually declare itself unreachable directly by setting it's port number(s) to zero. It can declare other hosts as unreachable by using a config-file that disables all protocols for these other hosts. Another option is to disable all protocols on that host in the other config files.	2029	A host can usually declare itself unreachable directly by setting its port number(s) to zero. It can declare other hosts as unreachable by using a config-file that disables all protocols for these other hosts. Another option is to disable all protocols on that host in the other config files.
1789	@refill	2030	@refill
1790	If two hosts cannot connect to each other because their IP address(es) are not known (such as dial-up hosts), one side will send a @emph{mediated} connection request to a router (routers must be configured to act as routers!), which will send both the originating and the destination host a connection info request with protocol information and IP address of the other host (if known). Both hosts will then try to establish a direct connection to the other peer, which is usually possible even when both hosts are behind a NAT gateway.	2031	If two hosts cannot connect to each other because their IP address(es) are not known (such as dial-up hosts), one side will send a @emph{mediated} connection request to a router (routers must be configured to act as routers!), which will send both the originating and the destination host a connection info request with protocol information and IP address of the other host (if known). Both hosts will then try to establish a direct connection to the other peer, which is usually possible even when both hosts are behind a NAT gateway.
1791	@refill	2032	@refill
1792	Routing via other nodes works because the SRCDST field is not encrypted, so the router can just forward the packet to the destination host. Since each host uses it's own private key, the router will not be able to decrypt or encrypt packets, it will just act as a simple router and protocol translator.	2033	Routing via other nodes works because the SRCDST field is not encrypted, so the router can just forward the packet to the destination host. Since each host uses its own private key, the router will not be able to decrypt or encrypt packets, it will just act as a simple router and protocol translator.
1793	@refill	2034	@refill
1794		2035
1795		2036
1796		2037
1797	@node Simple Example,Complex Example,gvpe.protocol,Top	2038	@node Simple Example,Complex Example,gvpe.protocol,Top

Diff Legend

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

Comparing gvpe/doc/gvpe.texi (file contents): Revision 1.5 by root, Tue Feb 15 13:31:22 2011 UTC vs. Revision 1.8 by root, Thu Nov 10 15:15:23 2016 UTC

Diff Legend

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.5 by root, Tue Feb 15 13:31:22 2011 UTC vs.
Revision 1.8 by root, Thu Nov 10 15:15:23 2016 UTC