src/core/gnunet-service-core_kx.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010, 2011 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file core/gnunet-service-core_kx.h
  23  * @brief code for managing the key exchange (SET_KEY, PING, PONG) with other peers
  24  * @author Christian Grothoff
  25  */
  26 #ifndef GNUNET_SERVICE_CORE_KX_H
  27 #define GNUNET_SERVICE_CORE_KX_H
  28
  29 #include "gnunet_util_lib.h"
  30
  31
  32 /**
  33  * State machine for our P2P encryption handshake.  Everyone starts in
  34  * "DOWN", if we receive the other peer's key (other peer initiated)
  35  * we start in state RECEIVED (since we will immediately send our
  36  * own); otherwise we start in SENT.  If we get back a PONG from
  37  * within either state, we move up to CONFIRMED (the PONG will always
  38  * be sent back encrypted with the key we sent to the other peer).
  39  */
  40 enum KxStateMachine
  41 {
  42   /**
  43    * No handshake yet.
  44    */
  45   KX_STATE_DOWN,
  46
  47   /**
  48    * We've sent our session key.
  49    */
  50   KX_STATE_KEY_SENT,
  51
  52   /**
  53    * We've received the other peers session key.
  54    */
  55   KX_STATE_KEY_RECEIVED,
  56
  57   /**
  58    * The other peer has confirmed our session key with a message
  59    * encrypted with his session key (which we got).  Key exchange
  60    * is done.
  61    */
  62   KX_STATE_UP
  63 };
  64
  65
  66 /**
  67  * Information about the status of a key exchange with another peer.
  68  */
  69 struct GSC_KeyExchangeInfo
  70 {
  71   /**
  72    * Identity of the peer.
  73    */
  74   struct GNUNET_PeerIdentity peer;
  75
  76   /**
  77    * SetKeyMessage to transmit (initialized the first
  78    * time our status goes past 'KX_STATE_KEY_SENT').
  79    */
  80   struct SetKeyMessage skm;
  81
  82   /**
  83    * PING message we transmit to the other peer.
  84    */
  85   struct PingMessage ping;
  86
  87   /**
  88    * SetKeyMessage we received and did not process yet.
  89    */
  90   struct SetKeyMessage *skm_received;
  91
  92   /**
  93    * PING message we received from the other peer and
  94    * did not process yet (or NULL).
  95    */
  96   struct PingMessage *ping_received;
  97
  98   /**
  99    * PONG message we received from the other peer and
 100    * did not process yet (or NULL).
 101    */
 102   struct PongMessage *pong_received;
 103
 104   /**
 105    * Non-NULL if we are currently looking up HELLOs for this peer.
 106    * for this peer.
 107    */
 108   struct GNUNET_PEERINFO_IteratorContext *pitr;
 109
 110   /**
 111    * Public key of the neighbour, NULL if we don't have it yet.
 112    */
 113   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key;
 114
 115   /**
 116    * We received a PONG message before we got the "public_key"
 117    * (or the SET_KEY).  We keep it here until we have a key
 118    * to decrypt it.  NULL if no PONG is pending.
 119    */
 120   struct PongMessage *pending_pong;
 121
 122   /**
 123    * Key we use to encrypt our messages for the other peer
 124    * (initialized by us when we do the handshake).
 125    */
 126   struct GNUNET_CRYPTO_AesSessionKey encrypt_key;
 127
 128   /**
 129    * Key we use to decrypt messages from the other peer
 130    * (given to us by the other peer during the handshake).
 131    */
 132   struct GNUNET_CRYPTO_AesSessionKey decrypt_key;
 133
 134   /**
 135    * At what time did we generate our encryption key?
 136    */
 137   struct GNUNET_TIME_Absolute encrypt_key_created;
 138
 139   /**
 140    * At what time did the other peer generate the decryption key?
 141    */
 142   struct GNUNET_TIME_Absolute decrypt_key_created;
 143
 144   /**
 145    * When should the session time out (if there are no PONGs)?
 146    */
 147   struct GNUNET_TIME_Absolute timeout;
 148
 149   /**
 150    * At what frequency are we currently re-trying SET_KEY messages?
 151    */
 152   struct GNUNET_TIME_Relative set_key_retry_frequency;
 153
 154   /**
 155    * ID of task used for re-trying SET_KEY and PING message.
 156    */
 157   GNUNET_SCHEDULER_TaskIdentifier retry_set_key_task;
 158
 159   /**
 160    * ID of task used for sending keep-alive pings.
 161    */
 162   GNUNET_SCHEDULER_TaskIdentifier keep_alive_task;
 163
 164   /**
 165    * What was our PING challenge number (for this peer)?
 166    */
 167   uint32_t ping_challenge;
 168
 169   /**
 170    * What is our connection status?
 171    */
 172   enum KxStateMachine status;
 173
 174 };
 175
 176
 177 /**
 178  * We received a SET_KEY message.  Validate and update
 179  * our key material and status.
 180  *
 181  * @param kx key exchange status for the corresponding peer
 182  * @param msg the set key message we received
 183  */
 184 void
 185 GSC_KX_handle_set_key (struct GSC_KeyExchangeInfo *kx,
 186                        const struct GNUNET_MessageHandler *msg);
 187
 188
 189 /**
 190  * We received a PING message.  Validate and transmit
 191  * a PONG message.
 192  *
 193  * @param kx key exchange status for the corresponding peer
 194  * @param msg the encrypted PING message itself
 195  */
 196 void
 197 GSC_KX_handle_ping (struct GSC_KeyExchangeInfo *kx,
 198                     const struct GNUNET_MessageHeader *msg);
 199
 200
 201 /**
 202  * We received a PONG message.  Validate and update our status.
 203  *
 204  * @param kx key exchange status for the corresponding peer
 205  * @param msg the encrypted PONG message itself
 206  */
 207 void
 208 GSC_KX_handle_pong (struct GSC_KeyExchangeInfo *kx,
 209                     const struct GNUNET_MessageHeader *msg);
 210
 211
 212 /**
 213  * Encrypt and transmit a message with the given payload.
 214  *
 215  * @param kx key exchange context
 216  * @param bw_in bandwidth limit to transmit to the other peer;
 217  *              the other peer shall not send us more than the
 218  *              given rate
 219  * @param payload payload of the message
 220  * @param payload_size number of bytes in 'payload'
 221  */
 222 void
 223 GSC_KX_encrypt_and_transmit (struct GSC_KeyExchangeInfo *kx,
 224                              struct GNUNET_BANDWIDTH_Value32NBO bw_in,
 225                              const void *payload,
 226                              size_t payload_size);
 227
 228
 229 /**
 230  * We received an encrypted message.  Decrypt, validate and
 231  * pass on to the appropriate clients.
 232  *
 233  * @param kx key exchange information context
 234  * @param msg encrypted message
 235  * @param atsi performance data
 236  * @param atsi_count number of entries in ats (excluding 0-termination)
 237  */
 238 void
 239 GSC_KX_handle_encrypted_message (struct GSC_KeyExchangeInfo *kx,
 240                                  const struct GNUNET_MessageHeader *msg,
 241                                  const struct GNUNET_TRANSPORT_ATS_Information *atsi,
 242                                  uint32_t atsi_count);
 243
 244
 245 /**
 246  * Start the key exchange with the given peer.
 247  *
 248  * @param pid identity of the peer to do a key exchange with
 249  * @return key exchange information context
 250  */
 251 struct GSC_KeyExchangeInfo *
 252 GSC_KX_start (const struct GNUNET_PeerIdentity *pid);
 253
 254
 255 /**
 256  * Stop key exchange with the given peer.  Clean up key material.
 257  *
 258  * @param kx key exchange to stop
 259  */
 260 void
 261 GSC_KX_stop (struct GSC_KeyExchangeInfo *kx);
 262
 263
 264 /**
 265  * Initialize KX subsystem.
 266  *
 267  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 268  */
 269 int
 270 GSC_KX_init (void);
 271
 272
 273 /**
 274  * Shutdown KX subsystem.
 275  */
 276 void
 277 GSC_KX_done (void);
 278
 279 #endif
 280 /* end of gnunet-service-core_kx.h */