1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
|
|
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. | will give a |
|
|
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
|
|
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
|
|
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
|
|
32 | .tr \(*W-|\(bv\*(Tr |
|
|
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 "2005-04-21" "1.9" "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 range of transport protocols that can be used to interchange |
|
|
147 | 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 cannot. |
|
|
168 | .PP |
|
|
169 | It works by prepending a \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 set |
|
|
201 | to zero, other nodes cannot connect to this node directly (and \f(CW\*(C`tcp\-port\*(C'\fR |
|
|
202 | zero cannot be used). If the \f(CW\*(C`tcp\-port\*(C'\fR is non\-zero, the node can act |
|
|
203 | both as a client as well as a 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 | Most configuration needs to be done by editing \f(CW\*(C`src/vpn_dns.C\*(C'\fR directly. |
|
|
221 | .PP |
|
|
222 | It's only use is to tunnel through firewalls that do not allow direct |
|
|
223 | internet access. Similar to using a \s-1HTTP\s0 proxy (as the \s-1TCP\s0 transport |
|
|
224 | does), it uses a local \s-1DNS\s0 server/forwarder (given by the \f(CW\*(C`dns\-forw\-host\*(C'\fR |
|
|
225 | configuration value) as a proxy to send and receive data as a client, |
|
|
226 | and a \f(CW\*(C`NS\*(C'\fR record pointing to the \s-1GVPE\s0 server (as given by the |
|
|
227 | \&\f(CW\*(C`dns\-hostname\*(C'\fR directive). |
|
|
228 | .PP |
|
|
229 | The only good side of this protocol is that it can tunnel through most |
|
|
230 | firewalls undetected, iff the local \s-1DNS\s0 server/forwarder is sane (which is |
|
|
231 | true for most routers, wlan gateways and nameservers). |
|
|
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). The protocol does not yet scale well beyond 30+ |
|
|
260 | hosts, since all hosts must connect to each other once on startup. But if |
|
|
261 | restarts are rare or tolerable and most connections are on demand, much |
|
|
262 | larger networks are feasible. |
|
|
263 | .PP |
|
|
264 | The \s-1DATA\s0 portion differs between each packet type, naturally, and is the |
|
|
265 | only part that can be encrypted. Data packets contain more fields, as |
|
|
266 | shown: |
|
|
267 | .PP |
|
|
268 | .Vb 3 |
|
|
269 | \& +------+------+--------+------+-------+------+ |
|
|
270 | \& | HMAC | TYPE | SRCDST | RAND | SEQNO | DATA | |
|
|
271 | \& +------+------+--------+------+-------+------+ |
|
|
272 | .Ve |
|
|
273 | .PP |
|
|
274 | \&\s-1RAND\s0 is a sequence of fully random bytes, used to increase the entropy of |
|
|
275 | the data for encryption purposes. |
|
|
276 | .PP |
|
|
277 | \&\s-1SEQNO\s0 is a 32\-bit sequence number. It is negotiated at every connection |
|
|
278 | initialization and starts at some random 31 bit value. \s-1VPE\s0 currently uses |
|
|
279 | a sliding window of 512 packets/sequence numbers to detect reordering, |
|
|
280 | duplication and reply attacks. |
|
|
281 | .Sh "The authentification protocol" |
|
|
282 | .IX Subsection "The authentification protocol" |
|
|
283 | Before hosts can exchange packets, they need to establish authenticity of |
|
|
284 | the other side and a key. Every host has a private \s-1RSA\s0 key and the public |
|
|
285 | \&\s-1RSA\s0 keys of all other hosts. |
|
|
286 | .PP |
|
|
287 | A host establishes a simplex connection by sending the other host a |
|
|
288 | \&\s-1RSA\s0 encrypted challenge containing a random challenge (consisting of |
|
|
289 | the encryption key to use when sending packets, more random data and |
|
|
290 | \&\s-1PKCS1_OAEP\s0 padding) and a random 16 byte \*(L"challenge\-id\*(R" (used to detect |
|
|
291 | duplicate auth packets). The destination host will respond by replying |
|
|
292 | with an (unencrypted) \s-1RIPEMD160\s0 hash of the decrypted challenge, which |
|
|
293 | will authentify that host. The destination host will also set the outgoing |
|
|
294 | encryption parameters as given in the packet. |
|
|
295 | .PP |
|
|
296 | When the source host receives a correct auth reply (by verifying the |
|
|
297 | hash and the id, which will expire after 120 seconds), it will start to |
|
|
298 | accept data packets from the destination host. |
|
|
299 | .PP |
|
|
300 | This means that a host can only initate a simplex connection, telling the |
|
|
301 | other side the key it has to use when it sends packets. The challenge |
|
|
302 | reply is only used to set the current \s-1IP\s0 address of the other side and |
|
|
303 | protocol parameters. |
|
|
304 | .PP |
|
|
305 | This protocol is completely symmetric, so to be able to send packets the |
|
|
306 | destination host must send a challenge in the exact same way as already |
|
|
307 | described (so, in essence, two simplex connections are created per host |
|
|
308 | pair). |
|
|
309 | .Sh "Retrying" |
|
|
310 | .IX Subsection "Retrying" |
|
|
311 | When there is no response to an auth request, the host will send auth |
|
|
312 | requests in bursts with an exponential backoff. After some time it will |
|
|
313 | resort to \s-1PING\s0 packets, which are very small (8 bytes) and lightweight |
|
|
314 | (no \s-1RSA\s0 operations required). A host that receives ping requests from an |
|
|
315 | unconnected peer will respond by trying to create a connection. |
|
|
316 | .PP |
|
|
317 | In addition to the exponential backoff, there is a global rate-limit on |
|
|
318 | a per-IP base. It allows long bursts but will limit total packet rate to |
|
|
319 | something like one control packet every ten seconds, to avoid accidental |
|
|
320 | floods due to protocol problems (like a \s-1RSA\s0 key file mismatch between two |
|
|
321 | hosts). |
|
|
322 | .Sh "Routing and Protocol translation" |
|
|
323 | .IX Subsection "Routing and Protocol translation" |
|
|
324 | The gvpe routing algorithm is easy: there isn't any routing. \s-1GVPE\s0 always |
|
|
325 | tries to establish direct connections, if the protocol abilities of the |
|
|
326 | two hosts allow it. |
|
|
327 | .PP |
|
|
328 | If the two hosts should be able to reach each other (common protocol, ip |
|
|
329 | and port all known), but cannot (network down), then there will be no |
|
|
330 | connection, point. |
|
|
331 | .PP |
|
|
332 | A host can usually declare itself unreachable directly by setting it's |
|
|
333 | port number(s) to zero. It can declare other hosts as unreachable by using |
|
|
334 | a config-file that disables all protocols for these other hosts. |
|
|
335 | .PP |
|
|
336 | If two hosts cannot connect to each other because their \s-1IP\s0 address(es) |
|
|
337 | are not known (such as dialup hosts), one side will send a connection |
|
|
338 | request to a router (routers must be configured to act as routers!), which |
|
|
339 | will send both the originating and the destination host a connection info |
|
|
340 | request with protocol information and \s-1IP\s0 address of the other host (if |
|
|
341 | known). Both hosts will then try to establish a connection to the other |
|
|
342 | peer, which is usually possible even when both hosts are behind a \s-1NAT\s0 |
|
|
343 | gateway. |
|
|
344 | .PP |
|
|
345 | If the hosts cannot reach each other because they have no common protocol, |
|
|
346 | the originator instead use the router with highest priority and matching |
|
|
347 | protocol as peer. Since the \s-1SRCDST\s0 field is not encrypted, the router host |
|
|
348 | can just forward the packet to the destination host. Since each host uses |
|
|
349 | it's own private key, the router will not be able to decrypt or encrypt |
|
|
350 | packets, it will just act as a simple router and protocol translator. |
|
|
351 | .PP |
|
|
352 | When no router is connected, the host will aggressively try to connect to |
|
|
353 | all routers, and if a router is asked for an unconnected host it will try |
|
|
354 | to ask another router to establish the connection. |
|
|
355 | .PP |
|
|
356 | \&... more not yet written about the details of the routing, please bug me |
|
|
357 | \&... |
|
|