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.7 by pcg, Fri Jun 3 05:07:31 2005 UTC vs.
Revision 1.11 by root, Sun Mar 6 19:40:27 2011 UTC

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
138protocol which is used to authenticate tunnels and send encrypted data
139packets. This protocol is described in more detail the second part of this
140document.
141.PP
142The first part of this document describes the transport protocols which
143are 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
147data between nodes. Protocols differ in their overhead, speed,
148reliability, and robustness.
149.PP
150The following sections describe each transport protocol in more
151detail. They are sorted by overhead/efficiency, the most efficient
152transport is listed first:
153.Sh "\s-1RAW\s0 \s-1IP\s0"
154.IX Subsection "RAW IP"
155This protocol is the best choice, performance\-wise, as the minimum
156overhead per packet is only 38 bytes.
157.PP
158It works by sending the \s-1VPN\s0 payload using raw ip frames (using the
159protocol set by \f(CW\*(C`ip\-proto\*(C'\fR).
160.PP
161Using raw ip frames has the drawback that many firewalls block \*(L"unknown\*(R"
162protocols, so this transport only works if you have full \s-1IP\s0 connectivity
163between nodes.
164.Sh "\s-1ICMP\s0"
165.IX Subsection "ICMP"
166This protocol offers very low overhead (minimum 42 bytes), and can
167sometimes tunnel through firewalls when other protocols cannot.
168.PP
169It works by prepending a \s-1ICMP\s0 header with type \f(CW\*(C`icmp\-type\*(C'\fR and a code
170of \f(CW255\fR. The default \f(CW\*(C`icmp\-type\*(C'\fR is \f(CW\*(C`echo\-reply\*(C'\fR, so the resulting
171packets look like echo replies, which looks rather strange to network
172admins.
173.PP
174This transport should only be used if other transports (i.e. raw ip) are
175not available or undesirable (due to their overhead).
176.Sh "\s-1UDP\s0"
177.IX Subsection "UDP"
178This is a good general choice for the transport protocol as \s-1UDP\s0 packets
179tunnel well through most firewalls and routers, and the overhead per
180packet is moderate (minimum 58 bytes).
181.PP
182It should be used if \s-1RAW\s0 \s-1IP\s0 is not available.
183.Sh "\s-1TCP\s0"
184.IX Subsection "TCP"
185This protocol is a very bad choice, as it not only has high overhead (more
186than 60 bytes), but the transport also retries on it's own, which leads
187to congestion when the link has moderate packet loss (as both the \s-1TCP\s0
188transport and the tunneled traffic will retry, increasing congestion more
189and more). It also has high latency and is quite inefficient.
190.PP
191It's only useful when tunneling through firewalls that block better
192protocols. If a node doesn't have direct internet access but a \s-1HTTP\s0 proxy
193that supports the \s-1CONNECT\s0 method it can be used to tunnel through a web
194proxy. For this to work, the \f(CW\*(C`tcp\-port\*(C'\fR should be \f(CW443\fR (\f(CW\*(C`https\*(C'\fR), as
195most proxies do not allow connections to other ports.
196.PP
197It is an abuse of the usage a proxy was designed for, so make sure you are
198allowed to use it for \s-1GVPE\s0.
199.PP
200This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is set
201to zero, other nodes cannot connect to this node directly (and \f(CW\*(C`tcp\-port\*(C'\fR
202zero cannot be used). If the \f(CW\*(C`tcp\-port\*(C'\fR is non\-zero, the node can act
203both 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
207almost certainly contains buffer overflows and other, likely exploitable,
208bugs. You have been warned.
209.PP
210This 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
213handle the traffic and drop or corrupt packets. The client also has to
214constantly poll the server for data, so the client will constantly create
215traffic even if it doesn't need to transport packets.
216.PP
217In addition, the same problems as the \s-1TCP\s0 transport also plague this
218protocol.
219.PP
220Most configuration needs to be done by editing \f(CW\*(C`src/vpn_dns.C\*(C'\fR directly.
221.PP
222It's only use is to tunnel through firewalls that do not allow direct
223internet access. Similar to using a \s-1HTTP\s0 proxy (as the \s-1TCP\s0 transport
224does), it uses a local \s-1DNS\s0 server/forwarder (given by the \f(CW\*(C`dns\-forw\-host\*(C'\fR
225configuration value) as a proxy to send and receive data as a client,
226and 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
229The only good side of this protocol is that it can tunnel through most
230firewalls undetected, iff the local \s-1DNS\s0 server/forwarder is sane (which is
231true for most routers, wlan gateways and nameservers).
232.SH "PART 2: The GNU VPE protocol"
233.IX Header "PART 2: The GNU VPE protocol"
234This section, unfortunately, is not yet finished, although the protocol
235is stable (until bugs in the cryptography are found, which will likely
236completely change the following description). Nevertheless, it should give
237you some overview over the protocol.
238.Sh "Anatomy of a \s-1VPN\s0 packet"
239.IX Subsection "Anatomy of a VPN packet"
240The exact layout and field lengths of a \s-1VPN\s0 packet is determined at
241compiletime and doesn't change. The same structure is used for all
242transort 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
250The \s-1HMAC\s0 field is present in all packets, even if not used (e.g. in auth
251request packets), in which case it is set to all zeroes. The checksum
252itself is calculated over the \s-1TYPE\s0, \s-1SRCDST\s0 and \s-1DATA\s0 fields in all cases.
253.PP
254The \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
259node ids (12 bits each). The protocol does not yet scale well beyond 30+
260hosts, since all hosts must connect to each other once on startup. But if
261restarts are rare or tolerable and most connections are on demand, much
262larger networks are feasible.
263.PP
264The \s-1DATA\s0 portion differs between each packet type, naturally, and is the
265only part that can be encrypted. Data packets contain more fields, as
266shown:
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
275the data for encryption purposes.
276.PP
277\&\s-1SEQNO\s0 is a 32\-bit sequence number. It is negotiated at every connection
278initialization and starts at some random 31 bit value. \s-1VPE\s0 currently uses
279a sliding window of 512 packets/sequence numbers to detect reordering,
280duplication and reply attacks.
281.Sh "The authentification protocol"
282.IX Subsection "The authentification protocol"
283Before hosts can exchange packets, they need to establish authenticity of
284the 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
287A host establishes a simplex connection by sending the other host a
288\&\s-1RSA\s0 encrypted challenge containing a random challenge (consisting of
289the 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
291duplicate auth packets). The destination host will respond by replying
292with an (unencrypted) \s-1RIPEMD160\s0 hash of the decrypted challenge, which
293will authentify that host. The destination host will also set the outgoing
294encryption parameters as given in the packet.
295.PP
296When the source host 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 host.
299.PP
300This means that a host can only initate 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 host must send a challenge in the exact same way as already
307described (so, in essence, two simplex connections are created per host
308pair).
309.Sh "Retrying"
310.IX Subsection "Retrying"
311When there is no response to an auth request, the host will send auth
312requests in bursts with an exponential backoff. After some time it will
313resort 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
315unconnected peer will respond by trying to create a connection.
316.PP
317In addition to the exponential backoff, there is a global rate-limit on
318a per-IP base. It allows long bursts but will limit total packet rate to
319something like one control packet every ten seconds, to avoid accidental
320floods due to protocol problems (like a \s-1RSA\s0 key file mismatch between two
321hosts).
322.Sh "Routing and Protocol translation"
323.IX Subsection "Routing and Protocol translation"
324The gvpe routing algorithm is easy: there isn't any routing. \s-1GVPE\s0 always
325tries to establish direct connections, if the protocol abilities of the
326two hosts allow it.
327.PP
328If the two hosts should be able to reach each other (common protocol, ip
329and port all known), but cannot (network down), then there will be no
330connection, point.
331.PP
332A host can usually declare itself unreachable directly by setting it's
333port number(s) to zero. It can declare other hosts as unreachable by using
334a config-file that disables all protocols for these other hosts.
335.PP
336If two hosts cannot connect to each other because their \s-1IP\s0 address(es)
337are not known (such as dialup hosts), one side will send a connection
338request to a router (routers must be configured to act as routers!), which
339will send both the originating and the destination host a connection info
340request with protocol information and \s-1IP\s0 address of the other host (if
341known). Both hosts will then try to establish a connection to the other
342peer, which is usually possible even when both hosts are behind a \s-1NAT\s0
343gateway.
344.PP
345If the hosts cannot reach each other because they have no common protocol,
346the originator instead use the router with highest priority and matching
347protocol as peer. Since the \s-1SRCDST\s0 field is not encrypted, the router host
348can just forward the packet to the destination host. Since each host uses
349it's own private key, the router will not be able to decrypt or encrypt
350packets, it will just act as a simple router and protocol translator.
351.PP
352When no router is connected, the host will aggressively try to connect to
353all routers, and if a router is asked for an unconnected host it will try
354to ask another router to establish the connection.
355.PP
356\&... more not yet written about the details of the routing, please bug me
357\&...

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines