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.11 by root, Sun Mar 6 19:40:27 2011 UTC vs.
Revision 1.12 by root, Sat Jul 13 04:10:29 2013 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C`
34. ds C'
35'br\}
36.el\{\
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
41'br\}
42.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
47.\" 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
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
51.ie \nF \{\
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
54..
55. nr % 0
56. rr F
57.\}
58.el \{\
59. de IX
60..
61.\}
62.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
66.if n \{\
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
72.\}
73.if t \{\
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
79.\}
80. \" simple accents for nroff and troff
81.if n \{\
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
88.\}
89.if t \{\
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96.\}
97. \" troff and (daisy-wheel) nroff accents
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
107. \" corrections for vroff
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110. \" for low resolution devices (crt and lpr)
111.if \n(.H>23 .if \n(.V>19 \
112\{\
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
122.\}
123.rm #[ #] #H #V #F C
124.\" ========================================================================
125.\"
126.IX Title "GVPE.PROTOCOL 7"
127.TH GVPE.PROTOCOL 7 "2013-07-12" "2.24" "GNU Virtual Private Ethernet"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
132.SH "The GNU-VPE Protocols"
133.IX Header "The GNU-VPE Protocols"
134.SH "Overview"
135.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
137protocol which is used to authenticate tunnels and send encrypted data
138packets. This protocol is described in more detail the second part of this
139document.
140.PP
141The 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.
143.SH "PART 1: Transport protocols"
144.IX Header "PART 1: Transport protocols"
145\&\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,
147reliability, and robustness.
148.PP
149The following sections describe each transport protocol in more
150detail. They are sorted by overhead/efficiency, the most efficient
151transport is listed first:
152.SS "\s-1RAW\s0 \s-1IP\s0"
153.IX Subsection "RAW IP"
154This protocol is the best choice, performance-wise, as the minimum
155overhead per packet is only 38 bytes.
156.PP
157It works by sending the \s-1VPN\s0 payload using raw \s-1IP\s0 frames (using the
158protocol set by \f(CW\*(C`ip\-proto\*(C'\fR).
159.PP
160Using raw \s-1IP\s0 frames has the drawback that many firewalls block \*(L"unknown\*(R"
161protocols, so this transport only works if you have full \s-1IP\s0 connectivity
162between nodes.
163.SS "\s-1ICMP\s0"
164.IX Subsection "ICMP"
165This protocol offers very low overhead (minimum 42 bytes), and can
166sometimes tunnel through firewalls when other protocols can not.
167.PP
168It works by prepending an \s-1ICMP\s0 header with type \f(CW\*(C`icmp\-type\*(C'\fR and a code
169of \f(CW255\fR. The default \f(CW\*(C`icmp\-type\*(C'\fR is \f(CW\*(C`echo\-reply\*(C'\fR, so the resulting
170packets look like echo replies, which looks rather strange to network
171administrators.
172.PP
173This transport should only be used if other transports (i.e. raw \s-1IP\s0) are
174not available or undesirable (due to their overhead).
175.SS "\s-1UDP\s0"
176.IX Subsection "UDP"
177This 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
179packet is moderate (minimum 58 bytes).
180.PP
181It should be used if \s-1RAW\s0 \s-1IP\s0 is not available.
182.SS "\s-1TCP\s0"
183.IX Subsection "TCP"
184This 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
186to congestion when the link has moderate packet loss (as both the \s-1TCP\s0
187transport and the tunneled traffic will retry, increasing congestion more
188and more). It also has high latency and is quite inefficient.
189.PP
190It's only useful when tunneling through firewalls that block better
191protocols. If a node doesn't have direct internet access but a \s-1HTTP\s0 proxy
192that 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
194most proxies do not allow connections to other ports.
195.PP
196It is an abuse of the usage a proxy was designed for, so make sure you are
197allowed to use it for \s-1GVPE\s0.
198.PP
199This 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
201\&\f(CW\*(C`tcp\-port\*(C'\fR is non-zero, the node can act both as a client as well as a
202server.
203.SS "\s-1DNS\s0"
204.IX Subsection "DNS"
205\&\fB\s-1WARNING:\s0\fR Parsing and generating \s-1DNS\s0 packets is rather tricky. The code
206almost certainly contains buffer overflows and other, likely exploitable,
207bugs. You have been warned.
208.PP
209This is the worst choice of transport protocol with respect to overhead
210(overhead can be 2\-3 times higher than the transferred data), and latency
211(which can be many seconds). Some \s-1DNS\s0 servers might not be prepared to
212handle the traffic and drop or corrupt packets. The client also has to
213constantly poll the server for data, so the client will constantly create
214traffic even if it doesn't need to transport packets.
215.PP
216In addition, the same problems as the \s-1TCP\s0 transport also plague this
217protocol.
218.PP
219Its only use is to tunnel through firewalls that do not allow direct
220internet access. Similar to using a \s-1HTTP\s0 proxy (as the \s-1TCP\s0 transport
221does), it uses a local \s-1DNS\s0 server/forwarder (given by the \f(CW\*(C`dns\-forw\-host\*(C'\fR
222configuration value) as a proxy to send and receive data as a client,
223and an \f(CW\*(C`NS\*(C'\fR record pointing to the \s-1GVPE\s0 server (as given by the
224\&\f(CW\*(C`dns\-hostname\*(C'\fR directive).
225.PP
226The only good side of this protocol is that it can tunnel through most
227firewalls mostly undetected, iff the local \s-1DNS\s0 server/forwarder is sane
228(which is true for most routers, wireless \s-1LAN\s0 gateways and nameservers).
229.PP
230Fine-tuning needs to be done by editing \f(CW\*(C`src/vpn_dns.C\*(C'\fR directly.
231.SH "PART 2: The GNU VPE protocol"
232.IX Header "PART 2: The GNU VPE protocol"
233This section, unfortunately, is not yet finished, although the protocol
234is stable (until bugs in the cryptography are found, which will likely
235completely change the following description). Nevertheless, it should give
236you some overview over the protocol.
237.SS "Anatomy of a \s-1VPN\s0 packet"
238.IX Subsection "Anatomy of a VPN packet"
239The 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
241transport protocols, be it \s-1RAWIP\s0 or \s-1TCP\s0.
242.PP
243.Vb 3
244\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+
245\& | HMAC | TYPE | SRCDST | DATA |
246\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+
247.Ve
248.PP
249The \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
251itself is calculated over the \s-1TYPE\s0, \s-1SRCDST\s0 and \s-1DATA\s0 fields in all cases.
252.PP
253The \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,
255\&\s-1CONNECT\s0 \s-1REQUEST/INFO\s0 etc.).
256.PP
257\&\s-1SRCDST\s0 is a three byte field which contains the source and destination
258node IDs (12 bits each).
259.PP
260The \s-1DATA\s0 portion differs between each packet type, naturally, and is the
261only part that can be encrypted. Data packets contain more fields, as
262shown:
263.PP
264.Vb 3
265\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-+
266\& | HMAC | TYPE | SRCDST | RAND | SEQNO | DATA |
267\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-+
268.Ve
269.PP
270\&\s-1RAND\s0 is a sequence of fully random bytes, used to increase the entropy of
271the data for encryption purposes.
272.PP
273\&\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-1VPE\s0 currently uses
275a sliding window of 512 packets/sequence numbers to detect reordering,
276duplication and replay attacks.
277.PP
278The 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,
280unless \s-1RAND\s0 size is decreased or increased over the default value).
281.SS "The authentication protocol"
282.IX Subsection "The authentication protocol"
283Before nodes can exchange packets, they need to establish authenticity of
284the other side and a key. Every node has a private \s-1RSA\s0 key and the public
285\&\s-1RSA\s0 keys of all other nodes.
286.PP
287A host establishes a simplex connection by sending the other node an \s-1RSA\s0
288encrypted challenge containing a random challenge (consisting of the
289encryption and authentication keys to use when sending packets, more
290random data and \s-1PKCS1_OAEP\s0 padding) and a random 16 byte \*(L"challenge-id\*(R"
291(used to detect duplicate auth packets). The destination node will respond
292by replying with an (unencrypted) hash of the decrypted challenge, which
293will authenticate that node. The destination node will also set the
294outgoing encryption parameters as given in the packet.
295.PP
296When the source node receives a correct auth reply (by verifying the
297hash and the id, which will expire after 120 seconds), it will start to
298accept data packets from the destination node.
299.PP
300This means that a node can only initiate a simplex connection, telling the
301other side the key it has to use when it sends packets. The challenge
302reply is only used to set the current \s-1IP\s0 address of the other side and
303protocol parameters.
304.PP
305This protocol is completely symmetric, so to be able to send packets the
306destination node must send a challenge in the exact same way as already
307described (so, in essence, two simplex connections are created per node
308pair).
309.SS "Retrying"
310.IX Subsection "Retrying"
311When there is no response to an auth request, the node will send auth
312requests in bursts with an exponential back-off. After some time it will
313resort to \s-1PING\s0 packets, which are very small (8 bytes + protocol header)
314and lightweight (no \s-1RSA\s0 operations required). A node that receives ping
315requests from an unconnected peer will respond by trying to create a
316connection.
317.PP
318In addition to the exponential back-off, there is a global rate-limit on
319a per-IP base. It allows long bursts but will limit total packet rate to
320something like one control packet every ten seconds, to avoid accidental
321floods due to protocol problems (like a \s-1RSA\s0 key file mismatch between two
322nodes).
323.PP
324The intervals between retries are limited by the \f(CW\*(C`max\-retry\*(C'\fR
325configuration value. A node with \f(CW\*(C`connect\*(C'\fR = \f(CW\*(C`always\*(C'\fR will always retry,
326a node with \f(CW\*(C`connect\*(C'\fR = \f(CW\*(C`ondemand\*(C'\fR will only try (and re-try) to connect
327as long as there are packets in the queue, usually this limits the retry
328period to \f(CW\*(C`max\-ttl\*(C'\fR seconds.
329.PP
330Sending packets over the \s-1VPN\s0 will reset the retry intervals as well, which
331means as long as somebody is trying to send packets to a given node, \s-1GVPE\s0
332will try to connect every few seconds.
333.SS "Routing and Protocol translation"
334.IX Subsection "Routing and Protocol translation"
335The \s-1GVPE\s0 routing algorithm is easy: there isn't much routing to speak
336of: When routing packets to another node, \s-1GVPE\s0 tries the following
337options, in order:
338.IP "If the two nodes should be able to reach each other directly (common protocol, port known), then \s-1GVPE\s0 will send the packet directly to the other node." 4
339.IX Item "If the two nodes should be able to reach each other directly (common protocol, port known), then GVPE will send the packet directly to the other node."
340.PD 0
341.ie n .IP "If this isn't possible (e.g. because the node doesn't have a \*(C`hostname\*(C' or known port), but the nodes speak a common protocol and a router is available, then \s-1GVPE\s0 will ask a router to ""mediate"" between both nodes (see below)." 4
342.el .IP "If this isn't possible (e.g. because the node doesn't have a \f(CW\*(C`hostname\*(C'\fR or known port), but the nodes speak a common protocol and a router is available, then \s-1GVPE\s0 will ask a router to ``mediate'' between both nodes (see below)." 4
343.IX Item "If this isn't possible (e.g. because the node doesn't have a hostname or known port), but the nodes speak a common protocol and a router is available, then GVPE will ask a router to mediate between both nodes (see below)."
344.ie n .IP "If a direct connection isn't possible (no common protocols) or forbidden (\*(C`deny\-direct\*(C') and there are any routers, then \s-1GVPE\s0 will try to send packets to the router with the highest priority that is connected already \fIand\fR is able (as specified by the config file) to connect directly to the target node." 4
345.el .IP "If a direct connection isn't possible (no common protocols) or forbidden (\f(CW\*(C`deny\-direct\*(C'\fR) and there are any routers, then \s-1GVPE\s0 will try to send packets to the router with the highest priority that is connected already \fIand\fR is able (as specified by the config file) to connect directly to the target node." 4
346.IX Item "If a direct connection isn't possible (no common protocols) or forbidden (deny-direct) and there are any routers, then GVPE will try to send packets to the router with the highest priority that is connected already and is able (as specified by the config file) to connect directly to the target node."
347.IP "If no such router exists, then \s-1GVPE\s0 will simply send the packet to the node with the highest priority available." 4
348.IX Item "If no such router exists, then GVPE will simply send the packet to the node with the highest priority available."
349.IP "Failing all that, the packet will be dropped." 4
350.IX Item "Failing all that, the packet will be dropped."
351.PD
352.PP
353A host can usually declare itself unreachable directly by setting it's
354port number(s) to zero. It can declare other hosts as unreachable by using
355a config-file that disables all protocols for these other hosts. Another
356option is to disable all protocols on that host in the other config files.
357.PP
358If two hosts cannot connect to each other because their \s-1IP\s0 address(es)
359are not known (such as dial-up hosts), one side will send a \fImediated\fR
360connection request to a router (routers must be configured to act as
361routers!), which will send both the originating and the destination host
362a connection info request with protocol information and \s-1IP\s0 address of the
363other host (if known). Both hosts will then try to establish a direct
364connection to the other peer, which is usually possible even when both
365hosts are behind a \s-1NAT\s0 gateway.
366.PP
367Routing via other nodes works because the \s-1SRCDST\s0 field is not encrypted,
368so the router can just forward the packet to the destination host. Since
369each host uses it's own private key, the router will not be able to
370decrypt or encrypt packets, it will just act as a simple router and
371protocol translator.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines