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 Guus Sliepen <guus@sliepen.warande.net>,
   4              2000 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.3 2000/09/10 15:07:41 zarq 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 in Linux.  Also planned is a generic
  28 PPP interface, because it is supported on virtually all UNIX flavours.
  29 The protocols for those interfaces will not be described in this
  30 document.
  31
  32 2.  Packet protocol
  33 ------------------
  34
  35 Normal packets are sent without any state information, so the layout
  36 is pretty basic.  An exception to this are the connections which only
  37 use TCP (configured with the directive `TCPonly=yes').  An explanation
  38 of this type of packet is given in the next chapter, when we explain
  39 the meta protocol.
  40
  41 A data packet can only be sent  if the encryption key is known to both
  42 parties, and the connection is  activated.  Normally, tinc opens a UDP
  43 connection when it  receives an acknowledgement that the  newly set up
  44 connection is properly initiated, and has been verified.
  45
  46  0   1   2   3
  47 |  SOURCE IP  |
  48 | SEQUENCE ID |
  49 | LEN  | DATA :   \
  50 : DATA        .   } encrypted
  51 . :               /
  52   .
  53
  54
  55 3.  Meta protocol
  56 ----------------
  57
  58 The meta protocol is used to tie all tinc daemons together, and
  59 exchange information about which tinc daemon serves which virtual
  60 subnet.
  61
  62 The meta protocol consists of requests that can be sent to the other
  63 side.  Each request has a unique number and several parameters.  All
  64 requests are represented in the standard ASCII character set.  It is
  65 possible to use tools such as telnet or netcat to connect to a tinc
  66 daemon and to read and write requests by hand, provided that one
  67 understands the numeric codes sent.
  68
  69 When tinc daemons connect to each other, they will have to
  70 authenticate each other first.  This is done by exchanging BASIC_INFO,
  71 PASSPHRASE, PUBLIC_KEY and ACK requests.  BASIC_INFO requests contain
  72 the virtual address and netmask of the tinc daemon, protocol version,
  73 port number and flags.  This identifies that tinc daemon, though it
  74 still has to be verified.  To that end, passphrases and public keys are
  75 exchanged.  The passphrases are known at both ends, but they are
  76 encrypted with the public key before transmission.  This way, nobody
  77 that sniffs the network can see what the passphrase actually was, and
  78 at the same time this ensures that the other host really knows the
  79 secret key that belongs to the public key it sends.  If both hosts are
  80 satisfied, the connection is activated, the contents of each other's
  81 connection lists are exchanged and other requests may be sent.  The
  82 following diagram shows how authentication is done:
  83
  84 Client                          Server
  85 ----------------------------------------------------------------
  86
  87
  88 ----------------------------------------------------------------
  89
  90 The client must never make a connection to a server that is already in
  91 it's connection list.  Not only would it corrupt the connection list,
  92 but it would also violate the tree property.  The meta connections must
  93 always be so that there are no loops.  This is very important, because
  94 certain requests are broadcast over the entire network of tinc
  95 daemons.  If there were loops in the network topology, some packets
  96 would be forwarded in a ring until the end of times (or until the ring
  97 breaks, which probably happens before time ends).