git.tinc-vpn.org Git - tinc/blob - doc/PROTOCOL

   1 This is the protocol documentation for tinc, a Virtual Private Network daemon.
   2
   3    Copyright 2000-2006 Guus Sliepen <guus@tinc-vpn.org>,
   4              2000-2005 Ivo Timmmermans
   5
   6    Permission is granted to make and distribute verbatim copies of
   7    this documentation provided the copyright notice and this
   8    permission notice are preserved on all copies.
   9
  10    Permission is granted to copy and distribute modified versions of
  11    this documentation under the conditions for verbatim copying,
  12    provided that the entire resulting derived work is distributed
  13    under the terms of a permission notice identical to this one.
  14
  15 1.  Protocols used in tinc
  16 -------------------------
  17
  18 tinc uses several protocols to function correctly.  To enter the
  19 network of tinc daemons that make up the virtual private network, tinc
  20 makes TCP connections to other tinc daemons.  It uses the "meta
  21 protocol" for these connections.  To exchange packets on the virtual
  22 network, UDP connections are made and the "packet protocol" is used.
  23 Tinc also needs to exchange network packets with the kernel.  This is
  24 done using the ethertap device or the universal TUN/TAP device that
  25 can be found in various UNIX flavours.
  26
  27 2.  Packet protocol
  28 ------------------
  29
  30 Normal packets are sent without any state information, so the layout
  31 is pretty basic.
  32
  33 A data packet can only be sent if the encryption key, cipher and digest are
  34 known to both parties, and the connection is activated. If the encryption key
  35 is not known, a request is sent to the destination using the meta connection to
  36 retreive it.
  37
  38 0   1   2   3   4   5   6   7   ...   97  98  99  100
  39 |     seqno     |         data        |     MAC       |
  40 \____________________________________/\_______________/
  41                  |                           |
  42   encrypted using symmetric cipher         digest
  43
  44 The sequence number prevents replay attacks, the message authentication code
  45 prevents altered packets from being accepted.
  46
  47 3.  Meta protocol
  48 ----------------
  49
  50 The meta protocol is used to tie all tinc daemons together, and
  51 exchange information about which tinc daemon serves which virtual
  52 subnet.
  53
  54 The meta protocol consists of requests that can be sent to the other
  55 side.  Each request has a unique number and several parameters.  All
  56 requests are represented in the standard ASCII character set.  It is
  57 possible to use tools such as telnet or netcat to connect to a tinc
  58 daemon and to read and write requests by hand, provided that one
  59 understands the numeric codes sent.
  60
  61 The authentication scheme is described in the SECURITY2 file. After a
  62 succesful authentication, the server and the client will exchange all the
  63 information about other tinc daemons and subnets they know of, so that both
  64 sides (and all the other tinc daemons behind them) have their information
  65 synchronised.
  66
  67 daemon  message
  68 --------------------------------------------------------------------------
  69 origin  ADD_EDGE node1 node2 21.32.43.54 655 222 0
  70                    |     |        |       |   |  +-> options
  71                    |     |        |       |   +----> weight
  72                            |     |        |       +--------> UDP port of node2
  73                            |     |        +----------------> real address of node2
  74                            |     +-------------------------> name of destination node
  75                    +-------------------------------> name of source node
  76
  77 origin  ADD_SUBNET node 192.168.1.0/24
  78                      |         |     +--> prefixlength
  79                      |         +--------> network address
  80                      +------------------> owner of this subnet
  81 --------------------------------------------------------------------------
  82
  83 The ADD_EDGE messages are to inform other tinc daemons that a connection between
  84 two nodes exist. The address of the destination node is available so that
  85 VPN packets can be sent directly to that node.
  86
  87 The ADD_SUBNET messages inform other tinc daemons that certain subnets belong
  88 to certain nodes. tinc will use it to determine to which node a VPN packet has
  89 to be sent.
  90
  91 message
  92 ------------------------------------------------------------------
  93 DEL_EDGE node1 node2
  94                    |     +----> name of destination node
  95            +----------> name of source node
  96
  97 DEL_SUBNET node 192.168.1.0/24
  98              |         |     +--> prefixlength
  99              |         +--------> network address
 100              +------------------> owner of this subnet
 101 ------------------------------------------------------------------
 102
 103 In case a connection between two daemons is closed or broken, DEL_EDGE messages
 104 are sent to inform the other daemons of that fact. Each daemon will calculate a
 105 new route to the the daemons, or mark them unreachable if there isn't any.
 106
 107 message
 108 ------------------------------------------------------------------
 109 REQ_KEY origin destination
 110            |       +--> name of the tinc daemon it wants the key from
 111            +----------> name of the daemon that wants the key
 112
 113 ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4
 114            |       |       \______________/ |  |  +--> MAC length
 115            |       |               |        |  +-----> digest algorithm
 116            |       |               |        +--------> cipher algorithm
 117            |       |               +--> 128 bits key
 118            |       +--> name of the daemon that wants the key
 119            +----------> name of the daemon that uses this key
 120
 121 KEY_CHANGED origin
 122               +--> daemon that has changed it's packet key
 123 --------------------------------------------------------------------------
 124
 125 The keys used to encrypt VPN packets are not sent out directly. This is
 126 because it would generate a lot of traffic on VPNs with many daemons, and
 127 chances are that not every tinc daemon will ever send a packet to every
 128 other daemon. Instead, if a daemon needs a key it sends a request for it
 129 via the meta connection of the nearest hop in the direction of the
 130 destination. If any hop on the way has already learned the key, it will
 131 act as a proxy and forward its copy back to the requestor.
 132
 133 daemon  message
 134 --------------------------------------------------------------------------
 135 origin  PING
 136 dest.   PONG
 137 --------------------------------------------------------------------------
 138
 139 There is also a mechanism to check if hosts are still alive. Since network
 140 failures or a crash can cause a daemon to be killed without properly
 141 shutting down the TCP connection, this is necessary to keep an up to date
 142 connection list. Pings are sent at regular intervals, except when there
 143 is also some other traffic. A little bit of salt (random data) is added
 144 with each PING and PONG message, to make sure that long sequences of PING/PONG
 145 messages without any other traffic won't result in known plaintext.
 146
 147 This basically covers everything that is sent over the meta connection by
 148 tinc.