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
  16 /**
  17  * @file cadet/gnunet-service-cadet_channel.h
  18  * @brief GNUnet CADET service with encryption
  19  * @author Bartlomiej Polot
  20  * @author Christian Grothoff
  21  */
  22 #ifndef GNUNET_SERVICE_CADET_CHANNEL_H
  23 #define GNUNET_SERVICE_CADET_CHANNEL_H
  24
  25 #include "gnunet-service-cadet.h"
  26 #include "gnunet-service-cadet_peer.h"
  27 #include "cadet_protocol.h"
  28
  29
  30 /**
  31  * A channel is a bidirectional connection between two CADET
  32  * clients.  Communiation can be reliable, unreliable, in-order
  33  * or out-of-order.  One client is the "local" client, this
  34  * one initiated the connection.   The other client is the
  35  * "incoming" client, this one listened on a port to accept
  36  * the connection from the "local" client.
  37  */
  38 struct CadetChannel;
  39
  40
  41 /**
  42  * Hash the @a port and @a initiator and @a listener to
  43  * calculate the "challenge" @a h_port we send to the other
  44  * peer on #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN.
  45  *
  46  * @param[out] h_port set to the hash of @a port, @a initiator and @a listener
  47  * @param port cadet port, as seen by CADET clients
  48  * @param listener peer that is listining on @a port
  49  */
  50 void
  51 GCCH_hash_port (struct GNUNET_HashCode *h_port,
  52                 const struct GNUNET_HashCode *port,
  53                 const struct GNUNET_PeerIdentity *listener);
  54
  55
  56 /**
  57  * Get the static string for identification of the channel.
  58  *
  59  * @param ch Channel.
  60  *
  61  * @return Static string with the channel IDs.
  62  */
  63 const char *
  64 GCCH_2s (const struct CadetChannel *ch);
  65
  66
  67 /**
  68  * Log channel info.
  69  *
  70  * @param ch Channel.
  71  * @param level Debug level to use.
  72  */
  73 void
  74 GCCH_debug (struct CadetChannel *ch,
  75             enum GNUNET_ErrorType level);
  76
  77
  78 /**
  79  * Get the channel's public ID.
  80  *
  81  * @param ch Channel.
  82  *
  83  * @return ID used to identify the channel with the remote peer.
  84  */
  85 struct GNUNET_CADET_ChannelTunnelNumber
  86 GCCH_get_id (const struct CadetChannel *ch);
  87
  88
  89 /**
  90  * Create a new channel.
  91  *
  92  * @param owner local client owning the channel
  93  * @param owner_id local chid of this channel at the @a owner
  94  * @param destination peer to which we should build the channel
  95  * @param port desired port at @a destination
  96  * @param options options for the channel
  97  * @return handle to the new channel
  98  */
  99 struct CadetChannel *
 100 GCCH_channel_local_new (struct CadetClient *owner,
 101                         struct GNUNET_CADET_ClientChannelNumber owner_id,
 102                         struct CadetPeer *destination,
 103                         const struct GNUNET_HashCode *port,
 104                         uint32_t options);
 105
 106
 107 /**
 108  * A client is bound to the port that we have a channel
 109  * open to.  Send the acknowledgement for the connection
 110  * request and establish the link with the client.
 111  *
 112  * @param ch open incoming channel
 113  * @param c client listening on the respective @a port
 114  * @param port port number @a c is listening on
 115  */
 116 void
 117 GCCH_bind (struct CadetChannel *ch,
 118            struct CadetClient *c,
 119            const struct GNUNET_HashCode *port);
 120
 121
 122 /**
 123  * Destroy locally created channel.  Called by the
 124  * local client, so no need to tell the client.
 125  *
 126  * @param ch channel to destroy
 127  * @param c client that caused the destruction
 128  * @param ccn client number of the client @a c
 129  */
 130 void
 131 GCCH_channel_local_destroy (struct CadetChannel *ch,
 132                             struct CadetClient *c,
 133                             struct GNUNET_CADET_ClientChannelNumber ccn);
 134
 135
 136 /**
 137  * Function called once and only once after a channel was bound
 138  * to its tunnel via #GCT_add_channel() is ready for transmission.
 139  * Note that this is only the case for channels that this peer
 140  * initiates, as for incoming channels we assume that they are
 141  * ready for transmission immediately upon receiving the open
 142  * message.  Used to bootstrap the #GCT_send() process.
 143  *
 144  * @param ch the channel for which the tunnel is now ready
 145  */
 146 void
 147 GCCH_tunnel_up (struct CadetChannel *ch);
 148
 149
 150 /**
 151  * Create a new channel based on a request coming in over the network.
 152  *
 153  * @param t tunnel to the remote peer
 154  * @param chid identifier of this channel in the tunnel
 155  * @param origin peer to who initiated the channel
 156  * @param h_port hash of desired local port
 157  * @param options options for the channel
 158  * @return handle to the new channel
 159  */
 160 struct CadetChannel *
 161 GCCH_channel_incoming_new (struct CadetTunnel *t,
 162                            struct GNUNET_CADET_ChannelTunnelNumber chid,
 163                            const struct GNUNET_HashCode *h_port,
 164                            uint32_t options);
 165
 166
 167 /**
 168  * We got a #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN message again for
 169  * this channel.  If the binding was successful, (re)transmit the
 170  * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
 171  *
 172  * @param ch channel that got the duplicate open
 173  * @param cti identifier of the connection that delivered the message
 174  */
 175 void
 176 GCCH_handle_duplicate_open (struct CadetChannel *ch,
 177                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 178
 179
 180
 181 /**
 182  * We got payload data for a channel.  Pass it on to the client.
 183  *
 184  * @param ch channel that got data
 185  * @param cti identifier of the connection that delivered the message
 186  * @param msg message that was received
 187  */
 188 void
 189 GCCH_handle_channel_plaintext_data (struct CadetChannel *ch,
 190                                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 191                                     const struct GNUNET_CADET_ChannelAppDataMessage *msg);
 192
 193
 194 /**
 195  * We got an acknowledgement for payload data for a channel.
 196  * Possibly resume transmissions.
 197  *
 198  * @param ch channel that got the ack
 199  * @param cti identifier of the connection that delivered the message
 200  * @param ack details about what was received
 201  */
 202 void
 203 GCCH_handle_channel_plaintext_data_ack (struct CadetChannel *ch,
 204                                         const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 205                                         const struct GNUNET_CADET_ChannelDataAckMessage *ack);
 206
 207
 208 /**
 209  * We got an acknowledgement for the creation of the channel
 210  * (the port is open on the other side). Begin transmissions.
 211  *
 212  * @param ch channel to destroy
 213  * @param cti identifier of the connection that delivered the message,
 214  *        NULL if the ACK was inferred because we got payload or are on loopback
 215  * @param port port number (needed to verify receiver knows the port)
 216  */
 217 void
 218 GCCH_handle_channel_open_ack (struct CadetChannel *ch,
 219                               const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 220                               const struct GNUNET_HashCode *port);
 221
 222
 223 /**
 224  * Destroy channel, based on the other peer closing the
 225  * connection.  Also needs to remove this channel from
 226  * the tunnel.
 227  *
 228  * FIXME: need to make it possible to defer destruction until we have
 229  * received all messages up to the destroy, and right now the destroy
 230  * message (and this API) fails to give is the information we need!
 231  *
 232  * FIXME: also need to know if the other peer got a destroy from
 233  * us before!
 234  *
 235  * @param ch channel to destroy
 236  * @param cti identifier of the connection that delivered the message,
 237  *            NULL during shutdown
 238  */
 239 void
 240 GCCH_handle_remote_destroy (struct CadetChannel *ch,
 241                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 242
 243
 244 /**
 245  * Handle data given by a client.
 246  *
 247  * Check whether the client is allowed to send in this tunnel, save if
 248  * channel is reliable and send an ACK to the client if there is still
 249  * buffer space in the tunnel.
 250  *
 251  * @param ch Channel.
 252  * @param sender_ccn ccn of the sender
 253  * @param buf payload to transmit.
 254  * @param buf_len number of bytes in @a buf
 255  * @return #GNUNET_OK if everything goes well,
 256  *         #GNUNET_SYSERR in case of an error.
 257  */
 258 int
 259 GCCH_handle_local_data (struct CadetChannel *ch,
 260                         struct GNUNET_CADET_ClientChannelNumber sender_ccn,
 261                         const char *buf,
 262                         size_t buf_len);
 263
 264
 265 /**
 266  * Handle ACK from client on local channel.
 267  *
 268  * @param ch channel to destroy
 269  * @param client_ccn ccn of the client sending the ack
 270  */
 271 void
 272 GCCH_handle_local_ack (struct CadetChannel *ch,
 273                        struct GNUNET_CADET_ClientChannelNumber client_ccn);
 274
 275 #endif