… | |
… | |
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 | |
… | |
… | |
606 | |
606 | |
607 | |
607 | |
608 | @section DESCRIPTION |
608 | @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. |
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. |
610 | @refill |
610 | @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. |
611 | All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones. |
612 | @refill |
612 | @refill |
|
|
613 | The only exceptions to the above are the following directives: |
|
|
614 | @refill |
|
|
615 | |
|
|
616 | |
|
|
617 | @itemize |
|
|
618 | |
|
|
619 | |
|
|
620 | @item |
|
|
621 | node nodename |
|
|
622 | |
|
|
623 | 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. |
|
|
624 | @refill |
|
|
625 | Multiple @t{node} statements with the same node name are supported and will be merged together. |
|
|
626 | @refill |
|
|
627 | |
|
|
628 | |
|
|
629 | @item |
|
|
630 | global |
|
|
631 | |
|
|
632 | 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: |
|
|
633 | @refill |
|
|
634 | |
|
|
635 | |
|
|
636 | @example |
|
|
637 | global |
|
|
638 | include local.conf |
|
|
639 | @end example |
|
|
640 | |
|
|
641 | |
|
|
642 | |
|
|
643 | @item |
|
|
644 | on nodename ... |
|
|
645 | |
|
|
646 | |
|
|
647 | |
|
|
648 | @item |
|
|
649 | on !nodename ... |
|
|
650 | |
|
|
651 | 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. |
|
|
652 | @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: |
653 | 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 |
654 | @refill |
615 | |
655 | |
616 | |
656 | |
617 | @example |
657 | @example |
618 | mtu = 1450 |
658 | mtu = 1450 |
619 | on branch1 loglevel = noise |
659 | on branch1 loglevel = noise |
620 | on !branch2 connect = ondemand |
660 | on !branch2 connect = ondemand |
621 | @end example |
661 | @end example |
622 | |
662 | |
623 | All settings are applied "in order", that is, later settings of the same variable overwrite earlier ones. |
663 | |
|
|
664 | |
|
|
665 | @item |
|
|
666 | include relative-or-absolute-path |
|
|
667 | |
|
|
668 | 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 |
669 | @refill |
|
|
670 | 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. |
|
|
671 | @refill |
|
|
672 | Relative paths are interpreted relative to the GVPE config directory. |
|
|
673 | @refill |
|
|
674 | Example: include the file @file{local.conf} in the config directory on every node. |
|
|
675 | @refill |
|
|
676 | |
|
|
677 | |
|
|
678 | @example |
|
|
679 | include local.conf |
|
|
680 | @end example |
|
|
681 | |
|
|
682 | Example: include a file @file{conf/}nodename@file{.conf} |
|
|
683 | @refill |
|
|
684 | |
|
|
685 | |
|
|
686 | @example |
|
|
687 | include conf/%s.conf |
|
|
688 | @end example |
|
|
689 | |
|
|
690 | @end itemize |
|
|
691 | |
625 | |
692 | |
626 | |
693 | |
627 | @section ANATOMY OF A CONFIG FILE |
694 | @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. |
695 | 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 |
696 | @refill |
… | |
… | |
643 | |
710 | |
644 | @itemize |
711 | @itemize |
645 | |
712 | |
646 | |
713 | |
647 | @item |
714 | @item |
|
|
715 | chroot = path or / |
|
|
716 | |
|
|
717 | @cindex chroot |
|
|
718 | 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. |
|
|
719 | @refill |
|
|
720 | 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. |
|
|
721 | @refill |
|
|
722 | |
|
|
723 | |
|
|
724 | @item |
|
|
725 | chuid = numerical-uid |
|
|
726 | |
|
|
727 | @cindex chuid |
|
|
728 | |
|
|
729 | |
|
|
730 | @item |
|
|
731 | chgid = numerical-gid |
|
|
732 | |
|
|
733 | @cindex chgid |
|
|
734 | 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. |
|
|
735 | @refill |
|
|
736 | Other scripts, such as @t{node-up}, are run with the new user id or group id. |
|
|
737 | @refill |
|
|
738 | |
|
|
739 | |
|
|
740 | @item |
|
|
741 | chuser = username |
|
|
742 | |
|
|
743 | @cindex chuser |
|
|
744 | 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}). |
|
|
745 | @refill |
|
|
746 | |
|
|
747 | |
|
|
748 | @item |
648 | dns-forw-host = hostname/ip |
749 | dns-forw-host = hostname/ip |
649 | |
750 | |
650 | @cindex dns-forw-host |
751 | @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). |
752 | 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 |
753 | @refill |
… | |
… | |
655 | @item |
756 | @item |
656 | dns-forw-port = port-number |
757 | dns-forw-port = port-number |
657 | |
758 | |
658 | @cindex dns-forw-port |
759 | @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). |
760 | The port where the @t{dns-forw-host} is to be contacted (default: @t{53}, which is fine in most cases). |
|
|
761 | @refill |
|
|
762 | |
|
|
763 | |
|
|
764 | @item |
|
|
765 | dns-case-preserving = yes|true|on | no|false|off |
|
|
766 | |
|
|
767 | @cindex dns-case-preserving |
|
|
768 | 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). |
|
|
769 | @refill |
|
|
770 | Normally, when the forwarding server changes the case of domain names then GVPE will automatically set this to false. |
660 | @refill |
771 | @refill |
661 | |
772 | |
662 | |
773 | |
663 | @item |
774 | @item |
664 | dns-max-outstanding = integer-number-of-requests |
775 | dns-max-outstanding = integer-number-of-requests |
… | |
… | |
894 | |
1005 | |
895 | @item |
1006 | @item |
896 | keepalive = seconds |
1007 | keepalive = seconds |
897 | |
1008 | |
898 | @cindex keepalive |
1009 | @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. |
1010 | 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 |
1011 | @refill |
901 | |
1012 | |
902 | |
1013 | |
903 | @item |
1014 | @item |
904 | loglevel = noise|trace|debug|info|notice|warn|error|critical |
1015 | loglevel = noise|trace|debug|info|notice|warn|error|critical |
… | |
… | |
919 | This value must be the minimum of the MTU values of all nodes. |
1030 | This value must be the minimum of the MTU values of all nodes. |
920 | @refill |
1031 | @refill |
921 | |
1032 | |
922 | |
1033 | |
923 | @item |
1034 | @item |
924 | node = nickname |
1035 | nfmark = integer |
925 | |
1036 | |
926 | @cindex node |
1037 | @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. |
1038 | 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 |
1039 | @refill |
|
|
1040 | 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: |
|
|
1041 | @refill |
|
|
1042 | |
|
|
1043 | |
|
|
1044 | @example |
|
|
1045 | ip rule add not fwmark 1000 lookup 99 |
|
|
1046 | @end example |
|
|
1047 | |
929 | |
1048 | |
930 | |
1049 | |
931 | @item |
1050 | @item |
932 | node-up = relative-or-absolute-path |
1051 | node-up = relative-or-absolute-path |
933 | |
1052 | |
… | |
… | |
996 | @example |
1115 | @example |
997 | #!/bin/sh |
1116 | #!/bin/sh |
998 | @{ |
1117 | @{ |
999 | echo update delete $DESTNODE.lowttl.example.net. a |
1118 | echo update delete $DESTNODE.lowttl.example.net. a |
1000 | echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP |
1119 | echo update add $DESTNODE.lowttl.example.net. 1 in a $DESTIP |
1001 | echo |
1120 | echo |
1002 | @} | nsupdate -d -k $CONFBASE:key.example.net. |
1121 | @} | nsupdate -d -k $CONFBASE:key.example.net. |
1003 | @end example |
1122 | @end example |
1004 | |
1123 | |
1005 | |
1124 | |
1006 | |
1125 | |
… | |
… | |
1022 | |
1141 | |
1023 | @item |
1142 | @item |
1024 | pid-file = path |
1143 | pid-file = path |
1025 | |
1144 | |
1026 | @cindex pid-file |
1145 | @cindex pid-file |
1027 | The path to the pid file to check and create (default: @t{LOCALSTATEDIR/run/gvpe.pid}). |
1146 | 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 |
1147 | @refill |
1029 | |
1148 | |
1030 | |
1149 | |
1031 | @item |
1150 | @item |
1032 | private-key = relative-path-to-key |
1151 | private-key = relative-path-to-key |
… | |
… | |
1040 | |
1159 | |
1041 | @item |
1160 | @item |
1042 | rekey = seconds |
1161 | rekey = seconds |
1043 | |
1162 | |
1044 | @cindex rekey |
1163 | @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. |
1164 | 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 |
1165 | @refill |
1047 | |
1166 | |
1048 | |
1167 | |
1049 | @item |
1168 | @item |
1050 | nfmark = integer |
1169 | seed-device = path |
1051 | |
1170 | |
1052 | @cindex nfmark |
1171 | @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. |
1172 | 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 |
1173 | @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: |
1174 | On program start and every seed-interval, gvpe will read 64 octets. |
1056 | @refill |
1175 | @refill |
|
|
1176 | 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). |
|
|
1177 | @refill |
1057 | |
1178 | |
1058 | |
1179 | |
1059 | @example |
1180 | @item |
1060 | ip rule add not fwmark 1000 lookup 99 |
1181 | seed-interval = seconds |
1061 | @end example |
|
|
1062 | |
1182 | |
|
|
1183 | @cindex seed-interval |
|
|
1184 | The number of seconds between reseeds of the random number generator (default: @t{3613}). A value of @t{0} disables this regular reseeding. |
|
|
1185 | @refill |
|
|
1186 | |
|
|
1187 | |
|
|
1188 | @item |
|
|
1189 | serial = string |
|
|
1190 | |
|
|
1191 | @cindex serial |
|
|
1192 | 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. |
|
|
1193 | @refill |
|
|
1194 | It's recommended to specify this is a date string such as @t{2013-05-05} or @t{20121205084417).} |
|
|
1195 | @refill |
|
|
1196 | The exact algorithm is as this: if a connection request is received form a node with an identical serial, then it succeeds normally. |
|
|
1197 | @refill |
|
|
1198 | If the remote serial is lower than the local serial, it is ignored. |
|
|
1199 | @refill |
|
|
1200 | If the remote serial is higher than the local serial, a warning message is logged. |
|
|
1201 | @refill |
1063 | @end itemize |
1202 | @end itemize |
1064 | |
1203 | |
1065 | |
1204 | |
1066 | |
1205 | |
1067 | @subsection NODE SPECIFIC SETTINGS |
1206 | @subsection NODE SPECIFIC SETTINGS |
… | |
… | |
1206 | enable-udp = yes|true|on | no|false|off |
1345 | enable-udp = yes|true|on | no|false|off |
1207 | |
1346 | |
1208 | @cindex enable-udp |
1347 | @cindex enable-udp |
1209 | See gvpe.protocol(7) for a description of the UDP transport protocol. |
1348 | See gvpe.protocol(7) for a description of the UDP transport protocol. |
1210 | @refill |
1349 | @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). |
1350 | 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 |
1351 | @refill |
1215 | |
1352 | |
1216 | |
1353 | |
1217 | @item |
1354 | @item |
1218 | hostname = hostname | ip [can not be defaulted] |
1355 | 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. |
1386 | 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 |
1387 | @refill |
1251 | |
1388 | |
1252 | |
1389 | |
1253 | @item |
1390 | @item |
|
|
1391 | low-power = yes|true|on | no|false|off |
|
|
1392 | |
|
|
1393 | @cindex low-power |
|
|
1394 | 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. |
|
|
1395 | @refill |
|
|
1396 | The typical low-power node would be a mobile phone, where wakeups and encryption can significantly increase power drain. |
|
|
1397 | @refill |
|
|
1398 | |
|
|
1399 | |
|
|
1400 | @item |
1254 | max-retry = positive-number |
1401 | max-retry = positive-number |
1255 | |
1402 | |
1256 | @cindex max-retry |
1403 | @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. |
1404 | 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 |
1405 | @refill |
… | |
… | |
1340 | |
1487 | |
1341 | |
1488 | |
1342 | @item |
1489 | @item |
1343 | hostkey |
1490 | hostkey |
1344 | |
1491 | |
1345 | The private key (taken from @t{hostkeys/nodename}) of the current host. |
1492 | The (default path of the) private key of the current host. |
1346 | @refill |
1493 | @refill |
1347 | |
1494 | |
1348 | |
1495 | |
1349 | @item |
1496 | @item |
1350 | pubkey/nodename |
1497 | pubkey/nodename |
… | |
… | |
1626 | |
1773 | |
1627 | |
1774 | |
1628 | @section Overview |
1775 | @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. |
1776 | 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 |
1777 | @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. |
1778 | 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 |
1779 | @refill |
1633 | |
1780 | |
1634 | |
1781 | |
1635 | @section PART 1: Transport protocols |
1782 | @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. |
1783 | 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. |
1810 | It should be used if RAW IP is not available. |
1664 | @refill |
1811 | @refill |
1665 | |
1812 | |
1666 | |
1813 | |
1667 | @subsection TCP |
1814 | @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. |
1815 | 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 |
1816 | @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. |
1817 | 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 |
1818 | @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. |
1819 | 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 |
1820 | @refill |
… | |
… | |
1680 | @refill |
1827 | @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. |
1828 | 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 |
1829 | @refill |
1683 | In addition, the same problems as the TCP transport also plague this protocol. |
1830 | In addition, the same problems as the TCP transport also plague this protocol. |
1684 | @refill |
1831 | @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). |
1832 | 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 |
1833 | @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). |
1834 | 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 |
1835 | @refill |
1689 | Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly. |
1836 | Fine-tuning needs to be done by editing @t{src/vpn_dns.C} directly. |
1690 | @refill |
1837 | @refill |
… | |
… | |
1704 | +------+------+--------+------+ |
1851 | +------+------+--------+------+ |
1705 | | HMAC | TYPE | SRCDST | DATA | |
1852 | | HMAC | TYPE | SRCDST | DATA | |
1706 | +------+------+--------+------+ |
1853 | +------+------+--------+------+ |
1707 | @end example |
1854 | @end example |
1708 | |
1855 | |
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. |
1856 | 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 |
1857 | @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.). |
1858 | 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 |
1859 | @refill |
1713 | SRCDST is a three byte field which contains the source and destination node IDs (12 bits each). |
1860 | SRCDST is a three byte field which contains the source and destination node IDs (12 bits each). |
1714 | @refill |
1861 | @refill |
… | |
… | |
1722 | +------+------+--------+------+-------+------+ |
1869 | +------+------+--------+------+-------+------+ |
1723 | @end example |
1870 | @end example |
1724 | |
1871 | |
1725 | RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes. |
1872 | RAND is a sequence of fully random bytes, used to increase the entropy of the data for encryption purposes. |
1726 | @refill |
1873 | @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. |
1874 | 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 |
1875 | @refill |
|
|
1876 | The encryption is done on RAND+SEQNO+DATA in CBC mode with zero IV (or, equivalently, the IV is RAND+SEQNO, encrypted with the block cipher, unless RAND size is decreased or increased over the default value). |
|
|
1877 | @refill |
|
|
1878 | The random prefix itself is generated by using AES in CTR mode with a random key and starting value, which should make them unpredictable even before encrypting them again. The sequence number additionally ensures that the IV is unique. |
|
|
1879 | @refill |
1729 | |
1880 | |
1730 | |
1881 | |
1731 | @subsection The authentication protocol |
1882 | @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. |
1883 | 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 |
1884 | @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. |
1885 | 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 |
1886 | @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. |
1887 | 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 |
1888 | @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. |
1889 | In detail, the challenge consist of: |
1739 | @refill |
1890 | @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). |
1891 | |
|
|
1892 | |
|
|
1893 | @example |
|
|
1894 | RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1 |
|
|
1895 | @end example |
|
|
1896 | |
|
|
1897 | 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. |
|
|
1898 | @refill |
|
|
1899 | The remote node decrypts the RSA data, generates its own ECDH key (ECDH2), and replies with: |
|
|
1900 | @refill |
|
|
1901 | |
|
|
1902 | |
|
|
1903 | @example |
|
|
1904 | HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2 |
|
|
1905 | @end example |
|
|
1906 | |
|
|
1907 | 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. |
|
|
1908 | @refill |
|
|
1909 | 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). |
|
|
1910 | @refill |
|
|
1911 | The HMAC key for sending is generated as follow: |
|
|
1912 | @refill |
|
|
1913 | |
|
|
1914 | |
|
|
1915 | @example |
|
|
1916 | HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE) |
|
|
1917 | @end example |
|
|
1918 | |
|
|
1919 | It extracts from MAC and ECDH_SECRET using the @emph{remote} SALT, then expands using a static info string. |
|
|
1920 | @refill |
|
|
1921 | The cipher key is generated in the same way, except using the CIPHER part of the original challenge. |
|
|
1922 | @refill |
|
|
1923 | 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. |
|
|
1924 | @refill |
|
|
1925 | 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 |
1926 | @refill |
1742 | |
1927 | |
1743 | |
1928 | |
1744 | @subsection Retrying |
1929 | @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. |
1930 | 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. |
1936 | 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 |
1937 | @refill |
1753 | |
1938 | |
1754 | |
1939 | |
1755 | @subsection Routing and Protocol translation |
1940 | @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: |
1941 | 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 |
1942 | @refill |
1758 | |
1943 | |
1759 | |
1944 | |
1760 | @itemize |
1945 | @itemize |
1761 | |
1946 | |
… | |
… | |
1783 | @item |
1968 | @item |
1784 | Failing all that, the packet will be dropped. |
1969 | Failing all that, the packet will be dropped. |
1785 | |
1970 | |
1786 | @end itemize |
1971 | @end itemize |
1787 | |
1972 | |
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. |
1973 | 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 |
1974 | @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. |
1975 | 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 |
1976 | @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. |
1977 | 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 |
1978 | @refill |
1794 | |
1979 | |
1795 | |
1980 | |
1796 | |
1981 | |
1797 | @node Simple Example,Complex Example,gvpe.protocol,Top |
1982 | @node Simple Example,Complex Example,gvpe.protocol,Top |