ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.protocol.7.pod
(Generate patch)

Comparing gvpe/doc/gvpe.protocol.7.pod (file contents):
Revision 1.3 by pcg, Thu Mar 17 22:24:31 2005 UTC vs.
Revision 1.13 by root, Sat Apr 26 19:05:56 2014 UTC

6protocol which is used to authenticate tunnels and send encrypted data 6protocol which is used to authenticate tunnels and send encrypted data
7packets. This protocol is described in more detail the second part of this 7packets. This protocol is described in more detail the second part of this
8document. 8document.
9 9
10The first part of this document describes the transport protocols which 10The first part of this document describes the transport protocols which
11are used by GVPE to send it's data packets over the network. 11are used by GVPE to send its data packets over the network.
12 12
13=head1 PART 1: Tansport protocols 13=head1 PART 1: Transport protocols
14 14
15GVPE offers a range of transport protocols that can be used to interchange 15GVPE offers a wide range of transport protocols that can be used to
16data between nodes. Protocols differ in their overhead, speed, 16interchange data between nodes. Protocols differ in their overhead, speed,
17reliability, and robustness. 17reliability, and robustness.
18 18
19The following sections describe each transport protocol in more 19The following sections describe each transport protocol in more
20detail. They are sorted by overhead/efficiency, the most efficient 20detail. They are sorted by overhead/efficiency, the most efficient
21transprot is listed first: 21transport is listed first:
22 22
23=head2 RAW IP 23=head2 RAW IP
24 24
25This protocol is the best choice, performance-wise, as the minimum 25This protocol is the best choice, performance-wise, as the minimum
26overhead per packet is only 38 bytes. 26overhead per packet is only 38 bytes.
27 27
28It works by sending the VPN payload using raw ip frames (using the 28It works by sending the VPN payload using raw IP frames (using the
29protocol set by C<ip-proto>). 29protocol set by C<ip-proto>).
30 30
31Using raw ip frames has the drawback that many firewalls block "unknown" 31Using raw IP frames has the drawback that many firewalls block "unknown"
32protocols, so this transport only works if you have full IP connectivity 32protocols, so this transport only works if you have full IP connectivity
33between nodes. 33between nodes.
34 34
35=head2 ICMP 35=head2 ICMP
36 36
37This protocol offers very low overhead (minimum 42 bytes), and can 37This protocol offers very low overhead (minimum 42 bytes), and can
38sometimes tunnel through firewalls when other protocols cannot. 38sometimes tunnel through firewalls when other protocols can not.
39 39
40It works by prepending a ICMP header with type C<icmp-type> and a code 40It works by prepending an ICMP header with type C<icmp-type> and a code
41of C<255>. The default C<icmp-type> is C<echo-reply>, so the resulting 41of C<255>. The default C<icmp-type> is C<echo-reply>, so the resulting
42packets look like echo replies, which looks rather strange to network 42packets look like echo replies, which looks rather strange to network
43admins. 43administrators.
44 44
45This transport should only be used if other transports (i.e. raw ip) are 45This transport should only be used if other transports (i.e. raw IP) are
46not available or undesirable (due to their overhead). 46not available or undesirable (due to their overhead).
47 47
48=head2 UDP 48=head2 UDP
49 49
50This is a good general choice for the transport protocol as UDP packets 50This is a good general choice for the transport protocol as UDP packets
54It should be used if RAW IP is not available. 54It should be used if RAW IP is not available.
55 55
56=head2 TCP 56=head2 TCP
57 57
58This protocol is a very bad choice, as it not only has high overhead (more 58This protocol is a very bad choice, as it not only has high overhead (more
59than 60 bytes), but the transport also retries on it's own, which leads 59than 60 bytes), but the transport also retries on its own, which leads
60to congestion when the link has moderate packet loss (as both the TCP 60to congestion when the link has moderate packet loss (as both the TCP
61transport and the tunneled traffic will retry, increasing congestion more 61transport and the tunneled traffic will retry, increasing congestion more
62and more). It also has high latency and is quite inefficient. 62and more). It also has high latency and is quite inefficient.
63 63
64It's only useful when tunneling through firewalls that block better 64It's only useful when tunneling through firewalls that block better
68most proxies do not allow connections to other ports. 68most proxies do not allow connections to other ports.
69 69
70It is an abuse of the usage a proxy was designed for, so make sure you are 70It is an abuse of the usage a proxy was designed for, so make sure you are
71allowed to use it for GVPE. 71allowed to use it for GVPE.
72 72
73This protocol also has server and client sides. If the C<tcp-port> is set 73This protocol also has server and client sides. If the C<tcp-port> is
74to zero, other nodes cannot connect to this node directly (and C<tcp-port> 74set to zero, other nodes cannot connect to this node directly. If the
75zero cannot be used). If the C<tcp-port> is non-zero, the node can act 75C<tcp-port> is non-zero, the node can act both as a client as well as a
76both as a client as well as a server. 76server.
77 77
78=head2 DNS 78=head2 DNS
79 79
80B<WARNING:> Parsing and generating DNS packets is rather tricky. The code 80B<WARNING:> Parsing and generating DNS packets is rather tricky. The code
81almost certainly contains buffer overflows and other, likely exploitable, 81almost certainly contains buffer overflows and other, likely exploitable,
89traffic even if it doesn't need to transport packets. 89traffic even if it doesn't need to transport packets.
90 90
91In addition, the same problems as the TCP transport also plague this 91In addition, the same problems as the TCP transport also plague this
92protocol. 92protocol.
93 93
94Most configuration needs to be done by editing C<src/vpn_dns.C> directly.
95
96It's only use is to tunnel through firewalls that do not allow direct 94Its only use is to tunnel through firewalls that do not allow direct
97internet access. Similar to using a HTTP proxy (as the TCP transport 95internet access. Similar to using a HTTP proxy (as the TCP transport
98does), it uses a local DNS server/forwarder (given by the C<dns-forw-host> 96does), it uses a local DNS server/forwarder (given by the C<dns-forw-host>
99configuration value) as a proxy to send and receive data as a client, 97configuration value) as a proxy to send and receive data as a client,
100and a C<NS> record pointing to the GVPE server (as given by the 98and an C<NS> record pointing to the GVPE server (as given by the
101C<dns-hostname> directive). 99C<dns-hostname> directive).
102 100
103The only good side of this protocol is that it can tunnel through most 101The only good side of this protocol is that it can tunnel through most
104firewalls undetected, iff the local DNS server/forwarder is sane (which is 102firewalls mostly undetected, iff the local DNS server/forwarder is sane
105true for most routers, wlan gateways and nameservers). 103(which is true for most routers, wireless LAN gateways and nameservers).
104
105Fine-tuning needs to be done by editing C<src/vpn_dns.C> directly.
106 106
107=head1 PART 2: The GNU VPE protocol 107=head1 PART 2: The GNU VPE protocol
108 108
109This section, unfortunately, is not yet finished, although the protocol 109This section, unfortunately, is not yet finished, although the protocol
110is stable (until bugs in the cryptography are found, which will likely 110is stable (until bugs in the cryptography are found, which will likely
112you some overview over the protocol. 112you some overview over the protocol.
113 113
114=head2 Anatomy of a VPN packet 114=head2 Anatomy of a VPN packet
115 115
116The exact layout and field lengths of a VPN packet is determined at 116The exact layout and field lengths of a VPN packet is determined at
117compiletime and doesn't change. The same structure is used for all 117compile time and doesn't change. The same structure is used for all
118transort protocols, be it RAWIP or TCP. 118transport protocols, be it RAWIP or TCP.
119 119
120 +------+------+--------+------+ 120 +------+------+--------+------+
121 | HMAC | TYPE | SRCDST | DATA | 121 | HMAC | TYPE | SRCDST | DATA |
122 +------+------+--------+------+ 122 +------+------+--------+------+
123 123
128The TYPE field is a single byte and determines the purpose of the packet 128The TYPE field is a single byte and determines the purpose of the packet
129(e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, 129(e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE,
130CONNECT REQUEST/INFO etc.). 130CONNECT REQUEST/INFO etc.).
131 131
132SRCDST is a three byte field which contains the source and destination 132SRCDST is a three byte field which contains the source and destination
133node ids (12 bits each). The protocol does not yet scale well beyond 30+ 133node IDs (12 bits each).
134hosts, since all hosts must connect to each other once on startup. But if
135restarts are rare or tolerable and most connections are on demand, much
136larger networks are feasible.
137 134
138The DATA portion differs between each packet type, naturally, and is the 135The DATA portion differs between each packet type, naturally, and is the
139only part that can be encrypted. Data packets contain more fields, as 136only part that can be encrypted. Data packets contain more fields, as
140shown: 137shown:
141 138
145 142
146RAND is a sequence of fully random bytes, used to increase the entropy of 143RAND is a sequence of fully random bytes, used to increase the entropy of
147the data for encryption purposes. 144the data for encryption purposes.
148 145
149SEQNO is a 32-bit sequence number. It is negotiated at every connection 146SEQNO is a 32-bit sequence number. It is negotiated at every connection
150initialization and starts at some random 31 bit value. VPE currently uses 147initialization and starts at some random 31 bit value. GVPE currently uses
151a sliding window of 512 packets/sequence numbers to detect reordering, 148a sliding window of 512 packets/sequence numbers to detect reordering,
152duplication and reply attacks. 149duplication and replay attacks.
153 150
151The encryption is done on RAND+SEQNO+DATA in CBC mode with zero IV (or,
152equivalently, the IV is RAND+SEQNO, encrypted with the block cipher,
153unless RAND size is decreased or increased over the default value).
154
155The random prefix itself is generated by using AES in CTR mode with a
156random key and starting value, which should make them unpredictable even
157before encrypting them again. The sequence number additionally ensures
158that the IV is unique.
159
154=head2 The authentification protocol 160=head2 The authentication/key exchange protocol
155 161
156Before hosts can exchange packets, they need to establish authenticity of 162Before nodes can exchange packets, they need to establish authenticity of
157the other side and a key. Every host has a private RSA key and the public 163the other side and a key. Every node has a private RSA key and the public
158RSA keys of all other hosts. 164RSA keys of all other nodes.
159 165
160A host establishes a simplex connection by sending the other host a 166When a node wants to establish a connection to another node, it sends an
161RSA encrypted challenge containing a random challenge (consisting of 167RSA-OEAP-encrypted challenge and an ECDH (curve25519) key. The other node
162the encryption key to use when sending packets, more random data and 168replies with its own ECDH key and a HKDF of the challenge and both ECDH
163PKCS1_OAEP padding) and a random 16 byte "challenge-id" (used to detect 169keys to prove its identity.
164duplicate auth packets). The destination host will respond by replying
165with an (unencrypted) RIPEMD160 hash of the decrypted challenge, which
166will authentify that host. The destination host will also set the outgoing
167encryption parameters as given in the packet.
168 170
169When the source host receives a correct auth reply (by verifying the 171The remote node enganges in exactly the same protocol. When both nodes
170hash and the id, which will expire after 120 seconds), it will start to 172have exchanged their challenge and verified the response, they calculate a
171accept data packets from the destination host. 173cipher key and a HMAC key and start exchanging data packets.
172 174
173This means that a host can only initate a simplex connection, telling the 175In detail, the challenge consist of:
174other side the key it has to use when it sends packets. The challenge
175reply is only used to set the current IP address of the other side and
176protocol parameters.
177 176
178This protocol is completely symmetric, so to be able to send packets the 177 RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
179destination host must send a challenge in the exact same way as already 178
180described (so, in essence, two simplex connections are created per host 179That is, it encrypts (with the public key of the remote node) an initial
181pair). 180sequence number for data packets, key material for the HMAC key, key
181material for the cipher key, a salt used by the HKDF (as shown later) and
182some extra random bytes that are unused except for authentication. It also
183sends the public key of a curve25519 exchange.
184
185The remote node decrypts the RSA data, generates its own ECDH key (ECDH2),
186and replies with:
187
188 HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
189
190That is, it extracts from the decrypted RSA challenge, using its ECDH
191key as salt, and then expands using the requesting node's ECDH1 key. The
192resulting hash is returned as a proof that the node could decrypt the RSA
193challenge data, together with the ECDH key.
194
195After both nodes have done this to each other, they calculate the shared
196ECDH secret, cipher and HMAC keys for the session (each node generates two
197cipher and HMAC keys, one for sending and one for receiving).
198
199The HMAC key for sending is generated as follow:
200
201 HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
202
203It extracts from MAC and ECDH_SECRET using the I<remote> SALT, then
204expands using a static info string.
205
206The cipher key is generated in the same way, except using the CIPHER part
207of the original challenge.
208
209The result of this process is to authenticate each node to the other
210node, while exchanging keys using both RSA and ECDH, the latter providing
211perfect forward secrecy.
212
213The protocol has been overdesigned where this was possible without
214increasing implementation complexity, in an attempt to protect against
215implementation or protocol failures. For example, if the ECDH challenge
216was found to be flawed, perfect forward secrecy would be lost, but the
217data would likely still be protected. Likewise, standard algorithms and
218implementations are used where possible.
182 219
183=head2 Retrying 220=head2 Retrying
184 221
185When there is no response to an auth request, the host will send auth 222When there is no response to an auth request, the node will send auth
186requests in bursts with an exponential backoff. After some time it will 223requests in bursts with an exponential back-off. After some time it will
187resort to PING packets, which are very small (8 bytes) and lightweight 224resort to PING packets, which are very small (8 bytes + protocol header)
188(no RSA operations required). A host that receives ping requests from an 225and lightweight (no RSA operations required). A node that receives ping
189unconnected peer will respond by trying to create a connection. 226requests from an unconnected peer will respond by trying to create a
227connection.
190 228
191In addition to the exponential backoff, there is a global rate-limit on 229In addition to the exponential back-off, there is a global rate-limit on
192a per-IP base. It allows long bursts but will limit total packet rate to 230a per-IP base. It allows long bursts but will limit total packet rate to
193something like one control packet every ten seconds, to avoid accidental 231something like one control packet every ten seconds, to avoid accidental
194floods due to protocol problems (like a RSA key file mismatch between two 232floods due to protocol problems (like a RSA key file mismatch between two
195hosts). 233nodes).
234
235The intervals between retries are limited by the C<max-retry>
236configuration value. A node with C<connect> = C<always> will always retry,
237a node with C<connect> = C<ondemand> will only try (and re-try) to connect
238as long as there are packets in the queue, usually this limits the retry
239period to C<max-ttl> seconds.
240
241Sending packets over the VPN will reset the retry intervals as well, which
242means as long as somebody is trying to send packets to a given node, GVPE
243will try to connect every few seconds.
196 244
197=head2 Routing and Protocol translation 245=head2 Routing and Protocol translation
198 246
199The gvpe routing algorithm is easy: there isn't any routing. GVPE always 247The GVPE routing algorithm is easy: there isn't much routing to speak
200tries to establish direct connections, if the protocol abilities of the 248of: When routing packets to another node, GVPE tries the following
201two hosts allow it. 249options, in order:
202 250
251=over 4
252
203If the two hosts should be able to reach each other (common protocol, ip 253=item If the two nodes should be able to reach each other directly (common
204and port all known), but cannot (network down), then there will be no 254protocol, port known), then GVPE will send the packet directly to the
205connection, point. 255other node.
206 256
257=item If this isn't possible (e.g. because the node doesn't have a
258C<hostname> or known port), but the nodes speak a common protocol and a
259router is available, then GVPE will ask a router to "mediate" between both
260nodes (see below).
261
262=item If a direct connection isn't possible (no common protocols) or
263forbidden (C<deny-direct>) and there are any routers, then GVPE will try
264to send packets to the router with the highest priority that is connected
265already I<and> is able (as specified by the config file) to connect
266directly to the target node.
267
268=item If no such router exists, then GVPE will simply send the packet to
269the node with the highest priority available.
270
271=item Failing all that, the packet will be dropped.
272
273=back
274
207A host can usually declare itself unreachable directly by setting it's 275A host can usually declare itself unreachable directly by setting its
208port number(s) to zero. It can declare other hosts as unreachable by using 276port number(s) to zero. It can declare other hosts as unreachable by using
209a config-file that disables all protocols for these other hosts. 277a config-file that disables all protocols for these other hosts. Another
278option is to disable all protocols on that host in the other config files.
210 279
211If two hosts cannot connect to each other because their IP address(es) 280If two hosts cannot connect to each other because their IP address(es)
212are not known (such as dialup hosts), one side will send a connection 281are not known (such as dial-up hosts), one side will send a I<mediated>
213request to a router (routers must be configured to act as routers!), which 282connection request to a router (routers must be configured to act as
214will send both the originating and the destination host a connection info 283routers!), which will send both the originating and the destination host
215request with protocol information and IP address of the other host (if 284a connection info request with protocol information and IP address of the
216known). Both hosts will then try to establish a connection to the other 285other host (if known). Both hosts will then try to establish a direct
217peer, which is usually possible even when both hosts are behind a NAT 286connection to the other peer, which is usually possible even when both
218gateway. 287hosts are behind a NAT gateway.
219 288
220If the hosts cannot reach each other because they have no common protocol, 289Routing via other nodes works because the SRCDST field is not encrypted,
221the originator instead use the router with highest priority and matching
222protocol as peer. Since the SRCDST field is not encrypted, the router host
223can just forward the packet to the destination host. Since each host uses 290so the router can just forward the packet to the destination host. Since
224it's own private key, the router will not be able to decrypt or encrypt 291each host uses its own private key, the router will not be able to
225packets, it will just act as a simple router and protocol translator. 292decrypt or encrypt packets, it will just act as a simple router and
293protocol translator.
226 294
227When no router is connected, the host will aggressively try to connect to
228all routers, and if a router is asked for an unconnected host it will try
229to ask another router to establish the connection.
230 295
231... more not yet written about the details of the routing, please bug me
232...
233

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines