--- gvpe/doc/gvpe.protocol.7 2005/03/17 23:59:37 1.4 +++ gvpe/doc/gvpe.protocol.7 2008/08/10 23:04:05 1.8 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== @@ -25,11 +25,11 @@ .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "GVPE.PROTOCOL 7" -.TH GVPE.PROTOCOL 7 "2005-03-17" "1.8" "GNU Virtual Private Ethernet" +.TH GVPE.PROTOCOL 7 "2008-08-10" "2.2" "GNU Virtual Private Ethernet" .SH "The GNU-VPE Protocols" .IX Header "The GNU-VPE Protocols" .SH "Overview" @@ -141,10 +141,10 @@ .PP The first part of this document describes the transport protocols which are used by \s-1GVPE\s0 to send it's data packets over the network. -.SH "PART 1: Tansport protocols" -.IX Header "PART 1: Tansport protocols" -\&\s-1GVPE\s0 offers a range of transport protocols that can be used to interchange -data between nodes. Protocols differ in their overhead, speed, +.SH "PART 1: Transport protocols" +.IX Header "PART 1: Transport protocols" +\&\s-1GVPE\s0 offers a wide range of transport protocols that can be used to +interchange data between nodes. Protocols differ in their overhead, speed, reliability, and robustness. .PP The following sections describe each transport protocol in more @@ -164,9 +164,9 @@ .Sh "\s-1ICMP\s0" .IX Subsection "ICMP" This protocol offers very low overhead (minimum 42 bytes), and can -sometimes tunnel through firewalls when other protocols cannot. +sometimes tunnel through firewalls when other protocols can not. .PP -It works by prepending a \s-1ICMP\s0 header with type \f(CW\*(C`icmp\-type\*(C'\fR and a code +It works by prepending an \s-1ICMP\s0 header with type \f(CW\*(C`icmp\-type\*(C'\fR and a code of \f(CW255\fR. The default \f(CW\*(C`icmp\-type\*(C'\fR is \f(CW\*(C`echo\-reply\*(C'\fR, so the resulting packets look like echo replies, which looks rather strange to network admins. @@ -197,10 +197,10 @@ It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for \s-1GVPE\s0. .PP -This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is set -to zero, other nodes cannot connect to this node directly (and \f(CW\*(C`tcp\-port\*(C'\fR -zero cannot be used). If the \f(CW\*(C`tcp\-port\*(C'\fR is non\-zero, the node can act -both as a client as well as a server. +This protocol also has server and client sides. If the \f(CW\*(C`tcp\-port\*(C'\fR is +set to zero, other nodes cannot connect to this node directly. If the +\&\f(CW\*(C`tcp\-port\*(C'\fR is non\-zero, the node can act both as a client as well as a +server. .Sh "\s-1DNS\s0" .IX Subsection "DNS" \&\fB\s-1WARNING:\s0\fR Parsing and generating \s-1DNS\s0 packets is rather tricky. The code @@ -217,18 +217,18 @@ In addition, the same problems as the \s-1TCP\s0 transport also plague this protocol. .PP -Most configuration needs to be done by editing \f(CW\*(C`src/vpn_dns.C\*(C'\fR directly. -.PP It's only use is to tunnel through firewalls that do not allow direct internet access. Similar to using a \s-1HTTP\s0 proxy (as the \s-1TCP\s0 transport does), it uses a local \s-1DNS\s0 server/forwarder (given by the \f(CW\*(C`dns\-forw\-host\*(C'\fR configuration value) as a proxy to send and receive data as a client, -and a \f(CW\*(C`NS\*(C'\fR record pointing to the \s-1GVPE\s0 server (as given by the +and an \f(CW\*(C`NS\*(C'\fR record pointing to the \s-1GVPE\s0 server (as given by the \&\f(CW\*(C`dns\-hostname\*(C'\fR directive). .PP The only good side of this protocol is that it can tunnel through most -firewalls undetected, iff the local \s-1DNS\s0 server/forwarder is sane (which is -true for most routers, wlan gateways and nameservers). +firewalls mostly undetected, iff the local \s-1DNS\s0 server/forwarder is sane +(which is true for most routers, \s-1WLAN\s0 gateways and nameservers). +.PP +Finetuning needs to be done by editing \f(CW\*(C`src/vpn_dns.C\*(C'\fR directly. .SH "PART 2: The GNU VPE protocol" .IX Header "PART 2: The GNU VPE protocol" This section, unfortunately, is not yet finished, although the protocol @@ -242,9 +242,9 @@ transort protocols, be it \s-1RAWIP\s0 or \s-1TCP\s0. .PP .Vb 3 -\& +------+------+--------+------+ +\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+ \& | HMAC | TYPE | SRCDST | DATA | -\& +------+------+--------+------+ +\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+ .Ve .PP The \s-1HMAC\s0 field is present in all packets, even if not used (e.g. in auth @@ -256,19 +256,16 @@ \&\s-1CONNECT\s0 \s-1REQUEST/INFO\s0 etc.). .PP \&\s-1SRCDST\s0 is a three byte field which contains the source and destination -node ids (12 bits each). The protocol does not yet scale well beyond 30+ -hosts, since all hosts must connect to each other once on startup. But if -restarts are rare or tolerable and most connections are on demand, much -larger networks are feasible. +node IDs (12 bits each). .PP The \s-1DATA\s0 portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown: .PP .Vb 3 -\& +------+------+--------+------+-------+------+ +\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-+ \& | HMAC | TYPE | SRCDST | RAND | SEQNO | DATA | -\& +------+------+--------+------+-------+------+ +\& +\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-+ .Ve .PP \&\s-1RAND\s0 is a sequence of fully random bytes, used to increase the entropy of @@ -277,21 +274,21 @@ \&\s-1SEQNO\s0 is a 32\-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. \s-1VPE\s0 currently uses a sliding window of 512 packets/sequence numbers to detect reordering, -duplication and reply attacks. -.Sh "The authentification protocol" -.IX Subsection "The authentification protocol" +duplication and replay attacks. +.Sh "The authentication protocol" +.IX Subsection "The authentication protocol" Before hosts can exchange packets, they need to establish authenticity of the other side and a key. Every host has a private \s-1RSA\s0 key and the public \&\s-1RSA\s0 keys of all other hosts. .PP -A host establishes a simplex connection by sending the other host a +A host establishes a simplex connection by sending the other host an \&\s-1RSA\s0 encrypted challenge containing a random challenge (consisting of the encryption key to use when sending packets, more random data and \&\s-1PKCS1_OAEP\s0 padding) and a random 16 byte \*(L"challenge\-id\*(R" (used to detect duplicate auth packets). The destination host will respond by replying with an (unencrypted) \s-1RIPEMD160\s0 hash of the decrypted challenge, which -will authentify that host. The destination host will also set the outgoing -encryption parameters as given in the packet. +will authenticate that host. The destination host will also set the +outgoing encryption parameters as given in the packet. .PP When the source host receives a correct auth reply (by verifying the hash and the id, which will expire after 120 seconds), it will start to