--- gvpe/doc/gvpe.protocol.7	2005/06/03 05:07:31	1.7
+++ gvpe/doc/gvpe.protocol.7	2011/03/06 19:40:27	1.11
@@ -1,357 +0,0 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" 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
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-.    ds -- \(*W-
-.    ds PI pi
-.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
-.    ds L" ""
-.    ds R" ""
-.    ds C` 
-.    ds C' 
-'br\}
-.el\{\
-.    ds -- \|\(em\|
-.    ds PI \(*p
-.    ds L" ``
-.    ds R" ''
-'br\}
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
-.\" entries marked with X<> in POD.  Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.if \nF \{\
-.    de IX
-.    tm Index:\\$1\t\\n%\t"\\$2"
-..
-.    nr % 0
-.    rr F
-.\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
-.    \" fudge factors for nroff and troff
-.if n \{\
-.    ds #H 0
-.    ds #V .8m
-.    ds #F .3m
-.    ds #[ \f1
-.    ds #] \fP
-.\}
-.if t \{\
-.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-.    ds #V .6m
-.    ds #F 0
-.    ds #[ \&
-.    ds #] \&
-.\}
-.    \" simple accents for nroff and troff
-.if n \{\
-.    ds ' \&
-.    ds ` \&
-.    ds ^ \&
-.    ds , \&
-.    ds ~ ~
-.    ds /
-.\}
-.if t \{\
-.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-.    \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-.    \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-.    \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-.    ds : e
-.    ds 8 ss
-.    ds o a
-.    ds d- d\h'-1'\(ga
-.    ds D- D\h'-1'\(hy
-.    ds th \o'bp'
-.    ds Th \o'LP'
-.    ds ae ae
-.    ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "GVPE.PROTOCOL 7"
-.TH GVPE.PROTOCOL 7 "2005-04-21" "1.9" "GNU Virtual Private Ethernet"
-.SH "The GNU-VPE Protocols"
-.IX Header "The GNU-VPE Protocols"
-.SH "Overview"
-.IX Header "Overview"
-\&\s-1GVPE\s0 can make use of a number of protocols. One of them is the \s-1GNU\s0 \s-1VPE\s0
-protocol which is used to authenticate tunnels and send encrypted data
-packets. This protocol is described in more detail the second part of this
-document.
-.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: Transport protocols"
-.IX Header "PART 1: Transport 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,
-reliability, and robustness.
-.PP
-The following sections describe each transport protocol in more
-detail. They are sorted by overhead/efficiency, the most efficient
-transport is listed first:
-.Sh "\s-1RAW\s0 \s-1IP\s0"
-.IX Subsection "RAW IP"
-This protocol is the best choice, performance\-wise, as the minimum
-overhead per packet is only 38 bytes.
-.PP
-It works by sending the \s-1VPN\s0 payload using raw ip frames (using the
-protocol set by \f(CW\*(C`ip\-proto\*(C'\fR).
-.PP
-Using raw ip frames has the drawback that many firewalls block \*(L"unknown\*(R"
-protocols, so this transport only works if you have full \s-1IP\s0 connectivity
-between nodes.
-.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.
-.PP
-It works by prepending a \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.
-.PP
-This transport should only be used if other transports (i.e. raw ip) are
-not available or undesirable (due to their overhead).
-.Sh "\s-1UDP\s0"
-.IX Subsection "UDP"
-This is a good general choice for the transport protocol as \s-1UDP\s0 packets
-tunnel well through most firewalls and routers, and the overhead per
-packet is moderate (minimum 58 bytes).
-.PP
-It should be used if \s-1RAW\s0 \s-1IP\s0 is not available.
-.Sh "\s-1TCP\s0"
-.IX Subsection "TCP"
-This protocol is a very bad choice, as it not only has high overhead (more
-than 60 bytes), but the transport also retries on it's own, which leads
-to congestion when the link has moderate packet loss (as both the \s-1TCP\s0
-transport and the tunneled traffic will retry, increasing congestion more
-and more). It also has high latency and is quite inefficient.
-.PP
-It's only useful when tunneling through firewalls that block better
-protocols. If a node doesn't have direct internet access but a \s-1HTTP\s0 proxy
-that supports the \s-1CONNECT\s0 method it can be used to tunnel through a web
-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
-most proxies do not allow connections to other ports.
-.PP
-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.
-.Sh "\s-1DNS\s0"
-.IX Subsection "DNS"
-\&\fB\s-1WARNING:\s0\fR Parsing and generating \s-1DNS\s0 packets is rather tricky. The code
-almost certainly contains buffer overflows and other, likely exploitable,
-bugs. You have been warned.
-.PP
-This is the worst choice of transport protocol with respect to overhead
-(overhead can be 2\-3 times higher than the transferred data), and latency
-(which can be many seconds). Some \s-1DNS\s0 servers might not be prepared to
-handle the traffic and drop or corrupt packets. The client also has to
-constantly poll the server for data, so the client will constantly create
-traffic even if it doesn't need to transport packets.
-.PP
-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
-\&\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).
-.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
-is stable (until bugs in the cryptography are found, which will likely
-completely change the following description). Nevertheless, it should give
-you some overview over the protocol.
-.Sh "Anatomy of a \s-1VPN\s0 packet"
-.IX Subsection "Anatomy of a VPN packet"
-The exact layout and field lengths of a \s-1VPN\s0 packet is determined at
-compiletime and doesn't change. The same structure is used for all
-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
-request packets), in which case it is set to all zeroes. The checksum
-itself is calculated over the \s-1TYPE\s0, \s-1SRCDST\s0 and \s-1DATA\s0 fields in all cases.
-.PP
-The \s-1TYPE\s0 field is a single byte and determines the purpose of the packet
-(e.g. \s-1RESET\s0, \s-1COMPRESSED/UNCOMPRESSED\s0 \s-1DATA\s0, \s-1PING\s0, \s-1AUTH\s0 \s-1REQUEST/RESPONSE\s0,
-\&\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.
-.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
-the data for encryption purposes.
-.PP
-\&\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"
-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
-\&\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.
-.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
-accept data packets from the destination host.
-.PP
-This means that a host can only initate a simplex connection, telling the
-other side the key it has to use when it sends packets. The challenge
-reply is only used to set the current \s-1IP\s0 address of the other side and
-protocol parameters.
-.PP
-This protocol is completely symmetric, so to be able to send packets the
-destination host must send a challenge in the exact same way as already
-described (so, in essence, two simplex connections are created per host
-pair).
-.Sh "Retrying"
-.IX Subsection "Retrying"
-When there is no response to an auth request, the host will send auth
-requests in bursts with an exponential backoff. After some time it will
-resort to \s-1PING\s0 packets, which are very small (8 bytes) and lightweight
-(no \s-1RSA\s0 operations required). A host that receives ping requests from an
-unconnected peer will respond by trying to create a connection.
-.PP
-In addition to the exponential backoff, there is a global rate-limit on
-a per-IP base. It allows long bursts but will limit total packet rate to
-something like one control packet every ten seconds, to avoid accidental
-floods due to protocol problems (like a \s-1RSA\s0 key file mismatch between two
-hosts).
-.Sh "Routing and Protocol translation"
-.IX Subsection "Routing and Protocol translation"
-The gvpe routing algorithm is easy: there isn't any routing. \s-1GVPE\s0 always
-tries to establish direct connections, if the protocol abilities of the
-two hosts allow it.
-.PP
-If the two hosts should be able to reach each other (common protocol, ip
-and port all known), but cannot (network down), then there will be no
-connection, point.
-.PP
-A host can usually declare itself unreachable directly by setting it's
-port number(s) to zero. It can declare other hosts as unreachable by using
-a config-file that disables all protocols for these other hosts.
-.PP
-If two hosts cannot connect to each other because their \s-1IP\s0 address(es)
-are not known (such as dialup hosts), one side will send a connection
-request to a router (routers must be configured to act as routers!), which
-will send both the originating and the destination host a connection info
-request with protocol information and \s-1IP\s0 address of the other host (if
-known). Both hosts will then try to establish a connection to the other
-peer, which is usually possible even when both hosts are behind a \s-1NAT\s0
-gateway.
-.PP
-If the hosts cannot reach each other because they have no common protocol,
-the originator instead use the router with highest priority and matching
-protocol as peer. Since the \s-1SRCDST\s0 field is not encrypted, the router host
-can just forward the packet to the destination host. Since each host uses
-it's own private key, the router will not be able to decrypt or encrypt
-packets, it will just act as a simple router and protocol translator.
-.PP
-When no router is connected, the host will aggressively try to connect to
-all routers, and if a router is asked for an unconnected host it will try
-to ask another router to establish the connection.
-.PP
-\&... more not yet written about the details of the routing, please bug me
-\&...