diff options
Diffstat (limited to 'src/cadet/gnunet-service-cadet_tunnel.h')
-rw-r--r-- | src/cadet/gnunet-service-cadet_tunnel.h | 531 |
1 files changed, 531 insertions, 0 deletions
diff --git a/src/cadet/gnunet-service-cadet_tunnel.h b/src/cadet/gnunet-service-cadet_tunnel.h new file mode 100644 index 000000000..16616de59 --- /dev/null +++ b/src/cadet/gnunet-service-cadet_tunnel.h | |||
@@ -0,0 +1,531 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | (C) 2013 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 3, or (at your | ||
8 | option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file cadet/gnunet-service-cadet_tunnel.h | ||
23 | * @brief cadet service; dealing with tunnels and crypto | ||
24 | * @author Bartlomiej Polot | ||
25 | * | ||
26 | * All functions in this file should use the prefix GMT (Gnunet Cadet Tunnel) | ||
27 | */ | ||
28 | |||
29 | #ifndef GNUNET_SERVICE_CADET_TUNNEL_H | ||
30 | #define GNUNET_SERVICE_CADET_TUNNEL_H | ||
31 | |||
32 | #ifdef __cplusplus | ||
33 | extern "C" | ||
34 | { | ||
35 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
36 | } | ||
37 | #endif | ||
38 | #endif | ||
39 | |||
40 | #include "platform.h" | ||
41 | #include "gnunet_util_lib.h" | ||
42 | |||
43 | /** | ||
44 | * All the connectivity states a tunnel can be in. | ||
45 | */ | ||
46 | enum CadetTunnel3CState | ||
47 | { | ||
48 | /** | ||
49 | * Uninitialized status, should never appear in operation. | ||
50 | */ | ||
51 | CADET_TUNNEL3_NEW, | ||
52 | |||
53 | /** | ||
54 | * Path to the peer not known yet. | ||
55 | */ | ||
56 | CADET_TUNNEL3_SEARCHING, | ||
57 | |||
58 | /** | ||
59 | * Request sent, not yet answered. | ||
60 | */ | ||
61 | CADET_TUNNEL3_WAITING, | ||
62 | |||
63 | /** | ||
64 | * Peer connected and ready to accept data. | ||
65 | */ | ||
66 | CADET_TUNNEL3_READY, | ||
67 | |||
68 | /** | ||
69 | * Tunnel being shut down, don't try to keep it alive. | ||
70 | */ | ||
71 | CADET_TUNNEL3_SHUTDOWN | ||
72 | }; | ||
73 | |||
74 | |||
75 | /** | ||
76 | * All the encryption states a tunnel can be in. | ||
77 | */ | ||
78 | enum CadetTunnel3EState | ||
79 | { | ||
80 | /** | ||
81 | * Uninitialized status, should never appear in operation. | ||
82 | */ | ||
83 | CADET_TUNNEL3_KEY_UNINITIALIZED, | ||
84 | |||
85 | /** | ||
86 | * Ephemeral key sent, waiting for peer's key. | ||
87 | */ | ||
88 | CADET_TUNNEL3_KEY_SENT, | ||
89 | |||
90 | /** | ||
91 | * New ephemeral key and ping sent, waiting for pong. | ||
92 | * This means that we DO have the peer's ephemeral key, otherwise the | ||
93 | * state would be KEY_SENT. | ||
94 | */ | ||
95 | CADET_TUNNEL3_KEY_PING, | ||
96 | |||
97 | /** | ||
98 | * Handshake completed: session key available. | ||
99 | */ | ||
100 | CADET_TUNNEL3_KEY_OK, | ||
101 | }; | ||
102 | |||
103 | /** | ||
104 | * Struct containing all information regarding a given peer | ||
105 | */ | ||
106 | struct CadetTunnel3; | ||
107 | |||
108 | |||
109 | #include "gnunet-service-cadet_channel.h" | ||
110 | #include "gnunet-service-cadet_connection.h" | ||
111 | #include "gnunet-service-cadet_peer.h" | ||
112 | |||
113 | /** | ||
114 | * Handle for messages queued but not yet sent. | ||
115 | */ | ||
116 | struct CadetTunnel3Queue; | ||
117 | |||
118 | /** | ||
119 | * Callback called when a queued message is sent. | ||
120 | * | ||
121 | * @param cls Closure. | ||
122 | * @param t Tunnel this message was on. | ||
123 | * @param type Type of message sent. | ||
124 | * @param size Size of the message. | ||
125 | */ | ||
126 | typedef void (*GMT_sent) (void *cls, | ||
127 | struct CadetTunnel3 *t, | ||
128 | struct CadetTunnel3Queue *q, | ||
129 | uint16_t type, size_t size); | ||
130 | |||
131 | typedef void (*GMT_conn_iter) (void *cls, struct CadetConnection *c); | ||
132 | typedef void (*GMT_chan_iter) (void *cls, struct CadetChannel *ch); | ||
133 | |||
134 | |||
135 | /******************************************************************************/ | ||
136 | /******************************** API ***********************************/ | ||
137 | /******************************************************************************/ | ||
138 | |||
139 | /** | ||
140 | * Initialize tunnel subsystem. | ||
141 | * | ||
142 | * @param c Configuration handle. | ||
143 | * @param key ECC private key, to derive all other keys and do crypto. | ||
144 | */ | ||
145 | void | ||
146 | GMT_init (const struct GNUNET_CONFIGURATION_Handle *c, | ||
147 | const struct GNUNET_CRYPTO_EddsaPrivateKey *key); | ||
148 | |||
149 | /** | ||
150 | * Shut down the tunnel subsystem. | ||
151 | */ | ||
152 | void | ||
153 | GMT_shutdown (void); | ||
154 | |||
155 | /** | ||
156 | * Create a tunnel. | ||
157 | * | ||
158 | * @param destination Peer this tunnel is towards. | ||
159 | */ | ||
160 | struct CadetTunnel3 * | ||
161 | GMT_new (struct CadetPeer *destination); | ||
162 | |||
163 | /** | ||
164 | * Tunnel is empty: destroy it. | ||
165 | * | ||
166 | * Notifies all connections about the destruction. | ||
167 | * | ||
168 | * @param t Tunnel to destroy. | ||
169 | */ | ||
170 | void | ||
171 | GMT_destroy_empty (struct CadetTunnel3 *t); | ||
172 | |||
173 | /** | ||
174 | * Destroy tunnel if empty (no more channels). | ||
175 | * | ||
176 | * @param t Tunnel to destroy if empty. | ||
177 | */ | ||
178 | void | ||
179 | GMT_destroy_if_empty (struct CadetTunnel3 *t); | ||
180 | |||
181 | /** | ||
182 | * Destroy the tunnel. | ||
183 | * | ||
184 | * This function does not generate any warning traffic to clients or peers. | ||
185 | * | ||
186 | * Tasks: | ||
187 | * Cancel messages belonging to this tunnel queued to neighbors. | ||
188 | * Free any allocated resources linked to the tunnel. | ||
189 | * | ||
190 | * @param t The tunnel to destroy. | ||
191 | */ | ||
192 | void | ||
193 | GMT_destroy (struct CadetTunnel3 *t); | ||
194 | |||
195 | |||
196 | /** | ||
197 | * Change the tunnel's connection state. | ||
198 | * | ||
199 | * @param t Tunnel whose connection state to change. | ||
200 | * @param cstate New connection state. | ||
201 | */ | ||
202 | void | ||
203 | GMT_change_cstate (struct CadetTunnel3* t, enum CadetTunnel3CState cstate); | ||
204 | |||
205 | |||
206 | /** | ||
207 | * Change the tunnel encryption state. | ||
208 | * | ||
209 | * @param t Tunnel whose encryption state to change. | ||
210 | * @param state New encryption state. | ||
211 | */ | ||
212 | void | ||
213 | GMT_change_estate (struct CadetTunnel3* t, enum CadetTunnel3EState state); | ||
214 | |||
215 | /** | ||
216 | * Add a connection to a tunnel. | ||
217 | * | ||
218 | * @param t Tunnel. | ||
219 | * @param c Connection. | ||
220 | */ | ||
221 | void | ||
222 | GMT_add_connection (struct CadetTunnel3 *t, struct CadetConnection *c); | ||
223 | |||
224 | /** | ||
225 | * Mark a path as no longer valid for this tunnel: has been tried and failed. | ||
226 | * | ||
227 | * @param t Tunnel to update. | ||
228 | * @param path Invalid path to remove. Is destroyed after removal. | ||
229 | */ | ||
230 | void | ||
231 | GMT_remove_path (struct CadetTunnel3 *t, struct CadetPeerPath *path); | ||
232 | |||
233 | /** | ||
234 | * Remove a connection from a tunnel. | ||
235 | * | ||
236 | * @param t Tunnel. | ||
237 | * @param c Connection. | ||
238 | */ | ||
239 | void | ||
240 | GMT_remove_connection (struct CadetTunnel3 *t, struct CadetConnection *c); | ||
241 | |||
242 | /** | ||
243 | * Add a channel to a tunnel. | ||
244 | * | ||
245 | * @param t Tunnel. | ||
246 | * @param ch Channel. | ||
247 | */ | ||
248 | void | ||
249 | GMT_add_channel (struct CadetTunnel3 *t, struct CadetChannel *ch); | ||
250 | |||
251 | /** | ||
252 | * Remove a channel from a tunnel. | ||
253 | * | ||
254 | * @param t Tunnel. | ||
255 | * @param ch Channel. | ||
256 | */ | ||
257 | void | ||
258 | GMT_remove_channel (struct CadetTunnel3 *t, struct CadetChannel *ch); | ||
259 | |||
260 | /** | ||
261 | * Search for a channel by global ID. | ||
262 | * | ||
263 | * @param t Tunnel containing the channel. | ||
264 | * @param chid Public channel number. | ||
265 | * | ||
266 | * @return channel handler, NULL if doesn't exist | ||
267 | */ | ||
268 | struct CadetChannel * | ||
269 | GMT_get_channel (struct CadetTunnel3 *t, CADET_ChannelNumber chid); | ||
270 | |||
271 | /** | ||
272 | * Decrypt and demultiplex by message type. Call appropriate handler | ||
273 | * for a message | ||
274 | * towards a channel of a local tunnel. | ||
275 | * | ||
276 | * @param t Tunnel this message came on. | ||
277 | * @param msg Message header. | ||
278 | */ | ||
279 | void | ||
280 | GMT_handle_encrypted (struct CadetTunnel3 *t, | ||
281 | const struct GNUNET_CADET_Encrypted *msg); | ||
282 | |||
283 | /** | ||
284 | * Demultiplex an encapsulated KX message by message type. | ||
285 | * | ||
286 | * @param t Tunnel on which the message came. | ||
287 | * @param message KX message itself. | ||
288 | */ | ||
289 | void | ||
290 | GMT_handle_kx (struct CadetTunnel3 *t, | ||
291 | const struct GNUNET_MessageHeader *message); | ||
292 | |||
293 | /** | ||
294 | * @brief Use the given path for the tunnel. | ||
295 | * Update the next and prev hops (and RCs). | ||
296 | * (Re)start the path refresh in case the tunnel is locally owned. | ||
297 | * | ||
298 | * @param t Tunnel to update. | ||
299 | * @param p Path to use. | ||
300 | * | ||
301 | * @return Connection created. | ||
302 | */ | ||
303 | struct CadetConnection * | ||
304 | GMT_use_path (struct CadetTunnel3 *t, struct CadetPeerPath *p); | ||
305 | |||
306 | /** | ||
307 | * Count established (ready) connections of a tunnel. | ||
308 | * | ||
309 | * @param t Tunnel on which to count. | ||
310 | * | ||
311 | * @return Number of connections. | ||
312 | */ | ||
313 | unsigned int | ||
314 | GMT_count_connections (struct CadetTunnel3 *t); | ||
315 | |||
316 | /** | ||
317 | * Count channels of a tunnel. | ||
318 | * | ||
319 | * @param t Tunnel on which to count. | ||
320 | * | ||
321 | * @return Number of channels. | ||
322 | */ | ||
323 | unsigned int | ||
324 | GMT_count_channels (struct CadetTunnel3 *t); | ||
325 | |||
326 | /** | ||
327 | * Get the connectivity state of a tunnel. | ||
328 | * | ||
329 | * @param t Tunnel. | ||
330 | * | ||
331 | * @return Tunnel's connectivity state. | ||
332 | */ | ||
333 | enum CadetTunnel3CState | ||
334 | GMT_get_cstate (struct CadetTunnel3 *t); | ||
335 | |||
336 | /** | ||
337 | * Get the encryption state of a tunnel. | ||
338 | * | ||
339 | * @param t Tunnel. | ||
340 | * | ||
341 | * @return Tunnel's encryption state. | ||
342 | */ | ||
343 | enum CadetTunnel3EState | ||
344 | GMT_get_estate (struct CadetTunnel3 *t); | ||
345 | |||
346 | /** | ||
347 | * Get the maximum buffer space for a tunnel towards a local client. | ||
348 | * | ||
349 | * @param t Tunnel. | ||
350 | * | ||
351 | * @return Biggest buffer space offered by any channel in the tunnel. | ||
352 | */ | ||
353 | unsigned int | ||
354 | GMT_get_channels_buffer (struct CadetTunnel3 *t); | ||
355 | |||
356 | /** | ||
357 | * Get the total buffer space for a tunnel for P2P traffic. | ||
358 | * | ||
359 | * @param t Tunnel. | ||
360 | * | ||
361 | * @return Buffer space offered by all connections in the tunnel. | ||
362 | */ | ||
363 | unsigned int | ||
364 | GMT_get_connections_buffer (struct CadetTunnel3 *t); | ||
365 | |||
366 | /** | ||
367 | * Get the tunnel's destination. | ||
368 | * | ||
369 | * @param t Tunnel. | ||
370 | * | ||
371 | * @return ID of the destination peer. | ||
372 | */ | ||
373 | const struct GNUNET_PeerIdentity * | ||
374 | GMT_get_destination (struct CadetTunnel3 *t); | ||
375 | |||
376 | /** | ||
377 | * Get the tunnel's next free Channel ID. | ||
378 | * | ||
379 | * @param t Tunnel. | ||
380 | * | ||
381 | * @return ID of a channel free to use. | ||
382 | */ | ||
383 | CADET_ChannelNumber | ||
384 | GMT_get_next_chid (struct CadetTunnel3 *t); | ||
385 | |||
386 | /** | ||
387 | * Send ACK on one or more channels due to buffer in connections. | ||
388 | * | ||
389 | * @param t Channel which has some free buffer space. | ||
390 | */ | ||
391 | void | ||
392 | GMT_unchoke_channels (struct CadetTunnel3 *t); | ||
393 | |||
394 | /** | ||
395 | * Send ACK on one or more connections due to buffer space to the client. | ||
396 | * | ||
397 | * Iterates all connections of the tunnel and sends ACKs appropriately. | ||
398 | * | ||
399 | * @param t Tunnel which has some free buffer space. | ||
400 | */ | ||
401 | void | ||
402 | GMT_send_connection_acks (struct CadetTunnel3 *t); | ||
403 | |||
404 | /** | ||
405 | * Cancel a previously sent message while it's in the queue. | ||
406 | * | ||
407 | * ONLY can be called before the continuation given to the send function | ||
408 | * is called. Once the continuation is called, the message is no longer in the | ||
409 | * queue. | ||
410 | * | ||
411 | * @param q Handle to the queue. | ||
412 | */ | ||
413 | void | ||
414 | GMT_cancel (struct CadetTunnel3Queue *q); | ||
415 | |||
416 | /** | ||
417 | * Sends an already built message on a tunnel, encrypting it and | ||
418 | * choosing the best connection. | ||
419 | * | ||
420 | * @param message Message to send. Function modifies it. | ||
421 | * @param t Tunnel on which this message is transmitted. | ||
422 | * @param c Connection to use (autoselect if NULL). | ||
423 | * @param force Force the tunnel to take the message (buffer overfill). | ||
424 | * @param cont Continuation to call once message is really sent. | ||
425 | * @param cont_cls Closure for @c cont. | ||
426 | * | ||
427 | * @return Handle to cancel message. NULL if @c cont is NULL. | ||
428 | */ | ||
429 | struct CadetTunnel3Queue * | ||
430 | GMT_send_prebuilt_message (const struct GNUNET_MessageHeader *message, | ||
431 | struct CadetTunnel3 *t, struct CadetConnection *c, | ||
432 | int force, GMT_sent cont, void *cont_cls); | ||
433 | |||
434 | /** | ||
435 | * Is the tunnel directed towards the local peer? | ||
436 | * | ||
437 | * @param t Tunnel. | ||
438 | * | ||
439 | * @return #GNUNET_YES if it is loopback. | ||
440 | */ | ||
441 | int | ||
442 | GMT_is_loopback (const struct CadetTunnel3 *t); | ||
443 | |||
444 | /** | ||
445 | * Is the tunnel using this path already? | ||
446 | * | ||
447 | * @param t Tunnel. | ||
448 | * @param p Path. | ||
449 | * | ||
450 | * @return #GNUNET_YES a connection uses this path. | ||
451 | */ | ||
452 | int | ||
453 | GMT_is_path_used (const struct CadetTunnel3 *t, const struct CadetPeerPath *p); | ||
454 | |||
455 | /** | ||
456 | * Get a cost of a path for a tunnel considering existing connections. | ||
457 | * | ||
458 | * @param t Tunnel. | ||
459 | * @param path Candidate path. | ||
460 | * | ||
461 | * @return Cost of the path (path length + number of overlapping nodes) | ||
462 | */ | ||
463 | unsigned int | ||
464 | GMT_get_path_cost (const struct CadetTunnel3 *t, | ||
465 | const struct CadetPeerPath *path); | ||
466 | |||
467 | /** | ||
468 | * Get the static string for the peer this tunnel is directed. | ||
469 | * | ||
470 | * @param t Tunnel. | ||
471 | * | ||
472 | * @return Static string the destination peer's ID. | ||
473 | */ | ||
474 | const char * | ||
475 | GMT_2s (const struct CadetTunnel3 *t); | ||
476 | |||
477 | /** | ||
478 | * Log all possible info about the tunnel state. | ||
479 | * | ||
480 | * @param t Tunnel to debug. | ||
481 | */ | ||
482 | void | ||
483 | GMT_debug (const struct CadetTunnel3 *t); | ||
484 | |||
485 | /** | ||
486 | * Iterate all tunnels. | ||
487 | * | ||
488 | * @param iter Iterator. | ||
489 | * @param cls Closure for @c iter. | ||
490 | */ | ||
491 | void | ||
492 | GMT_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter, void *cls); | ||
493 | |||
494 | /** | ||
495 | * Count all tunnels. | ||
496 | * | ||
497 | * @return Number of tunnels to remote peers kept by this peer. | ||
498 | */ | ||
499 | unsigned int | ||
500 | GMT_count_all (void); | ||
501 | |||
502 | /** | ||
503 | * Iterate all connections of a tunnel. | ||
504 | * | ||
505 | * @param t Tunnel whose connections to iterate. | ||
506 | * @param iter Iterator. | ||
507 | * @param cls Closure for @c iter. | ||
508 | */ | ||
509 | void | ||
510 | GMT_iterate_connections (struct CadetTunnel3 *t, GMT_conn_iter iter, void *cls); | ||
511 | |||
512 | /** | ||
513 | * Iterate all channels of a tunnel. | ||
514 | * | ||
515 | * @param t Tunnel whose channels to iterate. | ||
516 | * @param iter Iterator. | ||
517 | * @param cls Closure for @c iter. | ||
518 | */ | ||
519 | void | ||
520 | GMT_iterate_channels (struct CadetTunnel3 *t, GMT_chan_iter iter, void *cls); | ||
521 | |||
522 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
523 | { | ||
524 | #endif | ||
525 | #ifdef __cplusplus | ||
526 | } | ||
527 | #endif | ||
528 | |||
529 | /* ifndef GNUNET_CADET_SERVICE_TUNNEL_H */ | ||
530 | #endif | ||
531 | /* end of gnunet-cadet-service_tunnel.h */ | ||