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
   5    Permission is granted to make and distribute verbatim copies of
   6    this documentation provided the copyright notice and this permission
   7    notice are preserved on all copies.
   8
   9    Permission is granted to copy and distribute modified versions
  10    of this documentation under the conditions for verbatim copying, provided
  11    that the entire resulting derived work is distributed under
  12    the terms of a permission notice identical to this one.
  13
  14    $Id: PROTOCOL,v 1.1.2.2 2000/07/01 14:32:24 guus Exp $
  15
  16
  17 1. Protocols used in tinc
  18 -------------------------
  19
  20 Tinc uses several protocols to function correctly. To enter the network of tinc
  21 daemons that make up the virtual private network, tinc makes TCP connections to
  22 other tinc daemons. It uses the "meta protocol" for these connections. To
  23 exchange packets on the virtual network, UDP connections are made and the
  24 "packet protocol" is used. Tinc also needs to exchange network packets with the
  25 kernel. This is done using the ethertap device in Linux. Also planned is a
  26 generic PPP interface, because it is supported on virtually all UNIX flavours.
  27 The protocols for those interfaces will not be described in this document.
  28
  29 2. Packet protocol
  30 ------------------
  31
  32 See net.h for now.
  33
  34 3. Meta protocol
  35 ----------------
  36
  37 The meta protocol is used to tie all tinc daemons together, and exchange
  38 information about which tinc daemon serves which virtual subnet.
  39
  40 The meta protocol consists of requests that can be sent to the other side. Each
  41 request has a unique number and several parameters. All requests are represented
  42 in the standard ASCII character set. It is possible to use tools such as telnet
  43 or netcat to connect to a tinc daemon and to read and write requests by hand,
  44 provided that one understands the numeric codes sent.
  45
  46 When tinc daemons connect to each other, they will have to authenticate each
  47 other first. This is done by exchanging BASIC_INFO, PASSPHRASE, PUBLIC_KEY and
  48 ACK requests. BASIC_INFO requests contain the virtual address and netmask of the
  49 tinc daemon, protocol version, port number and flags. This identifies that tinc
  50 daemon, though it still has to be verified. To that end, passphrases and public
  51 keys are exchanged. The passphrases are known at both ends, but they are
  52 encrypted with the public key before transmission. This way, nobody that sniffs
  53 the network can see what the passphrase actually was, and at the same time this
  54 ensures that the other host really knows the secret key that belongs to the
  55 public key it sends. If both hosts are satisfied, the connection is activated,
  56 the contents of each other's connection lists are exchanged and other requests
  57 may be sent. The following diagram shows how authentication is done:
  58
  59 Client                          Server
  60 ----------------------------------------------------------------
  61 Connects to server:
  62                                 Accepts connection.
  63                                 Sends BASIC_INFO:
  64 Verifies BASIC_INFO.
  65 If server is already in
  66 connection list, abort.
  67 Else sends his own BASIC_INFO:
  68                                 Verifies BASIC_INFO.
  69                                 If client is alread in
  70                                 connection list, remove
  71                                 old entry.
  72                                 Sends PASSPHRASE:
  73 Receives and stores PASSPHRASE.
  74 Sends his own PASSPHRASE:
  75                                 Receives and stores PASSPHRASE.
  76                                 Sends PUBLIC_KEY:
  77 Verifies PUBLIC key and stored
  78 PASSPHRASE. If wrong, abort.
  79 Else sends his own PUBLIC_KEY:
  80                                 Verifies PUBLIC key and stored
  81                                 PASSPHRASE. If wrong, abort.
  82                                 Else activates connection and
  83                                 sends ACK and ADD_HOSTs for all
  84                                 known hosts.
  85 Receives ACK and activates
  86 connection.
  87 Sends ADD_HOSTs for all known
  88 hosts.
  89 ----------------------------------------------------------------
  90
  91 The client must never make a connection to a server that is already in it's
  92 connection list. Not only would it corrupt the connection list, but it would
  93 also violate the tree property. The meta connections must always be so that
  94 there are no loops. This is very important, because certain requests are
  95 broadcast over the entire network of tinc daemons. If there were loops, packets
  96 would be sent infinitely.