ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.protocol.7
Revision: 1.9
Committed: Mon Aug 11 16:02:16 2008 UTC (15 years, 9 months ago) by pcg
Branch: MAIN
CVS Tags: rel-2_2
Changes since 1.8: +46 -32 lines
Log Message:
*** empty log message ***

File Contents

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