| 1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
| 2 | .\" |
2 | .\" |
| 3 | .\" Standard preamble: |
3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
4 | .\" ======================================================================== |
| 5 | .de Sh \" Subsection heading |
5 | .de Sh \" Subsection heading |
| 6 | .br |
6 | .br |
| … | |
… | |
| 23 | .ft R |
23 | .ft R |
| 24 | .fi |
24 | .fi |
| 25 | .. |
25 | .. |
| 26 | .\" Set up some character translations and predefined strings. \*(-- will |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
| 27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
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 |
28 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
| 29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
29 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
| 30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
30 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
| 31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
31 | .\" nothing in troff, for use with C<>. |
| 32 | .tr \(*W-|\(bv\*(Tr |
32 | .tr \(*W- |
| 33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 34 | .ie n \{\ |
34 | .ie n \{\ |
| 35 | . ds -- \(*W- |
35 | . ds -- \(*W- |
| 36 | . ds PI pi |
36 | . ds PI pi |
| 37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| … | |
… | |
| 127 | .\} |
127 | .\} |
| 128 | .rm #[ #] #H #V #F C |
128 | .rm #[ #] #H #V #F C |
| 129 | .\" ======================================================================== |
129 | .\" ======================================================================== |
| 130 | .\" |
130 | .\" |
| 131 | .IX Title "GVPE.PROTOCOL 7" |
131 | .IX Title "GVPE.PROTOCOL 7" |
| 132 | .TH GVPE.PROTOCOL 7 "2005-04-21" "1.9" "GNU Virtual Private Ethernet" |
132 | .TH GVPE.PROTOCOL 7 "2008-08-10" "2.2" "GNU Virtual Private Ethernet" |
| 133 | .SH "The GNU-VPE Protocols" |
133 | .SH "The GNU-VPE Protocols" |
| 134 | .IX Header "The GNU-VPE Protocols" |
134 | .IX Header "The GNU-VPE Protocols" |
| 135 | .SH "Overview" |
135 | .SH "Overview" |
| 136 | .IX Header "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 |
137 | \&\s-1GVPE\s0 can make use of a number of protocols. One of them is the \s-1GNU\s0 \s-1VPE\s0 |
| … | |
… | |
| 141 | .PP |
141 | .PP |
| 142 | The first part of this document describes the transport protocols which |
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. |
143 | are used by \s-1GVPE\s0 to send it's data packets over the network. |
| 144 | .SH "PART 1: Transport protocols" |
144 | .SH "PART 1: Transport protocols" |
| 145 | .IX Header "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 |
146 | \&\s-1GVPE\s0 offers a wide range of transport protocols that can be used to |
| 147 | data between nodes. Protocols differ in their overhead, speed, |
147 | interchange data between nodes. Protocols differ in their overhead, speed, |
| 148 | reliability, and robustness. |
148 | reliability, and robustness. |
| 149 | .PP |
149 | .PP |
| 150 | The following sections describe each transport protocol in more |
150 | The following sections describe each transport protocol in more |
| 151 | detail. They are sorted by overhead/efficiency, the most efficient |
151 | detail. They are sorted by overhead/efficiency, the most efficient |
| 152 | transport is listed first: |
152 | transport is listed first: |
| … | |
… | |
| 162 | protocols, so this transport only works if you have full \s-1IP\s0 connectivity |
162 | protocols, so this transport only works if you have full \s-1IP\s0 connectivity |
| 163 | between nodes. |
163 | between nodes. |
| 164 | .Sh "\s-1ICMP\s0" |
164 | .Sh "\s-1ICMP\s0" |
| 165 | .IX Subsection "ICMP" |
165 | .IX Subsection "ICMP" |
| 166 | This protocol offers very low overhead (minimum 42 bytes), and can |
166 | This protocol offers very low overhead (minimum 42 bytes), and can |
| 167 | sometimes tunnel through firewalls when other protocols cannot. |
167 | sometimes tunnel through firewalls when other protocols can not. |
| 168 | .PP |
168 | .PP |
| 169 | It works by prepending a \s-1ICMP\s0 header with type \f(CW\*(C`icmp\-type\*(C'\fR and a code |
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 |
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 |
171 | packets look like echo replies, which looks rather strange to network |
| 172 | admins. |
172 | admins. |
| 173 | .PP |
173 | .PP |
| 174 | This transport should only be used if other transports (i.e. raw ip) are |
174 | This transport should only be used if other transports (i.e. raw ip) are |
| … | |
… | |
| 195 | most proxies do not allow connections to other ports. |
195 | most proxies do not allow connections to other ports. |
| 196 | .PP |
196 | .PP |
| 197 | It is an abuse of the usage a proxy was designed for, so make sure you are |
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. |
198 | allowed to use it for \s-1GVPE\s0. |
| 199 | .PP |
199 | .PP |
| 200 | This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is set |
200 | This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is |
| 201 | to zero, other nodes cannot connect to this node directly (and \f(CW\*(C`tcp\-port\*(C'\fR |
201 | set to zero, other nodes cannot connect to this node directly. If the |
| 202 | zero cannot be used). If the \f(CW\*(C`tcp\-port\*(C'\fR is non\-zero, the node can act |
202 | \&\f(CW\*(C`tcp\-port\*(C'\fR is non\-zero, the node can act both as a client as well as a |
| 203 | both as a client as well as a server. |
203 | server. |
| 204 | .Sh "\s-1DNS\s0" |
204 | .Sh "\s-1DNS\s0" |
| 205 | .IX Subsection "DNS" |
205 | .IX Subsection "DNS" |
| 206 | \&\fB\s-1WARNING:\s0\fR Parsing and generating \s-1DNS\s0 packets is rather tricky. The code |
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, |
207 | almost certainly contains buffer overflows and other, likely exploitable, |
| 208 | bugs. You have been warned. |
208 | bugs. You have been warned. |
| … | |
… | |
| 215 | traffic even if it doesn't need to transport packets. |
215 | traffic even if it doesn't need to transport packets. |
| 216 | .PP |
216 | .PP |
| 217 | In addition, the same problems as the \s-1TCP\s0 transport also plague this |
217 | In addition, the same problems as the \s-1TCP\s0 transport also plague this |
| 218 | protocol. |
218 | protocol. |
| 219 | .PP |
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 |
220 | 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 |
221 | 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 |
222 | 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, |
223 | 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 |
224 | and an \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). |
225 | \&\f(CW\*(C`dns\-hostname\*(C'\fR directive). |
| 228 | .PP |
226 | .PP |
| 229 | The only good side of this protocol is that it can tunnel through most |
227 | 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 |
228 | firewalls mostly undetected, iff the local \s-1DNS\s0 server/forwarder is sane |
| 231 | true for most routers, wlan gateways and nameservers). |
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" |
232 | .SH "PART 2: The GNU VPE protocol" |
| 233 | .IX Header "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 |
234 | This section, unfortunately, is not yet finished, although the protocol |
| 235 | is stable (until bugs in the cryptography are found, which will likely |
235 | is stable (until bugs in the cryptography are found, which will likely |
| 236 | completely change the following description). Nevertheless, it should give |
236 | completely change the following description). Nevertheless, it should give |
| … | |
… | |
| 240 | The exact layout and field lengths of a \s-1VPN\s0 packet is determined at |
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 |
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. |
242 | transort protocols, be it \s-1RAWIP\s0 or \s-1TCP\s0. |
| 243 | .PP |
243 | .PP |
| 244 | .Vb 3 |
244 | .Vb 3 |
| 245 | \& +------+------+--------+------+ |
245 | \& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+ |
| 246 | \& | HMAC | TYPE | SRCDST | DATA | |
246 | \& | HMAC | TYPE | SRCDST | DATA | |
| 247 | \& +------+------+--------+------+ |
247 | \& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+ |
| 248 | .Ve |
248 | .Ve |
| 249 | .PP |
249 | .PP |
| 250 | The \s-1HMAC\s0 field is present in all packets, even if not used (e.g. in auth |
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 |
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. |
252 | itself is calculated over the \s-1TYPE\s0, \s-1SRCDST\s0 and \s-1DATA\s0 fields in all cases. |
| … | |
… | |
| 254 | The \s-1TYPE\s0 field is a single byte and determines the purpose of the packet |
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, |
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.). |
256 | \&\s-1CONNECT\s0 \s-1REQUEST/INFO\s0 etc.). |
| 257 | .PP |
257 | .PP |
| 258 | \&\s-1SRCDST\s0 is a three byte field which contains the source and destination |
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+ |
259 | node IDs (12 bits each). |
| 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 |
260 | .PP |
| 264 | The \s-1DATA\s0 portion differs between each packet type, naturally, and is the |
261 | 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 |
262 | only part that can be encrypted. Data packets contain more fields, as |
| 266 | shown: |
263 | shown: |
| 267 | .PP |
264 | .PP |
| 268 | .Vb 3 |
265 | .Vb 3 |
| 269 | \& +------+------+--------+------+-------+------+ |
266 | \& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-+ |
| 270 | \& | HMAC | TYPE | SRCDST | RAND | SEQNO | DATA | |
267 | \& | HMAC | TYPE | SRCDST | RAND | SEQNO | DATA | |
| 271 | \& +------+------+--------+------+-------+------+ |
268 | \& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-+ |
| 272 | .Ve |
269 | .Ve |
| 273 | .PP |
270 | .PP |
| 274 | \&\s-1RAND\s0 is a sequence of fully random bytes, used to increase the entropy of |
271 | \&\s-1RAND\s0 is a sequence of fully random bytes, used to increase the entropy of |
| 275 | the data for encryption purposes. |
272 | the data for encryption purposes. |
| 276 | .PP |
273 | .PP |
| 277 | \&\s-1SEQNO\s0 is a 32\-bit sequence number. It is negotiated at every connection |
274 | \&\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 |
275 | 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, |
276 | a sliding window of 512 packets/sequence numbers to detect reordering, |
| 280 | duplication and reply attacks. |
277 | duplication and replay attacks. |
| 281 | .Sh "The authentification protocol" |
278 | .Sh "The authentication protocol" |
| 282 | .IX Subsection "The authentification protocol" |
279 | .IX Subsection "The authentication protocol" |
| 283 | Before hosts can exchange packets, they need to establish authenticity of |
280 | 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 |
281 | 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. |
282 | \&\s-1RSA\s0 keys of all other hosts. |
| 286 | .PP |
283 | .PP |
| 287 | A host establishes a simplex connection by sending the other host a |
284 | A host establishes a simplex connection by sending the other host an |
| 288 | \&\s-1RSA\s0 encrypted challenge containing a random challenge (consisting of |
285 | \&\s-1RSA\s0 encrypted challenge containing a random challenge (consisting of |
| 289 | the encryption key to use when sending packets, more random data and |
286 | 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 |
287 | \&\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 |
288 | duplicate auth packets). The destination host will respond by replying |
| 292 | with an (unencrypted) \s-1RIPEMD160\s0 hash of the decrypted challenge, which |
289 | 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 |
290 | will authenticate that host. The destination host will also set the |
| 294 | encryption parameters as given in the packet. |
291 | outgoing encryption parameters as given in the packet. |
| 295 | .PP |
292 | .PP |
| 296 | When the source host receives a correct auth reply (by verifying the |
293 | 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 |
294 | hash and the id, which will expire after 120 seconds), it will start to |
| 298 | accept data packets from the destination host. |
295 | accept data packets from the destination host. |
| 299 | .PP |
296 | .PP |
