X-Git-Url: https://www.tinc-vpn.org/git/browse?p=tinc;a=blobdiff_plain;f=doc%2FPROTOCOL;h=da9c75ba5de51bfd663e7989cff555dc2f234bef;hp=81de215c52bfab7121ab8a23558feadfec82d5e2;hb=b1322d244ff24e900f2298b8aa775d825c8ab00b;hpb=8ec648abf438bb5fcfe84e3a1c6a31192dc32b2e diff --git a/doc/PROTOCOL b/doc/PROTOCOL index 81de215c..da9c75ba 100644 --- a/doc/PROTOCOL +++ b/doc/PROTOCOL @@ -1,96 +1,129 @@ This is the protocol documentation for tinc, a Virtual Private Network daemon. - Copyright 2000 Guus Sliepen + Copyright 2000-2002 Guus Sliepen , + 2000-2002 Ivo Timmmermans Permission is granted to make and distribute verbatim copies of - this documentation provided the copyright notice and this permission - notice are preserved on all copies. + this documentation provided the copyright notice and this + permission notice are preserved on all copies. - Permission is granted to copy and distribute modified versions - of this documentation under the conditions for verbatim copying, provided - that the entire resulting derived work is distributed under - the terms of a permission notice identical to this one. + Permission is granted to copy and distribute modified versions of + this documentation under the conditions for verbatim copying, + provided that the entire resulting derived work is distributed + under the terms of a permission notice identical to this one. - $Id: PROTOCOL,v 1.1.2.1 2000/06/30 22:38:58 guus Exp $ + $Id: PROTOCOL,v 1.1.2.6 2002/04/09 11:43:29 guus Exp $ -1. Protocols used in tinc +1. Protocols used in tinc ------------------------- -Tinc uses several protocols to function correctly. To enter the network of tinc -daemons that make up the virtual private network, tinc makes TCP connections to -other tinc daemons. It uses the "meta protocol" for these connections. To -exchange packets on the virtual network, UDP connections are made and the -"packet protocol" is used. Tinc also needs to exchange network packets with the -kernel. This is done using the ethertap device in Linux. Also planned is a -generic PPP interface, because it is supported on virtually all UNIX flavours. -The protocols for those interfaces will not be described in this document. +tinc uses several protocols to function correctly. To enter the +network of tinc daemons that make up the virtual private network, tinc +makes TCP connections to other tinc daemons. It uses the "meta +protocol" for these connections. To exchange packets on the virtual +network, UDP connections are made and the "packet protocol" is used. +Tinc also needs to exchange network packets with the kernel. This is +done using the ethertap device or the universal TUN/TAP device that +can be found in various UNIX flavours. -2. Packet protocol +2. Packet protocol ------------------ -This is described in net.h. +Normal packets are sent without any state information, so the layout +is pretty basic. -3. Meta protocol +A data packet can only be sent if the encryption key, cipher and digest are +known to both parties, and the connection is activated. If the encryption key +is not known, a request is sent to the destination using the meta connection to +retreive it. + +0 1 2 3 4 5 6 7 ... 97 98 99 100 +| seqno | data | MAC | +\____________________________________/\_______________/ + | | + encrypted using symmetric cipher digest + +The sequence number prevents replay attacks, the message authentication code +prevents altered packets from being accepted. + +3. Meta protocol ---------------- -The meta protocol is used to tie all tinc daemons together, and exchange -information about which tinc daemon serves which virtual subnet. - -The meta protocol consists of requests that can be sent to the other side. Each -request has a unique number and several parameters. All requests are represented -in the standard ASCII character set. It is possible to use tools such as telnet -or netcat to connect to a tinc daemon and to read and write requests by hand, -provided that one understands the numeric codes sent. - -When tinc daemons connect to each other, they will have to authenticate each -other first. This is done by exchanging BASIC_INFO, PASSPHRASE, PUBLIC_KEY and -ACK requests. BASIC_INFO requests contain the virtual address and netmask of the -tinc daemon, protocol version, port number and flags. This identifies that tinc -daemon, though it still has to be verified. To that end, passphrases and public -keys are exchanged. The passphrases are known at both ends, but they are -encrypted with the public key before transmission. This way, nobody that sniffs -the network can see what the passphrase actually was, and at the same time this -ensures that the other host really knows the secret key that belongs to the -public key it sends. If both hosts are satisfied, the connection is activated, -the contents of each other's connection lists are exchanged and other requests -may be sent. The following diagram shows how authentication is done: - -Client Server ----------------------------------------------------------------- -Connects to server - Accepts connection - Sends BASIC_INFO -Verifies BASIC_INFO -If server is already in -connection list, abort. -Else sends his own BASIC_INFO - Verifies BASIC_INFO - If client is alread in - connection list, remove - old entry. - Sends PASSPHRASE -Receives and stores PASSPHRASE. -Sends his own PASSPHRASE - Receives and stores PASSPHRASE. - Sends PUBLIC_KEY -Verifies PUBLIC key and stored -PASSPHRASE. If wrong, abort. -Else sends his own PUBLIC_KEY - Verifies PUBLIC key and stored - PASSPHRASE. If wrong, abort. - Else activates connection and - sends ACK and ADD_HOSTs for all - known hosts -Receives ACK and activates -connection. -Sends ADD_HOSTs for all known -hosts ----------------------------------------------------------------- - -The client must never make a connection to a server that is already in it's -connection list. Not only would it corrupt the connection list, but it would -also violate the tree property. The meta connections must always be so that -there are no loops. This is very important, because certain requests are -broadcast over the entire network of tinc daemons. If there were loops, packets -would be sent infinitely. +The meta protocol is used to tie all tinc daemons together, and +exchange information about which tinc daemon serves which virtual +subnet. + +The meta protocol consists of requests that can be sent to the other +side. Each request has a unique number and several parameters. All +requests are represented in the standard ASCII character set. It is +possible to use tools such as telnet or netcat to connect to a tinc +daemon and to read and write requests by hand, provided that one +understands the numeric codes sent. + +The authentication scheme is described in the SECURITY2 file. After a +succesful authentication, the server and the client will exchange all the +information about other tinc daemons and subnets they know of, so that both +sides (and all the other tinc daemons behind them) have their information +synchronised. + +daemon message +-------------------------------------------------------------------------- +origin ADD_EDGE node1 12.23.34.45 655 node2 21.32.43.54 655 222 0 + | | | \___________________/ | +-> options + | | | | +----> weight + | | | +----------------> see below + | | +--> UDP port + | +----------> real address + +------------------> name of node on one side of the edge + +origin ADD_SUBNET node 192.168.1.0/24 + | | +--> prefixlength + | +--------> IPv4 network address + +------------------> owner of this subnet +-------------------------------------------------------------------------- + +In case a connection between two daemons is closed or broken, DEL_EDGE messages +are sent to inform the other daemons of that fact. Each daemon will calculate a +new route to the the daemons, or mark them unreachable if there isn't any. + +The keys used to encrypt VPN packets are not sent out directly. This is +because it would generate a lot of traffic on VPNs with many daemons, and +chances are that not every tinc daemon will ever send a packet to every +other daemon. Instead, if a daemon needs a key it sends a request for it +via the meta connection of the nearest hop in the direction of the +destination. If any hop on the way has already learned the key, it will +act as a proxy and forward its copy back to the requestor. + +daemon message +-------------------------------------------------------------------------- +daemon REQ_KEY origin destination + | +--> name of the tinc daemon it wants the key from + +----------> name of the daemon that wants the key + +daemon ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4 + | | \______________/ | | +--> MAC length + | | | | +-----> digest algorithm + | | | +--------> cipher algorithm + | | +--> 128 bits key + | +--> name of the daemon that wants the key + +----------> name of the daemon that uses this key + +daemon KEY_CHANGED origin + +--> daemon that has changed it's packet key +-------------------------------------------------------------------------- + +There is also a mechanism to check if hosts are still alive. Since network +failures or a crash can cause a daemon to be killed without properly +shutting down the TCP connection, this is necessary to keep an up to date +connection list. Pings are sent at regular intervals, except when there +is also some other traffic. + +daemon message +-------------------------------------------------------------------------- +origin PING +dest. PONG +-------------------------------------------------------------------------- + +This basically covers everything that is sent over the meta connection by +tinc.