]> git.meshlink.io Git - meshlink/blob - doc/PROTOCOL
Check for ranlib.
[meshlink] / doc / PROTOCOL
1 This is the protocol documentation for tinc, a Virtual Private Network daemon.
2
3    Copyright 2000-2002 Guus Sliepen <guus@sliepen.eu.org>,
4              2000-2002 Ivo Timmmermans <ivo@o2w.nl>
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.7 2002/06/21 10:11:10 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, cipher and digest are
37 known to both parties, and the connection is activated. If the encryption key
38 is not known, a request is sent to the destination using the meta connection to
39 retreive it.
40
41 0   1   2   3   4   5   6   7   ...   97  98  99  100
42 |     seqno     |         data        |     MAC       |
43 \____________________________________/\_______________/
44                  |                           |
45   encrypted using symmetric cipher         digest
46
47 The sequence number prevents replay attacks, the message authentication code
48 prevents altered packets from being accepted.
49
50 3.  Meta protocol
51 ----------------
52
53 The meta protocol is used to tie all tinc daemons together, and
54 exchange information about which tinc daemon serves which virtual
55 subnet.
56
57 The meta protocol consists of requests that can be sent to the other
58 side.  Each request has a unique number and several parameters.  All
59 requests are represented in the standard ASCII character set.  It is
60 possible to use tools such as telnet or netcat to connect to a tinc
61 daemon and to read and write requests by hand, provided that one
62 understands the numeric codes sent.
63
64 The authentication scheme is described in the SECURITY2 file. After a
65 succesful authentication, the server and the client will exchange all the
66 information about other tinc daemons and subnets they know of, so that both
67 sides (and all the other tinc daemons behind them) have their information
68 synchronised.
69
70 daemon  message
71 --------------------------------------------------------------------------
72 origin  ADD_EDGE node1 12.23.34.45 655 node2 21.32.43.54 655 222 0
73                     |       |       |  \___________________/  |  +-> options
74                     |       |       |             |           +----> weight
75                     |       |       |             +----------------> see below
76                     |       |       +--> UDP port
77                     |       +----------> real address
78                     +------------------> name of node on one side of the edge
79
80 origin  ADD_SUBNET node 192.168.1.0/24
81                      |         |     +--> prefixlength
82                      |         +--------> IPv4 network address
83                      +------------------> owner of this subnet
84 --------------------------------------------------------------------------
85
86 In case a connection between two daemons is closed or broken, DEL_EDGE messages
87 are sent to inform the other daemons of that fact. Each daemon will calculate a
88 new route to the the daemons, or mark them unreachable if there isn't any.
89
90 The keys used to encrypt VPN packets are not sent out directly. This is
91 because it would generate a lot of traffic on VPNs with many daemons, and
92 chances are that not every tinc daemon will ever send a packet to every
93 other daemon. Instead, if a daemon needs a key it sends a request for it
94 via the meta connection of the nearest hop in the direction of the
95 destination. If any hop on the way has already learned the key, it will
96 act as a proxy and forward its copy back to the requestor.
97
98 daemon  message
99 --------------------------------------------------------------------------
100 daemon  REQ_KEY origin destination
101                    |       +--> name of the tinc daemon it wants the key from
102                    +----------> name of the daemon that wants the key      
103
104 daemon  ANS_KEY origin destination 4ae0b0a82d6e0078 91 64 4
105                    |       |       \______________/ |  |  +--> MAC length
106                    |       |               |        |  +-----> digest algorithm
107                    |       |               |        +--------> cipher algorithm
108                    |       |               +--> 128 bits key
109                    |       +--> name of the daemon that wants the key
110                    +----------> name of the daemon that uses this key
111
112 daemon  KEY_CHANGED origin
113                       +--> daemon that has changed it's packet key
114 --------------------------------------------------------------------------
115
116 There is also a mechanism to check if hosts are still alive. Since network
117 failures or a crash can cause a daemon to be killed without properly
118 shutting down the TCP connection, this is necessary to keep an up to date
119 connection list. Pings are sent at regular intervals, except when there
120 is also some other traffic.
121
122 daemon  message
123 --------------------------------------------------------------------------
124 origin  PING
125 dest.   PONG
126 --------------------------------------------------------------------------
127
128 This basically covers everything that is sent over the meta connection by
129 tinc.