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

Comparing gvpe/doc/gvpe.protocol.7 (file contents):
Revision 1.13 by root, Fri Sep 20 11:57:03 2013 UTC vs.
Revision 1.14 by root, Wed Jun 18 20:40:51 2014 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) 1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
36.el\{\ 36.el\{\
37. ds -- \|\(em\| 37. ds -- \|\(em\|
38. ds PI \(*p 38. ds PI \(*p
39. ds L" `` 39. ds L" ``
40. ds R" '' 40. ds R" ''
41. ds C`
42. ds C'
41'br\} 43'br\}
42.\" 44.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
45.el .ds Aq ' 47.el .ds Aq '
46.\" 48.\"
47.\" If the F register is turned on, we'll generate index entries on stderr for 49.\" If the F register is turned on, we'll generate index entries on stderr for
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" entries marked with X<> in POD. Of course, you'll have to process the 51.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
51.ie \nF \{\ 53.\"
54.\" Avoid warning from groff about undefined register 'F'.
52. de IX 55.de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
54.. 56..
55. nr % 0 57.nr rF 0
56. rr F 58.if \n(.g .if rF .nr rF 1
57.\} 59.if (\n(rF:(\n(.g==0)) \{
58.el \{\ 60. if \nF \{
59. de IX 61. de IX
62. tm Index:\\$1\t\\n%\t"\\$2"
60.. 63..
64. if !\nF==2 \{
65. nr % 0
66. nr F 2
67. \}
68. \}
61.\} 69.\}
70.rr rF
62.\" 71.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 72.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts. 73.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff 74. \" fudge factors for nroff and troff
66.if n \{\ 75.if n \{\
122.\} 131.\}
123.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
124.\" ======================================================================== 133.\" ========================================================================
125.\" 134.\"
126.IX Title "GVPE.PROTOCOL 7" 135.IX Title "GVPE.PROTOCOL 7"
127.TH GVPE.PROTOCOL 7 "2013-07-19" "2.25" "GNU Virtual Private Ethernet" 136.TH GVPE.PROTOCOL 7 "2014-04-26" "2.25" "GNU Virtual Private Ethernet"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
130.if n .ad l 139.if n .ad l
131.nh 140.nh
132.SH "The GNU-VPE Protocols" 141.SH "The GNU-VPE Protocols"
133.IX Header "The GNU-VPE Protocols" 142.IX Header "The GNU-VPE Protocols"
134.SH "Overview" 143.SH "Overview"
135.IX Header "Overview" 144.IX Header "Overview"
136\&\s-1GVPE\s0 can make use of a number of protocols. One of them is the \s-1GNU\s0 \s-1VPE\s0 145\&\s-1GVPE\s0 can make use of a number of protocols. One of them is the \s-1GNU VPE\s0
137protocol which is used to authenticate tunnels and send encrypted data 146protocol which is used to authenticate tunnels and send encrypted data
138packets. This protocol is described in more detail the second part of this 147packets. This protocol is described in more detail the second part of this
139document. 148document.
140.PP 149.PP
141The first part of this document describes the transport protocols which 150The first part of this document describes the transport protocols which
142are used by \s-1GVPE\s0 to send it's data packets over the network. 151are used by \s-1GVPE\s0 to send its data packets over the network.
143.SH "PART 1: Transport protocols" 152.SH "PART 1: Transport protocols"
144.IX Header "PART 1: Transport protocols" 153.IX Header "PART 1: Transport protocols"
145\&\s-1GVPE\s0 offers a wide range of transport protocols that can be used to 154\&\s-1GVPE\s0 offers a wide range of transport protocols that can be used to
146interchange data between nodes. Protocols differ in their overhead, speed, 155interchange data between nodes. Protocols differ in their overhead, speed,
147reliability, and robustness. 156reliability, and robustness.
148.PP 157.PP
149The following sections describe each transport protocol in more 158The following sections describe each transport protocol in more
150detail. They are sorted by overhead/efficiency, the most efficient 159detail. They are sorted by overhead/efficiency, the most efficient
151transport is listed first: 160transport is listed first:
152.SS "\s-1RAW\s0 \s-1IP\s0" 161.SS "\s-1RAW IP\s0"
153.IX Subsection "RAW IP" 162.IX Subsection "RAW IP"
154This protocol is the best choice, performance-wise, as the minimum 163This protocol is the best choice, performance-wise, as the minimum
155overhead per packet is only 38 bytes. 164overhead per packet is only 38 bytes.
156.PP 165.PP
157It works by sending the \s-1VPN\s0 payload using raw \s-1IP\s0 frames (using the 166It works by sending the \s-1VPN\s0 payload using raw \s-1IP\s0 frames (using the
176.IX Subsection "UDP" 185.IX Subsection "UDP"
177This is a good general choice for the transport protocol as \s-1UDP\s0 packets 186This is a good general choice for the transport protocol as \s-1UDP\s0 packets
178tunnel well through most firewalls and routers, and the overhead per 187tunnel well through most firewalls and routers, and the overhead per
179packet is moderate (minimum 58 bytes). 188packet is moderate (minimum 58 bytes).
180.PP 189.PP
181It should be used if \s-1RAW\s0 \s-1IP\s0 is not available. 190It should be used if \s-1RAW IP\s0 is not available.
182.SS "\s-1TCP\s0" 191.SS "\s-1TCP\s0"
183.IX Subsection "TCP" 192.IX Subsection "TCP"
184This protocol is a very bad choice, as it not only has high overhead (more 193This protocol is a very bad choice, as it not only has high overhead (more
185than 60 bytes), but the transport also retries on it's own, which leads 194than 60 bytes), but the transport also retries on its own, which leads
186to congestion when the link has moderate packet loss (as both the \s-1TCP\s0 195to congestion when the link has moderate packet loss (as both the \s-1TCP\s0
187transport and the tunneled traffic will retry, increasing congestion more 196transport and the tunneled traffic will retry, increasing congestion more
188and more). It also has high latency and is quite inefficient. 197and more). It also has high latency and is quite inefficient.
189.PP 198.PP
190It's only useful when tunneling through firewalls that block better 199It's only useful when tunneling through firewalls that block better
192that supports the \s-1CONNECT\s0 method it can be used to tunnel through a web 201that supports the \s-1CONNECT\s0 method it can be used to tunnel through a web
193proxy. For this to work, the \f(CW\*(C`tcp\-port\*(C'\fR should be \f(CW443\fR (\f(CW\*(C`https\*(C'\fR), as 202proxy. For this to work, the \f(CW\*(C`tcp\-port\*(C'\fR should be \f(CW443\fR (\f(CW\*(C`https\*(C'\fR), as
194most proxies do not allow connections to other ports. 203most proxies do not allow connections to other ports.
195.PP 204.PP
196It is an abuse of the usage a proxy was designed for, so make sure you are 205It is an abuse of the usage a proxy was designed for, so make sure you are
197allowed to use it for \s-1GVPE\s0. 206allowed to use it for \s-1GVPE.\s0
198.PP 207.PP
199This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is 208This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is
200set to zero, other nodes cannot connect to this node directly. If the 209set to zero, other nodes cannot connect to this node directly. If the
201\&\f(CW\*(C`tcp\-port\*(C'\fR is non-zero, the node can act both as a client as well as a 210\&\f(CW\*(C`tcp\-port\*(C'\fR is non-zero, the node can act both as a client as well as a
202server. 211server.
236you some overview over the protocol. 245you some overview over the protocol.
237.SS "Anatomy of a \s-1VPN\s0 packet" 246.SS "Anatomy of a \s-1VPN\s0 packet"
238.IX Subsection "Anatomy of a VPN packet" 247.IX Subsection "Anatomy of a VPN packet"
239The exact layout and field lengths of a \s-1VPN\s0 packet is determined at 248The exact layout and field lengths of a \s-1VPN\s0 packet is determined at
240compile time and doesn't change. The same structure is used for all 249compile time and doesn't change. The same structure is used for all
241transport protocols, be it \s-1RAWIP\s0 or \s-1TCP\s0. 250transport protocols, be it \s-1RAWIP\s0 or \s-1TCP.\s0
242.PP 251.PP
243.Vb 3 252.Vb 3
244\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+ 253\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+
245\& | HMAC | TYPE | SRCDST | DATA | 254\& | HMAC | TYPE | SRCDST | DATA |
246\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+ 255\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+
247.Ve 256.Ve
248.PP 257.PP
249The \s-1HMAC\s0 field is present in all packets, even if not used (e.g. in auth 258The \s-1HMAC\s0 field is present in all packets, even if not used (e.g. in auth
250request packets), in which case it is set to all zeroes. The checksum 259request packets), in which case it is set to all zeroes. The \s-1MAC\s0 itself is
251itself is calculated over the \s-1TYPE\s0, \s-1SRCDST\s0 and \s-1DATA\s0 fields in all cases. 260calculated over the \s-1TYPE, SRCDST\s0 and \s-1DATA\s0 fields in all cases.
252.PP 261.PP
253The \s-1TYPE\s0 field is a single byte and determines the purpose of the packet 262The \s-1TYPE\s0 field is a single byte and determines the purpose of the packet
254(e.g. \s-1RESET\s0, \s-1COMPRESSED/UNCOMPRESSED\s0 \s-1DATA\s0, \s-1PING\s0, \s-1AUTH\s0 \s-1REQUEST/RESPONSE\s0, 263(e.g. \s-1RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE,
255\&\s-1CONNECT\s0 \s-1REQUEST/INFO\s0 etc.). 264CONNECT REQUEST/INFO\s0 etc.).
256.PP 265.PP
257\&\s-1SRCDST\s0 is a three byte field which contains the source and destination 266\&\s-1SRCDST\s0 is a three byte field which contains the source and destination
258node IDs (12 bits each). 267node IDs (12 bits each).
259.PP 268.PP
260The \s-1DATA\s0 portion differs between each packet type, naturally, and is the 269The \s-1DATA\s0 portion differs between each packet type, naturally, and is the
273\&\s-1SEQNO\s0 is a 32\-bit sequence number. It is negotiated at every connection 282\&\s-1SEQNO\s0 is a 32\-bit sequence number. It is negotiated at every connection
274initialization and starts at some random 31 bit value. \s-1GVPE\s0 currently uses 283initialization and starts at some random 31 bit value. \s-1GVPE\s0 currently uses
275a sliding window of 512 packets/sequence numbers to detect reordering, 284a sliding window of 512 packets/sequence numbers to detect reordering,
276duplication and replay attacks. 285duplication and replay attacks.
277.PP 286.PP
278The encryption is done on \s-1RAND+SEQNO+DATA\s0 in \s-1CBC\s0 mode with zero \s-1IV\s0 (or, 287The encryption is done on \s-1RAND+SEQNO+DATA\s0 in \s-1CBC\s0 mode with zero \s-1IV \s0(or,
279equivalently, the \s-1IV\s0 is \s-1RAND+SEQNO\s0, encrypted with the block cipher, 288equivalently, the \s-1IV\s0 is \s-1RAND+SEQNO,\s0 encrypted with the block cipher,
280unless \s-1RAND\s0 size is decreased or increased over the default value). 289unless \s-1RAND\s0 size is decreased or increased over the default value).
281.PP 290.PP
282The random prefix itself is generated by using \s-1AES\s0 in \s-1CTR\s0 mode with a 291The random prefix itself is generated by using \s-1AES\s0 in \s-1CTR\s0 mode with a
283random key and starting value, which should make them unpredictable even 292random key and starting value, which should make them unpredictable even
284before encrypting them again. The sequence number additionally ensures 293before encrypting them again. The sequence number additionally ensures
288Before nodes can exchange packets, they need to establish authenticity of 297Before nodes can exchange packets, they need to establish authenticity of
289the other side and a key. Every node has a private \s-1RSA\s0 key and the public 298the other side and a key. Every node has a private \s-1RSA\s0 key and the public
290\&\s-1RSA\s0 keys of all other nodes. 299\&\s-1RSA\s0 keys of all other nodes.
291.PP 300.PP
292When a node wants to establish a connection to another node, it sends an 301When a node wants to establish a connection to another node, it sends an
293RSA-OEAP-encrypted challenge and an \s-1ECDH\s0 key. The other node replies with 302RSA-OEAP-encrypted challenge and an \s-1ECDH \s0(curve25519) key. The other node
294it's own \s-1ECDH\s0 key and a \s-1HKDF\s0 of the challange and both \s-1ECDH\s0 keys to proof 303replies with its own \s-1ECDH\s0 key and a \s-1HKDF\s0 of the challenge and both \s-1ECDH\s0
295it's identity. 304keys to prove its identity.
296.PP 305.PP
297The remote node enganges in exactly the same protocol. When both nodes 306The remote node enganges in exactly the same protocol. When both nodes
298have exchanged their challenge and verified the response, they calculate a 307have exchanged their challenge and verified the response, they calculate a
299cipher key and a \s-1HMAC\s0 key and start exchanging data packets. 308cipher key and a \s-1HMAC\s0 key and start exchanging data packets.
300.PP 309.PP
304\& RSA\-OAEP (SEQNO MAC CIPHER SALT EXTRA\-AUTH) ECDH1 313\& RSA\-OAEP (SEQNO MAC CIPHER SALT EXTRA\-AUTH) ECDH1
305.Ve 314.Ve
306.PP 315.PP
307That is, it encrypts (with the public key of the remote node) an initial 316That is, it encrypts (with the public key of the remote node) an initial
308sequence number for data packets, key material for the \s-1HMAC\s0 key, key 317sequence number for data packets, key material for the \s-1HMAC\s0 key, key
309material for the cipher key, a salt used by the \s-1HKDF\s0 (as shown later) and 318material for the cipher key, a salt used by the \s-1HKDF \s0(as shown later) and
310some extra random bytes that are unused except for authentication. It also 319some extra random bytes that are unused except for authentication. It also
311sends the public key of a curve25519 exchange. 320sends the public key of a curve25519 exchange.
312.PP 321.PP
313The remote node decrypts the \s-1RSA\s0 data, generates it's own \s-1ECDH\s0 key (\s-1ECDH2\s0), and 322The remote node decrypts the \s-1RSA\s0 data, generates its own \s-1ECDH\s0 key (\s-1ECDH2\s0),
314replies with: 323and replies with:
315.PP 324.PP
316.Vb 1 325.Vb 1
317\& HKDF\-Expand (HKDF\-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2 326\& HKDF\-Expand (HKDF\-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
318.Ve 327.Ve
319.PP 328.PP
320That is, it extracts from the decrypted \s-1RSA\s0 challenge, using it's \s-1ECDH\s0 329That is, it extracts from the decrypted \s-1RSA\s0 challenge, using its \s-1ECDH\s0
321key as salt, and then expands using the requesting node's \s-1ECDH1\s0 key. The 330key as salt, and then expands using the requesting node's \s-1ECDH1\s0 key. The
322resulting has is returned as a proof that the node could decrypt the \s-1RSA\s0 331resulting hash is returned as a proof that the node could decrypt the \s-1RSA\s0
323challenge data, together with the \s-1ECDH\s0 key. 332challenge data, together with the \s-1ECDH\s0 key.
324.PP 333.PP
325After both nodes have done this to each other, they calculate the shared 334After both nodes have done this to each other, they calculate the shared
326\&\s-1ECDH\s0 secrets, cipher and \s-1HMAC\s0 keys for the session (each 335\&\s-1ECDH\s0 secret, cipher and \s-1HMAC\s0 keys for the session (each node generates two
327node generates two cipher and \s-1HMAC\s0 keys, one for sending and one for 336cipher and \s-1HMAC\s0 keys, one for sending and one for receiving).
328receiving).
329.PP 337.PP
330The \s-1HMAC\s0 key for sending is generated as follow: 338The \s-1HMAC\s0 key for sending is generated as follow:
331.PP 339.PP
332.Vb 1 340.Vb 1
333\& HMAC_KEY = HKDF\-Expand (HKDF\-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE) 341\& HMAC_KEY = HKDF\-Expand (HKDF\-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
334.Ve 342.Ve
335.PP 343.PP
336It extracts from \s-1MAC\s0 and \s-1ECDH_SECRET\s0 using the \fIremote\fR \s-1SALT\s0, then 344It extracts from \s-1MAC\s0 and \s-1ECDH_SECRET\s0 using the \fIremote\fR \s-1SALT,\s0 then
337expands using a static info string. 345expands using a static info string.
338.PP 346.PP
339The cipher key is generated in the same way, except using the \s-1CIPHER\s0 part 347The cipher key is generated in the same way, except using the \s-1CIPHER\s0 part
340of the original challenge. 348of the original challenge.
341.PP 349.PP
342The result of this process is to authenticate each node to the other 350The result of this process is to authenticate each node to the other
343node, while exchanging keys using both \s-1RSA\s0 and \s-1ECDH\s0, the latter providing 351node, while exchanging keys using both \s-1RSA\s0 and \s-1ECDH,\s0 the latter providing
344perfect forward secrecy. 352perfect forward secrecy.
345.PP 353.PP
346The protocol has been overdesigned where this was possible without 354The protocol has been overdesigned where this was possible without
347increasing implementation complexity, in an attempt to protect against 355increasing implementation complexity, in an attempt to protect against
348implementation or protocol failures. For example, if the \s-1ECDH\s0 challenge 356implementation or protocol failures. For example, if the \s-1ECDH\s0 challenge
349was found to be flawed, perfect forward secrecy would be lost, but 357was found to be flawed, perfect forward secrecy would be lost, but the
350the data would still be protected. Likewise, standard algorithms and 358data would likely still be protected. Likewise, standard algorithms and
351implementations are used where possible. 359implementations are used where possible.
352.SS "Retrying" 360.SS "Retrying"
353.IX Subsection "Retrying" 361.IX Subsection "Retrying"
354When there is no response to an auth request, the node will send auth 362When there is no response to an auth request, the node will send auth
355requests in bursts with an exponential back-off. After some time it will 363requests in bursts with an exponential back-off. After some time it will
391.IX Item "If no such router exists, then GVPE will simply send the packet to the node with the highest priority available." 399.IX Item "If no such router exists, then GVPE will simply send the packet to the node with the highest priority available."
392.IP "Failing all that, the packet will be dropped." 4 400.IP "Failing all that, the packet will be dropped." 4
393.IX Item "Failing all that, the packet will be dropped." 401.IX Item "Failing all that, the packet will be dropped."
394.PD 402.PD
395.PP 403.PP
396A host can usually declare itself unreachable directly by setting it's 404A host can usually declare itself unreachable directly by setting its
397port number(s) to zero. It can declare other hosts as unreachable by using 405port number(s) to zero. It can declare other hosts as unreachable by using
398a config-file that disables all protocols for these other hosts. Another 406a config-file that disables all protocols for these other hosts. Another
399option is to disable all protocols on that host in the other config files. 407option is to disable all protocols on that host in the other config files.
400.PP 408.PP
401If two hosts cannot connect to each other because their \s-1IP\s0 address(es) 409If two hosts cannot connect to each other because their \s-1IP\s0 address(es)
407connection to the other peer, which is usually possible even when both 415connection to the other peer, which is usually possible even when both
408hosts are behind a \s-1NAT\s0 gateway. 416hosts are behind a \s-1NAT\s0 gateway.
409.PP 417.PP
410Routing via other nodes works because the \s-1SRCDST\s0 field is not encrypted, 418Routing via other nodes works because the \s-1SRCDST\s0 field is not encrypted,
411so the router can just forward the packet to the destination host. Since 419so the router can just forward the packet to the destination host. Since
412each host uses it's own private key, the router will not be able to 420each host uses its own private key, the router will not be able to
413decrypt or encrypt packets, it will just act as a simple router and 421decrypt or encrypt packets, it will just act as a simple router and
414protocol translator. 422protocol translator.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines