fix typo in pt.po headers
[debian/iodine.git] / doc / proto_00000502.txt
1 Detailed specification of protocol in version 00000502
2 ======================================================
3
4 Note: work in progress!!
5
6 ======================================================
7 1. DNS protocol
8 ======================================================
9
10 Quick alphabetical index / register:
11         0-9     Data packet
12         A-F     Data packet
13         I       IP address
14         L       Login
15         N       Downstream fragsize     (NS.topdomain A-type reply)
16         O       Options
17         P       Ping
18         R       Downstream fragsize probe
19         S       Switch upstream codec
20         V       Version
21         W                               (WWW.topdomain A-type reply)
22         Y       Downstream codec check
23         Z       Upstream codec check
24
25
26 CMC = 2 byte Cache Miss Counter, increased every time it is used
27
28 Version:
29 Client sends:
30         First byte v or V
31         Rest encoded with base32:
32         4 bytes big endian protocol version
33         CMC
34 Server replies:
35         4 chars:
36                 VACK (version ok), followed by login challenge
37                 VNAK (version differs), followed by server protocol version
38                 VFUL (server has no free slots), followed by max users
39         4 byte value: means login challenge/server protocol version/max users
40         1 byte userid of the new user, or any byte if not VACK
41         
42 Login:
43 Client sends:
44         First byte l or L
45         Rest encoded with base32:
46         1 byte userid
47         16 bytes MD5 hash of: (first 32 bytes of password) xor (8 repetitions of login challenge)
48         CMC
49 Server replies:
50         LNAK means not accepted
51         x.x.x.x-y.y.y.y-mtu-netmask means accepted (server ip, client ip, mtu, netmask bits)
52
53 IP Request:
54 Client sends:
55         First byte i or I
56         5 bits coded as Base32 char, meaning userid
57         CMC as 3 Base32 chars
58 Server replies
59         BADIP if bad userid, or
60         I and then 4 bytes network order external IP address of iodined server
61
62 Upstream codec check / bounce:
63 Client sends: 
64         First byte z or Z
65         Lots of data that should not be decoded
66 Server replies:
67         The requested domain copied raw, in the lowest-grade downstream codec
68         available for the request type.
69
70 Downstream codec check:
71 Client sends:
72         First byte y or Y
73         1 char, meaning downstream codec to use
74         5 bits coded as Base32 char, meaning check variant
75         CMC as 3 Base32 chars
76         Possibly extra data, depending on check variant
77 Server sends:
78         Data encoded with requested downstream codec; data content depending
79         on check variant number.
80         BADCODEC if requested downstream codec not available.
81         BADLEN if check variant is not available, or problem with extra data.
82
83         Downstream codec chars are same as in 'O' Option request, below.
84
85         Check variants:
86         1: Send encoded DOWNCODECCHECK1 string as defined in encoding.h
87
88         (Other variants reserved; possibly variant that sends a decoded-encoded
89         copy of Base32-encoded extra data in the request)
90
91 Switch codec:
92 Client sends:
93         First byte s or S
94         5 bits coded as Base32 char, meaning userid
95         5 bits coded as Base32 char, representing number of raw bits per
96         encoded byte:
97                 5: Base32   (a-z0-5)
98                 6: Base64   (a-zA-Z0-9+-)
99                 26: Base64u (a-zA-Z0-9_-)
100                 7: Base128  (a-zA-Z0-9\274-\375)
101         CMC as 3 Base32 chars
102 Server sends:
103         Name of codec if accepted. After this all upstream data packets must 
104         be encoded with the new codec.
105         BADCODEC if not accepted. Client must then revert to previous codec
106         BADLEN if length of query is too short
107
108 Options:
109 Client sends:
110         First byte o or O
111         5 bits coded as Base32 char, meaning userid
112         1 char, meaning option
113         CMC as 3 Base32 chars
114 Server sends:
115         Full name of option if accepted. After this, option immediately takes
116         effect in server.
117         BADCODEC if not accepted. Previous situation remains.
118         All options affect only the requesting client.
119
120         Option chars:
121         t or T: Downstream encoding Base32, for TXT/CNAME/A/MX (default)
122         s or S: Downstream encoding Base64, for TXT/CNAME/A/MX
123         u or U: Downstream encoding Base64u, for TXT/CNAME/A/MX
124         v or V: Downstream encoding Base128, for TXT/CNAME/A/MX
125         r or R: Downstream encoding Raw, for PRIVATE/TXT/NULL (default for
126                 PRIVATE and NULL)
127         If codec unsupported for request type, server will use Base32; note
128         that server will answer any mix of request types that a client sends.
129         Server may disregard this option; client must always use the downstream
130         encoding type indicated in every downstream DNS packet.
131
132         l or L: Lazy mode, server will keep one request unanswered until the
133         next one comes in. Applies only to data transfer; handshake is always
134         answered immediately.
135         i or I: Immediate (non-lazy) mode, server will answer all requests
136         (nearly) immediately.
137
138 Probe downstream fragment size:
139 Client sends:
140         First byte r or R
141         15 bits coded as 3 Base32 chars: UUUUF FFFFF FFFFF
142                 meaning 4 bits userid, 11 bits fragment size
143         Then follows a long random query which contents does not matter
144 Server sends:
145         Requested number of bytes as a response. The first two bytes contain
146         the requested length. The third byte is 107 (0x6B). The fourth byte
147         is a random value, and each following byte is incremented with 107.
148         This is checked by the client to determine corruption.
149         BADFRAG if requested length not accepted.
150
151 Set downstream fragment size:
152 Client sends:
153         First byte n or N
154         Rest encoded with base32:
155         1 byte userid
156         2 bytes new downstream fragment size
157         CMC
158 Server sends:
159         2 bytes new downstream fragment size. After this all downstream
160         payloads will be max (fragsize + 2) bytes long.
161         BADFRAG if not accepted.
162
163 Data:
164 Upstream data header:
165          3210 432 10 43 210 4321 0 43210
166         +----+---+--+--+---+----+-+-----+
167         |UUUU|SSS|FF|FF|DDD|GGGG|L|UDCMC|
168         +----+---+--+--+---+----+-+-----+
169
170 Downstream data header:
171          7 654 3210 765 4321 0
172         +-+---+----+---+----+-+
173         |C|SSS|FFFF|DDD|GGGG|L|
174         +-+---+----+---+----+-+
175
176 UUUU = Userid
177 L = Last fragment in packet flag
178 SS = Upstream packet sequence number
179 FFFF = Upstream fragment number
180 DDD = Downstream packet sequence number
181 GGGG = Downstream fragment number
182 C = Compression enabled for downstream packet
183 UDCMC = Upstream Data CMC, 36 steps a-z0-9, case-insensitive
184
185 Upstream data packet starts with 1 byte ASCII hex coded user byte; then 3 bytes 
186 Base32 encoded header; then 1 char data-CMC; then comes the payload data,
187 encoded with the chosen upstream codec.
188
189 Downstream data starts with 2 byte header. Then payload data, which may be
190 compressed.
191
192 In NULL and PRIVATE responses, downstream data is always raw. In all other
193 response types, downstream data is encoded (see Options above).
194 Encoding type is indicated by 1 prefix char:
195 TXT:
196         End result is always DNS-chopped (series of len-prefixed strings
197         <=255 bytes)
198         t or T: Base32   encoded before chop, decoded after un-chop
199         s or S: Base64   encoded before chop, decoded after un-chop
200         u or U: Base64u  encoded before chop, decoded after un-chop
201         v or V: Base128  encoded before chop, decoded after un-chop
202         r or R: Raw      no encoding, only DNS-chop
203 SRV/MX/CNAME/A:
204         h or H: Hostname encoded with Base32
205         i or I: Hostname encoded with Base64
206         j or J: Hostname encoded with Base64u
207         k or K: Hostname encoded with Base128
208 SRV and MX may reply with multiple hostnames, each encoded separately. Each
209 has a 10-multiple priority, and encoding/decoding is done in strictly
210 increasing priority sequence 10, 20, 30, etc. without gaps. Note that some DNS
211 relays will shuffle the answer records in the response.
212
213 Ping:
214 Client sends:
215         First byte p or P
216         Rest encoded with Base32:
217         1 byte with 4 bits userid
218         1 byte with:
219                 3 bits downstream seqno
220                 4 bits downstream fragment
221         CMC
222
223 The server response to Ping and Data packets is a DNS NULL/TXT/.. type response,
224 always starting with the 2 bytes downstream data header as shown above.
225 If server has nothing to send, no data is added after the header.
226 If server has something to send, it will add the downstream data packet
227 (or some fragment of it) after the header.
228  
229  
230 "Lazy-mode" operation
231 =====================
232
233 Client-server DNS traffic sequence has been reordered to provide increased
234 (interactive) performance and greatly reduced latency.
235
236 Idea taken from Lucas Nussbaum's slides (24th IFIP International Security
237 Conference, 2009) at http://www.loria.fr/~lnussbau/tuns.html. Current
238 implementation is original to iodine, no code or documentation from any other
239 project was consulted during development.
240
241 Server:
242 Upstream data is acked immediately*, to keep the slow upstream data flowing
243 as fast as possible (client waits for ack to send next frag).
244
245 Upstream pings are answered _only_ when 1) downstream data arrives from tun,
246 OR 2) new upstream ping/data arrives from client.
247 In most cases, this means we answer the previous DNS query instead of the
248 current one. The current query is kept in queue and used as soon as
249 downstream data has to be sent.
250
251 *: upstream data ack is usually done as reply on the previous ping packet,
252 and the upstream-data packet itself is kept in queue.
253  
254 Client:
255 Downstream data is acked immediately, to keep it flowing fast (includes a
256 ping after last downstream frag).
257
258 Also, after all available upstream data is sent & acked by the server (which
259 in some cases uses up the last query), send an additional ping to prime the
260 server for the next downstream data.
261
262
263 ======================================================
264 2. Raw UDP protocol
265 ======================================================
266
267 All Raw UDP protcol messages start with a 3 byte header: 0x10d19e
268 This is not the start of a valid DNS message so it is easy to identify.
269 The fourth byte contains the command and the user id.
270
271          7654 3210
272         +----+----+
273         |CCCC|UUUU|
274         +----+----+
275
276 Login message (command = 1):
277 The header is followed by a MD5 hash with the same password as in the DNS
278 login. The client starts the raw mode by sending this message, and uses
279 the login challenge +1, and the server responds using the login challenge -1.
280 After the login message has been exchanged, both the server and the client
281 switch to raw udp mode for the rest of the connection.
282
283 Data message (command = 2):
284 After the header comes the payload data, which may be compressed.
285
286 Ping message (command = 3):
287 Sent from client to server and back to keep session open. Has no payload.
288