ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.protocol.7
Revision: 1.6
Committed: Sat Mar 26 03:16:23 2005 UTC (19 years, 2 months ago) by pcg
Branch: MAIN
CVS Tags: rel-1_9
Changes since 1.5: +1 -1 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 pcg 1.1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
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 pcg 1.6 .TH GVPE.PROTOCOL 7 "2005-03-26" "1.9" "GNU Virtual Private Ethernet"
133 pcg 1.2 .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: Tansport protocols"
145     .IX Header "PART 1: Tansport protocols"
146 pcg 1.3 \&\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 pcg 1.4 transport is listed first:
153 pcg 1.2 .Sh "\s-1RAW\s0 \s-1IP\s0"
154     .IX Subsection "RAW IP"
155 pcg 1.3 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 pcg 1.2 .Sh "\s-1ICMP\s0"
165     .IX Subsection "ICMP"
166 pcg 1.3 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 pcg 1.2 .Sh "\s-1UDP\s0"
177     .IX Subsection "UDP"
178 pcg 1.3 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 pcg 1.2 .Sh "\s-1TCP\s0"
184     .IX Subsection "TCP"
185 pcg 1.3 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 pcg 1.2 .Sh "\s-1DNS\s0"
205     .IX Subsection "DNS"
206 pcg 1.3 \&\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 pcg 1.2 .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 pcg 1.1 .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 pcg 1.2 transort protocols, be it \s-1RAWIP\s0 or \s-1TCP\s0.
243 pcg 1.1 .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 pcg 1.2 itself is calculated over the \s-1TYPE\s0, \s-1SRCDST\s0 and \s-1DATA\s0 fields in all cases.
253 pcg 1.1 .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 pcg 1.2 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 pcg 1.1 .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 pcg 1.2 a sliding window of 512 packets/sequence numbers to detect reordering,
280     duplication and reply attacks.
281 pcg 1.1 .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 pcg 1.2 reply is only used to set the current \s-1IP\s0 address of the other side and
303     protocol parameters.
304 pcg 1.1 .PP
305 pcg 1.2 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 pcg 1.1 .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 pcg 1.2 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 pcg 1.1 .PP
317     In addition to the exponential backoff, there is a global rate-limit on
318 pcg 1.2 a per-IP base. It allows long bursts but will limit total packet rate to
319 pcg 1.1 something like one control packet every ten seconds, to avoid accidental
320 pcg 1.2 floods due to protocol problems (like a \s-1RSA\s0 key file mismatch between two
321 pcg 1.1 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     \&...