This is the protocol documentation for tinc, a Virtual Private Network daemon.
- Copyright 2000 Guus Sliepen <guus@sliepen.warande.net>
+ Copyright 2000-2002 Guus Sliepen <guus@sliepen.eu.org>,
+ 2000-2002 Ivo Timmmermans <ivo@o2w.nl>
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.8 2002/09/15 22:19:37 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 node2 21.32.43.54 655 222 0
+ | | | | | +-> options
+ | | | | +----> weight
+ | | | +--------> UDP port of node2
+ | | +----------------> real address of node2
+ | +-------------------------> name of destination node
+ +-------------------------------> name of source node
+
+origin ADD_SUBNET node 192.168.1.0/24
+ | | +--> prefixlength
+ | +--------> network address
+ +------------------> owner of this subnet
+--------------------------------------------------------------------------
+
+The ADD_EDGE messages are to inform other tinc daemons that a connection between
+two nodes exist. The address of the destination node is available so that
+VPN packets can be sent directly to that node.
+
+The ADD_SUBNET messages inform other tinc daemons that certain subnets belong
+to certain nodes. tinc will use it to determine to which node a VPN packet has
+to be sent.
+
+message
+------------------------------------------------------------------
+DEL_EDGE node1 node2
+ | +----> name of destination node
+ +----------> name of source node
+
+DEL_SUBNET node 192.168.1.0/24
+ | | +--> prefixlength
+ | +--------> 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.
+
+message
+------------------------------------------------------------------
+REQ_KEY origin destination
+ | +--> name of the tinc daemon it wants the key from
+ +----------> name of the daemon that wants the key
+
+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
+
+KEY_CHANGED origin
+ +--> daemon that has changed it's packet key
+--------------------------------------------------------------------------
+
+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
+--------------------------------------------------------------------------
+origin PING
+dest. PONG
+--------------------------------------------------------------------------
+
+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. A little bit of salt (random data) is added
+with each PING and PONG message, to make sure that long sequences of PING/PONG
+messages without any other traffic won't result in known plaintext.
+
+This basically covers everything that is sent over the meta connection by
+tinc.
projects / tinc / blobdiff