3 This file is part of GNUnet.
4 Copyright (C) 2001-2017 GNUnet e.V.
6 GNUnet is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published
8 by the Free Software Foundation; either version 3, or (at your
9 option) any later version.
11 GNUnet is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNUnet; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
23 * @file cadet/gnunet-service-cadet-new_tunnels.h
24 * @brief Information we track per tunnel.
25 * @author Bartlomiej Polot
26 * @author Christian Grothoff
28 #ifndef GNUNET_SERVICE_CADET_TUNNELS_H
29 #define GNUNET_SERVICE_CADET_TUNNELS_H
31 #include "gnunet-service-cadet-new.h"
32 #include "cadet_protocol.h"
36 * How many connections would we like to have per tunnel?
38 #define DESIRED_CONNECTIONS_PER_TUNNEL 3
42 * All the connectivity states a tunnel can be in.
44 enum CadetTunnelCState
47 * Uninitialized status, should never appear in operation.
52 * No path to the peer known yet.
54 CADET_TUNNEL_SEARCHING,
57 * Request sent, not yet answered.
62 * Peer connected and ready to accept data.
67 * Tunnel being shut down, don't try to keep it alive.
75 * All the encryption states a tunnel can be in.
77 enum CadetTunnelEState
80 * Uninitialized status, should never appear in operation.
82 CADET_TUNNEL_KEY_UNINITIALIZED,
85 * Ephemeral key sent, waiting for peer's key.
87 CADET_TUNNEL_KEY_SENT,
90 * In OTR: 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. We DO NOT have a valid session key (either no
94 * previous key or previous key expired).
97 * In Axolotl: Key sent and received but no deciphered traffic yet.
99 * This means that we can send traffic (otherwise we would never complete
100 * the handshake), but we don't have complete confirmation. Since the first
101 * traffic MUST be a complete channel creation 3-way handshake, no payload
102 * will be sent before confirmation.
104 CADET_TUNNEL_KEY_PING,
107 * Handshake completed: session key available.
112 * New ephemeral key and ping sent, waiting for pong. Unlike KEY_PING,
113 * we still have a valid session key and therefore we *can* still send
114 * traffic on the tunnel.
116 CADET_TUNNEL_KEY_REKEY
121 * Number uniquely identifying a channel within a tunnel.
123 struct GCT_ChannelTunnelNumber
125 uint32_t channel_in_tunnel GNUNET_PACKED;
130 * Get the static string for the peer this tunnel is directed.
134 * @return Static string the destination peer's ID.
137 GCT_2s (const struct CadetTunnel *t);
141 * Create a tunnel to @a destionation. Must only be called
142 * from within #GCP_get_tunnel().
144 * @param destination where to create the tunnel to
145 * @return new tunnel to @a destination
148 GCT_create_tunnel (struct CadetPeer *destination);
152 * Return the peer to which this tunnel goes.
155 * @return the destination of the tunnel
158 GCT_get_destination (struct CadetTunnel *t);
162 * Consider using the path @a p for the tunnel @a t.
163 * The tunnel destination is at offset @a off in path @a p.
165 * @param cls our tunnel
166 * @param path a path to our destination
167 * @param off offset of the destination on path @a path
170 GCT_consider_path (struct CadetTunnel *t,
171 struct CadetPeerPath *p,
176 * Add a channel to a tunnel.
180 * @return unique number identifying @a ch within @a t
182 struct GCT_ChannelTunnelNumber
183 GCT_add_channel (struct CadetTunnel *t,
184 struct CadetChannel *ch);
188 * Remove a channel from a tunnel.
192 * @param gid unique number identifying @a ch within @a t
195 GCT_remove_channel (struct CadetTunnel *t,
196 struct CadetChannel *ch,
197 struct GCT_ChannelTunnelNumber gid);
201 * Sends an already built message on a tunnel, encrypting it and
202 * choosing the best connection if not provided.
204 * @param message Message to send. Function modifies it.
205 * @param t Tunnel on which this message is transmitted.
206 * @param cont Continuation to call once message is really sent.
207 * @param cont_cls Closure for @c cont.
208 * @return Handle to cancel message. NULL if @c cont is NULL.
210 struct CadetTunnelQueueEntry *
211 GCT_send (struct CadetTunnel *t,
212 const struct GNUNET_MessageHeader *message,
213 GNUNET_SCHEDULER_TaskCallback cont,
218 * Cancel a previously sent message while it's in the queue.
220 * ONLY can be called before the continuation given to the send
221 * function is called. Once the continuation is called, the message is
222 * no longer in the queue!
224 * @param q Handle to the queue entry to cancel.
227 GCT_send_cancel (struct CadetTunnelQueueEntry *q);
231 * Return the number of channels using a tunnel.
233 * @param t tunnel to count obtain the number of channels for
234 * @return number of channels using the tunnel
237 GCT_count_channels (struct CadetTunnel *t);
241 * Return the number of connections available for a tunnel.
243 * @param t tunnel to count obtain the number of connections for
244 * @return number of connections available for the tunnel
247 GCT_count_any_connections (struct CadetTunnel *t);
251 * Iterator over connections.
254 * @param c one of the connections
257 (*GCT_ConnectionIterator) (void *cls,
258 struct CadetConnection *c);
262 * Iterate over all connections of a tunnel.
264 * @param t Tunnel whose connections to iterate.
265 * @param iter Iterator.
266 * @param iter_cls Closure for @c iter.
269 GCT_iterate_connections (struct CadetTunnel *t,
270 GCT_ConnectionIterator iter,
275 * Iterator over channels.
278 * @param ch one of the channels
281 (*GCT_ChannelIterator) (void *cls,
282 struct CadetChannel *ch);
286 * Iterate over all channels of a tunnel.
288 * @param t Tunnel whose channels to iterate.
289 * @param iter Iterator.
290 * @param iter_cls Closure for @c iter.
293 GCT_iterate_channels (struct CadetTunnel *t,
294 GCT_ChannelIterator iter,
299 * Get the connectivity state of a tunnel.
303 * @return Tunnel's connectivity state.
305 enum CadetTunnelCState
306 GCT_get_cstate (struct CadetTunnel *t);
310 * Get the encryption state of a tunnel.
314 * @return Tunnel's encryption state.
316 enum CadetTunnelEState
317 GCT_get_estate (struct CadetTunnel *t);
323 * @param ct connection/tunnel combo that received encrypted message
324 * @param msg the key exchange message
327 GCT_handle_kx (struct CadetTConnection *ct,
328 const struct GNUNET_CADET_KX *msg);
332 * Handle encrypted message.
334 * @param ct connection/tunnel combo that received encrypted message
335 * @param msg the encrypted message to decrypt
338 GCT_handle_encrypted (struct CadetTConnection *ct,
339 const struct GNUNET_CADET_Encrypted *msg);
343 * Log all possible info about the tunnel state.
345 * @param t Tunnel to debug.
346 * @param level Debug level to use.
349 GCT_debug (const struct CadetTunnel *t,
350 enum GNUNET_ErrorType level);