PROTOCOL 6.7 KB

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