www.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,2001 Guus Sliepen <guus@sliepen.warande.net>,
   4              2000,2001 Ivo Timmmermans <itimmermans@bigfoot.com>
   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    $Id: PROTOCOL,v 1.1.2.4 2001/01/07 17:08:02 guus Exp $
  16
  17
  18 1.  Protocols used in tinc
  19 -------------------------
  20
  21 tinc uses several protocols to function correctly.  To enter the
  22 network of tinc daemons that make up the virtual private network, tinc
  23 makes TCP connections to other tinc daemons.  It uses the "meta
  24 protocol" for these connections.  To exchange packets on the virtual
  25 network, UDP connections are made and the "packet protocol" is used.
  26 Tinc also needs to exchange network packets with the kernel.  This is
  27 done using the ethertap device or the universal TUN/TAP device that
  28 can be found in various UNIX flavours.
  29
  30 2.  Packet protocol
  31 ------------------
  32
  33 Normal packets are sent without any state information, so the layout
  34 is pretty basic.
  35
  36 A data packet can only be sent  if the encryption key is known to both
  37 parties, and the connection is  activated. If the encryption key is not
  38 known, a request is sent to the destination using the meta connection
  39 to retreive it.
  40
  41  0   1   2   3
  42 | LEN  | DATA :   \
  43 : DATA        .   } encrypted
  44 . :               /
  45   .
  46
  47
  48 3.  Meta protocol
  49 ----------------
  50
  51 The meta protocol is used to tie all tinc daemons together, and
  52 exchange information about which tinc daemon serves which virtual
  53 subnet.
  54
  55 The meta protocol consists of requests that can be sent to the other
  56 side.  Each request has a unique number and several parameters.  All
  57 requests are represented in the standard ASCII character set.  It is
  58 possible to use tools such as telnet or netcat to connect to a tinc
  59 daemon and to read and write requests by hand, provided that one
  60 understands the numeric codes sent.
  61
  62 The authentication scheme is described in the SECURITY file. After a
  63 succesful authentication, the server and the client will exchange all the
  64 information about other tinc daemons and subnets they know of, so that both
  65 sides (and all the other tinc daemons behind them) have their information
  66 synchronised.
  67
  68 daemon  message
  69 --------------------------------------------------------------------------
  70 origin  ADD_HOST daemon a329e18c:655 0
  71                     |         |      +--> options
  72                     |         +---------> real address:port
  73                     +-------------------> name of new tinc daemon
  74 origin  ADD_SUBNET daemon 1,0a010100/ffffff00
  75                       |   |     |       +--> netmask
  76                       |   |     +----------> vpn IPv4 network address
  77                       |   +----------------> subnet type (1=IPv4)
  78                       +--------------------> owner of this subnet
  79 --------------------------------------------------------------------------
  80
  81 In case daemons leave the VPN, DEL_HOST and DEL_SUBNET messages with exactly
  82 the same syntax are sent to inform the other daemons of the departure.
  83
  84 The keys used to encrypt VPN packets are not sent out directly. This is
  85 because it would generate a lot of traffic on VPNs with many daemons, and
  86 chances are that not every tinc daemon will ever send a packet to every
  87 other daemon. Instead, if a daemon needs a key it sends a request for it
  88 via the meta connection of the nearest hop in the direction of the
  89 destination. If any hop on the way has already learned the key, it will
  90 act as a proxy and forward it's copy back to the requestor.
  91
  92 daemon  message
  93 --------------------------------------------------------------------------
  94 daemon  REQ_KEY origin destination
  95                    |       +--> name of the tinc daemon it wants the key from
  96                    +----------> name of the daemon that wants the key
  97 daemon  ANS_KEY origin destination e4ae0b0a82d6e0078179b5290c62c7d0
  98                    |       |       \______________________________/
  99                    |       |                      +--> 128 bits key
 100                    |       +--> name of the daemon that wants the key
 101                    +----------> name of the daemon that uses this key
 102 daemon  KEY_CHANGED origin
 103                       +--> daemon that has changed it's packet key
 104 --------------------------------------------------------------------------
 105
 106 There is also a mechanism to check if hosts are still alive. Since network
 107 failures or a crash can cause a daemon to be killed without properly
 108 shutting down the TCP connection, this is necessary to keep an up to date
 109 connection list. Pings are sent at regular intervals, except when there
 110 is also some other traffic.
 111
 112 daemon  message
 113 --------------------------------------------------------------------------
 114 origin  PING
 115 dest.   PONG
 116 --------------------------------------------------------------------------
 117
 118 This basically covers everything that is sent over the meta connection by
 119 tinc.