2 This file is part of GNUnet.
3 Copyright (C) 2001-2017 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @file cadet/gnunet-service-cadet_channel.h
23 * @brief GNUnet CADET service with encryption
24 * @author Bartlomiej Polot
25 * @author Christian Grothoff
27 #ifndef GNUNET_SERVICE_CADET_CHANNEL_H
28 #define GNUNET_SERVICE_CADET_CHANNEL_H
30 #include "gnunet-service-cadet.h"
31 #include "gnunet-service-cadet_peer.h"
32 #include "cadet_protocol.h"
36 * A channel is a bidirectional connection between two CADET
37 * clients. Communiation can be reliable, unreliable, in-order
38 * or out-of-order. One client is the "local" client, this
39 * one initiated the connection. The other client is the
40 * "incoming" client, this one listened on a port to accept
41 * the connection from the "local" client.
47 * Hash the @a port and @a initiator and @a listener to
48 * calculate the "challenge" @a h_port we send to the other
49 * peer on #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN.
51 * @param[out] h_port set to the hash of @a port, @a initiator and @a listener
52 * @param port cadet port, as seen by CADET clients
53 * @param listener peer that is listining on @a port
56 GCCH_hash_port (struct GNUNET_HashCode *h_port,
57 const struct GNUNET_HashCode *port,
58 const struct GNUNET_PeerIdentity *listener);
62 * Get the static string for identification of the channel.
66 * @return Static string with the channel IDs.
69 GCCH_2s (const struct CadetChannel *ch);
76 * @param level Debug level to use.
79 GCCH_debug (struct CadetChannel *ch,
80 enum GNUNET_ErrorType level);
84 * Get the channel's public ID.
88 * @return ID used to identify the channel with the remote peer.
90 struct GNUNET_CADET_ChannelTunnelNumber
91 GCCH_get_id (const struct CadetChannel *ch);
95 * Create a new channel.
97 * @param owner local client owning the channel
98 * @param owner_id local chid of this channel at the @a owner
99 * @param destination peer to which we should build the channel
100 * @param port desired port at @a destination
101 * @param options options for the channel
102 * @return handle to the new channel
104 struct CadetChannel *
105 GCCH_channel_local_new (struct CadetClient *owner,
106 struct GNUNET_CADET_ClientChannelNumber owner_id,
107 struct CadetPeer *destination,
108 const struct GNUNET_HashCode *port,
113 * A client is bound to the port that we have a channel
114 * open to. Send the acknowledgement for the connection
115 * request and establish the link with the client.
117 * @param ch open incoming channel
118 * @param c client listening on the respective @a port
119 * @param port port number @a c is listening on
122 GCCH_bind (struct CadetChannel *ch,
123 struct CadetClient *c,
124 const struct GNUNET_HashCode *port);
128 * Destroy locally created channel. Called by the
129 * local client, so no need to tell the client.
131 * @param ch channel to destroy
132 * @param c client that caused the destruction
133 * @param ccn client number of the client @a c
136 GCCH_channel_local_destroy (struct CadetChannel *ch,
137 struct CadetClient *c,
138 struct GNUNET_CADET_ClientChannelNumber ccn);
142 * Function called once and only once after a channel was bound
143 * to its tunnel via #GCT_add_channel() is ready for transmission.
144 * Note that this is only the case for channels that this peer
145 * initiates, as for incoming channels we assume that they are
146 * ready for transmission immediately upon receiving the open
147 * message. Used to bootstrap the #GCT_send() process.
149 * @param ch the channel for which the tunnel is now ready
152 GCCH_tunnel_up (struct CadetChannel *ch);
156 * Create a new channel based on a request coming in over the network.
158 * @param t tunnel to the remote peer
159 * @param chid identifier of this channel in the tunnel
160 * @param origin peer to who initiated the channel
161 * @param h_port hash of desired local port
162 * @param options options for the channel
163 * @return handle to the new channel
165 struct CadetChannel *
166 GCCH_channel_incoming_new (struct CadetTunnel *t,
167 struct GNUNET_CADET_ChannelTunnelNumber chid,
168 const struct GNUNET_HashCode *h_port,
173 * We got a #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN message again for
174 * this channel. If the binding was successful, (re)transmit the
175 * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
177 * @param ch channel that got the duplicate open
178 * @param cti identifier of the connection that delivered the message
181 GCCH_handle_duplicate_open (struct CadetChannel *ch,
182 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
187 * We got payload data for a channel. Pass it on to the client.
189 * @param ch channel that got data
190 * @param cti identifier of the connection that delivered the message
191 * @param msg message that was received
194 GCCH_handle_channel_plaintext_data (struct CadetChannel *ch,
195 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
196 const struct GNUNET_CADET_ChannelAppDataMessage *msg);
200 * We got an acknowledgement for payload data for a channel.
201 * Possibly resume transmissions.
203 * @param ch channel that got the ack
204 * @param cti identifier of the connection that delivered the message
205 * @param ack details about what was received
208 GCCH_handle_channel_plaintext_data_ack (struct CadetChannel *ch,
209 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
210 const struct GNUNET_CADET_ChannelDataAckMessage *ack);
214 * We got an acknowledgement for the creation of the channel
215 * (the port is open on the other side). Begin transmissions.
217 * @param ch channel to destroy
218 * @param cti identifier of the connection that delivered the message,
219 * NULL if the ACK was inferred because we got payload or are on loopback
220 * @param port port number (needed to verify receiver knows the port)
223 GCCH_handle_channel_open_ack (struct CadetChannel *ch,
224 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
225 const struct GNUNET_HashCode *port);
229 * Destroy channel, based on the other peer closing the
230 * connection. Also needs to remove this channel from
233 * FIXME: need to make it possible to defer destruction until we have
234 * received all messages up to the destroy, and right now the destroy
235 * message (and this API) fails to give is the information we need!
237 * FIXME: also need to know if the other peer got a destroy from
240 * @param ch channel to destroy
241 * @param cti identifier of the connection that delivered the message,
242 * NULL during shutdown
245 GCCH_handle_remote_destroy (struct CadetChannel *ch,
246 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
250 * Handle data given by a client.
252 * Check whether the client is allowed to send in this tunnel, save if
253 * channel is reliable and send an ACK to the client if there is still
254 * buffer space in the tunnel.
257 * @param sender_ccn ccn of the sender
258 * @param buf payload to transmit.
259 * @param buf_len number of bytes in @a buf
260 * @return #GNUNET_OK if everything goes well,
261 * #GNUNET_SYSERR in case of an error.
264 GCCH_handle_local_data (struct CadetChannel *ch,
265 struct GNUNET_CADET_ClientChannelNumber sender_ccn,
271 * Handle ACK from client on local channel.
273 * @param ch channel to destroy
274 * @param client_ccn ccn of the client sending the ack
277 GCCH_handle_local_ack (struct CadetChannel *ch,
278 struct GNUNET_CADET_ClientChannelNumber client_ccn);