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  * Information about the status of a key exchange with another peer.
  34  */
  35 struct GSC_KeyExchangeInfo
  36 {
  37
  38   /**
  39    * SetKeyMessage to transmit, NULL if we are not currently trying
  40    * to send one.
  41    */
  42   struct SetKeyMessage *skm;
  43
  44   /**
  45    * Non-NULL if we are currently looking up HELLOs for this peer.
  46    * for this peer.
  47    */
  48   struct GNUNET_PEERINFO_IteratorContext *pitr;
  49
  50   /**
  51    * Public key of the neighbour, NULL if we don't have it yet.
  52    */
  53   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *public_key;
  54
  55   /**
  56    * We received a PING message before we got the "public_key"
  57    * (or the SET_KEY).  We keep it here until we have a key
  58    * to decrypt it.  NULL if no PING is pending.
  59    */
  60   struct PingMessage *pending_ping;
  61
  62   /**
  63    * We received a PONG message before we got the "public_key"
  64    * (or the SET_KEY).  We keep it here until we have a key
  65    * to decrypt it.  NULL if no PONG is pending.
  66    */
  67   struct PongMessage *pending_pong;
  68
  69   /**
  70    * Key we use to encrypt our messages for the other peer
  71    * (initialized by us when we do the handshake).
  72    */
  73   struct GNUNET_CRYPTO_AesSessionKey encrypt_key;
  74
  75   /**
  76    * Key we use to decrypt messages from the other peer
  77    * (given to us by the other peer during the handshake).
  78    */
  79   struct GNUNET_CRYPTO_AesSessionKey decrypt_key;
  80
  81   /**
  82    * At what time did we generate our encryption key?
  83    */
  84   struct GNUNET_TIME_Absolute encrypt_key_created;
  85
  86   /**
  87    * At what time did the other peer generate the decryption key?
  88    */
  89   struct GNUNET_TIME_Absolute decrypt_key_created;
  90
  91   /**
  92    * At what frequency are we currently re-trying SET_KEY messages?
  93    */
  94   struct GNUNET_TIME_Relative set_key_retry_frequency;
  95
  96   /**
  97    * ID of task used for re-trying SET_KEY and PING message.
  98    */
  99   GNUNET_SCHEDULER_TaskIdentifier retry_set_key_task;
 100
 101   /**
 102    * What was our PING challenge number (for this peer)?
 103    */
 104   uint32_t ping_challenge;
 105
 106   /**
 107    * What is our connection status?
 108    */
 109   enum PeerStateMachine status;
 110
 111 };
 112
 113
 114 /**
 115  * We received a SET_KEY message.  Validate and update
 116  * our key material and status.
 117  *
 118  * @param kx key exchange status for the corresponding peer
 119  * @param msg the set key message we received
 120  * @param ats performance data
 121  * @param ats_count number of entries in ats (excluding 0-termination)
 122  */
 123 void
 124 GSC_KX_handle_set_key (struct GSC_KeyExchangeInfo *n,
 125                        const struct GNUNET_MessageHandler *msg,
 126                        const struct GNUNET_TRANSPORT_ATS_Information *ats,
 127                        uint32_t ats_count);
 128
 129
 130 /**
 131  * We received a PING message.  Validate and transmit
 132  * a PONG message.
 133  *
 134  * @param kx key exchange status for the corresponding peer
 135  * @param msg the encrypted PING message itself
 136  * @param ats performance data
 137  * @param ats_count number of entries in ats (excluding 0-termination)
 138  */
 139 void
 140 GSC_KX_handle_ping (struct GSC_KeyExchangeInfo *kx,
 141                     const struct GNUNET_MessageHeader *msg,
 142                     const struct GNUNET_TRANSPORT_ATS_Information *ats,
 143                     uint32_t ats_count);
 144
 145
 146 /**
 147  * We received a PONG message.  Validate and update our status.
 148  *
 149  * @param kx key exchange status for the corresponding peer
 150  * @param msg the encrypted PONG message itself
 151  * @param ats performance data
 152  * @param ats_count number of entries in ats (excluding 0-termination)
 153  */
 154 void
 155 GSC_KX_handle_pong (struct GSC_KeyExchangeInfo *kx,
 156                     const struct GNUNET_MessageHeader *msg,
 157                     const struct GNUNET_TRANSPORT_ATS_Information *ats,
 158                     uint32_t ats_count);
 159
 160
 161 /**
 162  * Encrypt and transmit a message with the given payload.
 163  *
 164  * @param kx key exchange context
 165  * @param payload payload of the message
 166  * @param payload_size number of bytes in 'payload'
 167  */
 168 void
 169 GSC_KX_encrypt_and_transmit (struct GSC_KeyExchangeInfo *kx,
 170                              const void *payload,
 171                              size_t payload_size);
 172
 173
 174 /**
 175  * We received an encrypted message.  Decrypt, validate and
 176  * pass on to the appropriate clients.
 177  *
 178  * @param kx key exchange information context
 179  * @param msg encrypted message
 180  * @param ats performance data
 181  * @param ats_count number of entries in ats (excluding 0-termination)
 182  */
 183 void
 184 GSC_KX_handle_encrypted_message (struct GSC_KeyExchangeInfo *kx,
 185                                  const struct GNUNET_MessageHeader *msg,
 186                                  const struct GNUNET_TRANSPORT_ATS_Information *ats,
 187                                  uint32_t ats_count);
 188
 189
 190 /**
 191  * Start the key exchange with the given peer.
 192  *
 193  * @param pid identity of the peer to do a key exchange with
 194  * @return key exchange information context
 195  */
 196 struct GSC_KeyExchangeInfo *
 197 GSC_KX_start (const struct GNUNET_PeerIdentity *pid);
 198
 199
 200 /**
 201  * Stop key exchange with the given peer.  Clean up key material.
 202  *
 203  * @param kx key exchange to stop
 204  */
 205 void
 206 GSC_KX_stop (struct GSC_KeyExchangeInfo *kx);
 207
 208
 209 /**
 210  * Initialize KX subsystem.
 211  *
 212  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
 213  */
 214 int
 215 GSC_KX_init (void);
 216
 217
 218 /**
 219  * Shutdown KX subsystem.
 220  */
 221 void
 222 GSC_KX_done (void);
 223
 224 #endif
 225 /* end of gnunet-service-core_kx.h */