src/cadet/gnunet-service-cadet_channel.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001-2017 GNUnet e.V.
   4
   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.
   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      Affero General Public License for more details.
  14
  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/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19 */
  20
  21 /**
  22  * @file cadet/gnunet-service-cadet_channel.h
  23  * @brief GNUnet CADET service with encryption
  24  * @author Bartlomiej Polot
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_SERVICE_CADET_CHANNEL_H
  28 #define GNUNET_SERVICE_CADET_CHANNEL_H
  29
  30 #include "gnunet-service-cadet.h"
  31 #include "gnunet-service-cadet_peer.h"
  32 #include "cadet_protocol.h"
  33
  34
  35 /**
  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.
  42  */
  43 struct CadetChannel;
  44
  45
  46 /**
  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.
  50  *
  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
  54  */
  55 void
  56 GCCH_hash_port (struct GNUNET_HashCode *h_port,
  57                 const struct GNUNET_HashCode *port,
  58                 const struct GNUNET_PeerIdentity *listener);
  59
  60
  61 /**
  62  * Get the static string for identification of the channel.
  63  *
  64  * @param ch Channel.
  65  *
  66  * @return Static string with the channel IDs.
  67  */
  68 const char *
  69 GCCH_2s (const struct CadetChannel *ch);
  70
  71
  72 /**
  73  * Log channel info.
  74  *
  75  * @param ch Channel.
  76  * @param level Debug level to use.
  77  */
  78 void
  79 GCCH_debug (struct CadetChannel *ch,
  80             enum GNUNET_ErrorType level);
  81
  82
  83 /**
  84  * Get the channel's public ID.
  85  *
  86  * @param ch Channel.
  87  *
  88  * @return ID used to identify the channel with the remote peer.
  89  */
  90 struct GNUNET_CADET_ChannelTunnelNumber
  91 GCCH_get_id (const struct CadetChannel *ch);
  92
  93
  94 /**
  95  * Create a new channel.
  96  *
  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
 103  */
 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,
 109                         uint32_t options);
 110
 111
 112 /**
 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.
 116  *
 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
 120  */
 121 void
 122 GCCH_bind (struct CadetChannel *ch,
 123            struct CadetClient *c,
 124            const struct GNUNET_HashCode *port);
 125
 126
 127 /**
 128  * Destroy locally created channel.  Called by the
 129  * local client, so no need to tell the client.
 130  *
 131  * @param ch channel to destroy
 132  * @param c client that caused the destruction
 133  * @param ccn client number of the client @a c
 134  */
 135 void
 136 GCCH_channel_local_destroy (struct CadetChannel *ch,
 137                             struct CadetClient *c,
 138                             struct GNUNET_CADET_ClientChannelNumber ccn);
 139
 140
 141 /**
 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.
 148  *
 149  * @param ch the channel for which the tunnel is now ready
 150  */
 151 void
 152 GCCH_tunnel_up (struct CadetChannel *ch);
 153
 154
 155 /**
 156  * Create a new channel based on a request coming in over the network.
 157  *
 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
 164  */
 165 struct CadetChannel *
 166 GCCH_channel_incoming_new (struct CadetTunnel *t,
 167                            struct GNUNET_CADET_ChannelTunnelNumber chid,
 168                            const struct GNUNET_HashCode *h_port,
 169                            uint32_t options);
 170
 171
 172 /**
 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.
 176  *
 177  * @param ch channel that got the duplicate open
 178  * @param cti identifier of the connection that delivered the message
 179  */
 180 void
 181 GCCH_handle_duplicate_open (struct CadetChannel *ch,
 182                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 183
 184
 185
 186 /**
 187  * We got payload data for a channel.  Pass it on to the client.
 188  *
 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
 192  */
 193 void
 194 GCCH_handle_channel_plaintext_data (struct CadetChannel *ch,
 195                                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 196                                     const struct GNUNET_CADET_ChannelAppDataMessage *msg);
 197
 198
 199 /**
 200  * We got an acknowledgement for payload data for a channel.
 201  * Possibly resume transmissions.
 202  *
 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
 206  */
 207 void
 208 GCCH_handle_channel_plaintext_data_ack (struct CadetChannel *ch,
 209                                         const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 210                                         const struct GNUNET_CADET_ChannelDataAckMessage *ack);
 211
 212
 213 /**
 214  * We got an acknowledgement for the creation of the channel
 215  * (the port is open on the other side). Begin transmissions.
 216  *
 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)
 221  */
 222 void
 223 GCCH_handle_channel_open_ack (struct CadetChannel *ch,
 224                               const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 225                               const struct GNUNET_HashCode *port);
 226
 227
 228 /**
 229  * Destroy channel, based on the other peer closing the
 230  * connection.  Also needs to remove this channel from
 231  * the tunnel.
 232  *
 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!
 236  *
 237  * FIXME: also need to know if the other peer got a destroy from
 238  * us before!
 239  *
 240  * @param ch channel to destroy
 241  * @param cti identifier of the connection that delivered the message,
 242  *            NULL during shutdown
 243  */
 244 void
 245 GCCH_handle_remote_destroy (struct CadetChannel *ch,
 246                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 247
 248
 249 /**
 250  * Handle data given by a client.
 251  *
 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.
 255  *
 256  * @param ch Channel.
 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.
 262  */
 263 int
 264 GCCH_handle_local_data (struct CadetChannel *ch,
 265                         struct GNUNET_CADET_ClientChannelNumber sender_ccn,
 266                         const char *buf,
 267                         size_t buf_len);
 268
 269
 270 /**
 271  * Handle ACK from client on local channel.
 272  *
 273  * @param ch channel to destroy
 274  * @param client_ccn ccn of the client sending the ack
 275  */
 276 void
 277 GCCH_handle_local_ack (struct CadetChannel *ch,
 278                        struct GNUNET_CADET_ClientChannelNumber client_ccn);
 279
 280 #endif