tinc/doc/PROTOCOL

This is the protocol documentation for tinc, a Virtual Private Network daemon.

   Copyright 2000-2006 Guus Sliepen <guus@tinc-vpn.org>,
             2000-2005 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.

   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$


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 or the universal TUN/TAP device that
can be found in various UNIX flavours.

2.  Packet protocol
------------------

Normal packets are sent without any state information, so the layout
is pretty basic.

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.

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.