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