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 encryption states a tunnel can be in.
44 enum CadetTunnelEState
47 * Uninitialized status, we need to send KX. We will stay
48 * in this state until the first connection is up.
50 CADET_TUNNEL_KEY_UNINITIALIZED,
53 * Ephemeral key sent, waiting for peer's key.
55 CADET_TUNNEL_KEY_SENT,
58 * Key received and we sent ours back, but we got no traffic yet.
59 * We will not yet send traffic, as this might have been a replay.
60 * The other (initiating) peer should send a CHANNEL_OPEN next
63 CADET_TUNNEL_KEY_PING,
66 * Handshake completed: session key available.
71 * New ephemeral key and ping sent, waiting for pong. Unlike KEY_PING,
72 * we still have a valid session key and therefore we *can* still send
73 * traffic on the tunnel.
75 CADET_TUNNEL_KEY_REKEY
80 * Get the static string for the peer this tunnel is directed.
84 * @return Static string the destination peer's ID.
87 GCT_2s (const struct CadetTunnel *t);
91 * Create a tunnel to @a destionation. Must only be called
92 * from within #GCP_get_tunnel().
94 * @param destination where to create the tunnel to
95 * @return new tunnel to @a destination
98 GCT_create_tunnel (struct CadetPeer *destination);
102 * Destroys the tunnel @a t now, without delay. Used during shutdown.
104 * @param t tunnel to destroy
107 GCT_destroy_tunnel_now (struct CadetTunnel *t);
111 * Add a @a connection to the @a tunnel.
114 * @param cid connection identifer to use for the connection
115 * @param path path to use for the connection
116 * @return #GNUNET_OK on success,
117 * #GNUNET_SYSERR on failure (duplicate connection)
120 GCT_add_inbound_connection (struct CadetTunnel *t,
121 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
122 struct CadetPeerPath *path);
126 * We lost a connection, remove it from our list and clean up
127 * the connection object itself.
129 * @param ct binding of connection to tunnel of the connection that was lost.
132 GCT_connection_lost (struct CadetTConnection *ct);
136 * Return the peer to which this tunnel goes.
139 * @return the destination of the tunnel
142 GCT_get_destination (struct CadetTunnel *t);
146 * Consider using the path @a p for the tunnel @a t.
147 * The tunnel destination is at offset @a off in path @a p.
149 * @param cls our tunnel
150 * @param path a path to our destination
151 * @param off offset of the destination on path @a path
154 GCT_consider_path (struct CadetTunnel *t,
155 struct CadetPeerPath *p,
160 * Add a channel to a tunnel.
164 * @return unique number identifying @a ch within @a t
166 struct GNUNET_CADET_ChannelTunnelNumber
167 GCT_add_channel (struct CadetTunnel *t,
168 struct CadetChannel *ch);
172 * Remove a channel from a tunnel.
176 * @param ctn unique number identifying @a ch within @a t
179 GCT_remove_channel (struct CadetTunnel *t,
180 struct CadetChannel *ch,
181 struct GNUNET_CADET_ChannelTunnelNumber ctn);
185 * Send a DESTROY message via the tunnel.
187 * @param t the tunnel to transmit over
188 * @param ctn ID of the channel to destroy
191 GCT_send_channel_destroy (struct CadetTunnel *t,
192 struct GNUNET_CADET_ChannelTunnelNumber ctn);
196 * Sends an already built message on a tunnel, encrypting it and
197 * choosing the best connection if not provided.
199 * @param message Message to send. Function modifies it.
200 * @param t Tunnel on which this message is transmitted.
201 * @param cont Continuation to call once message is really sent.
202 * @param cont_cls Closure for @c cont.
203 * @return Handle to cancel message. NULL if @c cont is NULL.
205 struct CadetTunnelQueueEntry *
206 GCT_send (struct CadetTunnel *t,
207 const struct GNUNET_MessageHeader *message,
208 GNUNET_SCHEDULER_TaskCallback cont,
213 * Cancel a previously sent message while it's in the queue.
215 * ONLY can be called before the continuation given to the send
216 * function is called. Once the continuation is called, the message is
217 * no longer in the queue!
219 * @param q Handle to the queue entry to cancel.
222 GCT_send_cancel (struct CadetTunnelQueueEntry *q);
226 * Return the number of channels using a tunnel.
228 * @param t tunnel to count obtain the number of channels for
229 * @return number of channels using the tunnel
232 GCT_count_channels (struct CadetTunnel *t);
236 * Return the number of connections available for a tunnel.
238 * @param t tunnel to count obtain the number of connections for
239 * @return number of connections available for the tunnel
242 GCT_count_any_connections (struct CadetTunnel *t);
246 * Iterator over connections.
249 * @param c one of the connections
252 (*GCT_ConnectionIterator) (void *cls,
253 struct CadetConnection *c);
257 * Iterate over all connections of a tunnel.
259 * @param t Tunnel whose connections to iterate.
260 * @param iter Iterator.
261 * @param iter_cls Closure for @c iter.
264 GCT_iterate_connections (struct CadetTunnel *t,
265 GCT_ConnectionIterator iter,
270 * Iterator over channels.
273 * @param ch one of the channels
276 (*GCT_ChannelIterator) (void *cls,
277 struct CadetChannel *ch);
281 * Iterate over all channels of a tunnel.
283 * @param t Tunnel whose channels to iterate.
284 * @param iter Iterator.
285 * @param iter_cls Closure for @c iter.
288 GCT_iterate_channels (struct CadetTunnel *t,
289 GCT_ChannelIterator iter,
294 * Get the encryption state of a tunnel.
298 * @return Tunnel's encryption state.
300 enum CadetTunnelEState
301 GCT_get_estate (struct CadetTunnel *t);
307 * @param ct connection/tunnel combo that received encrypted message
308 * @param msg the key exchange message
311 GCT_handle_kx (struct CadetTConnection *ct,
312 const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
316 * Handle encrypted message.
318 * @param ct connection/tunnel combo that received encrypted message
319 * @param msg the encrypted message to decrypt
322 GCT_handle_encrypted (struct CadetTConnection *ct,
323 const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
327 * Log all possible info about the tunnel state.
329 * @param t Tunnel to debug.
330 * @param level Debug level to use.
333 GCT_debug (const struct CadetTunnel *t,
334 enum GNUNET_ErrorType level);