src/rps/gnunet-service-rps_sampler_elem.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C)
   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 rps/gnunet-service-rps_sampler_elem.h
  18  * @brief sampler element implementation
  19  * @author Julius Bünger
  20  */
  21
  22 #ifndef RPS_SAMPLER_ELEM_H
  23 #define RPS_SAMPLER_ELEM_H
  24 #include <inttypes.h>
  25
  26
  27 /***********************************************************************
  28  * WARNING: This section needs to be reviewed regarding the use of
  29  * functions providing (pseudo)randomness!
  30  ***********************************************************************/
  31
  32 /**
  33  * Used to indicate whether a sampler element is empty.
  34  */
  35 enum RPS_SamplerEmpty
  36 {
  37   NOT_EMPTY = 0x0,
  38   EMPTY = 0x1
  39 };
  40
  41 /**
  42  * A sampler element sampling one PeerID at a time.
  43  */
  44 struct RPS_SamplerElement
  45 {
  46   /**
  47    * Min-wise linear permutation used by this sampler.
  48    *
  49    * This is an key later used by a hmac.
  50    */
  51   struct GNUNET_CRYPTO_AuthKey auth_key;
  52
  53   /**
  54    * The PeerID this sampler currently samples.
  55    */
  56   struct GNUNET_PeerIdentity peer_id;
  57
  58   /**
  59    * The according hash value of this PeerID.
  60    */
  61   struct GNUNET_HashCode peer_id_hash;
  62
  63
  64   /**
  65    * Time of last request.
  66    */
  67   struct GNUNET_TIME_Absolute last_client_request;
  68
  69   /**
  70    * Flag that indicates that we are not holding a valid PeerID right now.
  71    */
  72   enum RPS_SamplerEmpty is_empty;
  73
  74   /**
  75    * 'Birth'
  76    */
  77   struct GNUNET_TIME_Absolute birth;
  78
  79   /**
  80    * How many times a PeerID was put in this sampler.
  81    */
  82   uint32_t num_peers;
  83
  84   /**
  85    * How many times this sampler changed the peer_id.
  86    */
  87   uint32_t num_change;
  88
  89   /**
  90    * The file name this sampler element should log to
  91    */
  92   char *file_name;
  93 };
  94
  95
  96 /**
  97  * Reinitialise a previously initialised sampler element.
  98  *
  99  * @param sampler pointer to the memory that keeps the value.
 100  */
 101 void
 102 RPS_sampler_elem_reinit (struct RPS_SamplerElement *sampler_el);
 103
 104
 105 /**
 106  * Create a sampler element and initialise it.
 107  *
 108  * In this implementation this means choosing an auth_key for later use in
 109  * a hmac at random.
 110  *
 111  * @return a newly created RPS_SamplerElement which currently holds no id.
 112  */
 113 struct RPS_SamplerElement *
 114 RPS_sampler_elem_create (void);
 115
 116
 117 /**
 118  * Destroy a sampler element.
 119  *
 120  * @param sampler_elem the element to destroy
 121  */
 122 void
 123 RPS_sampler_elem_destroy (struct RPS_SamplerElement *sampler_elem);
 124
 125
 126 /**
 127  * Input an PeerID into the given sampler element.
 128  *
 129  * @param sampler the sampler the @a s_elem belongs to.
 130  *                Needed to know the
 131  */
 132 void
 133 RPS_sampler_elem_next (struct RPS_SamplerElement *s_elem,
 134                        const struct GNUNET_PeerIdentity *new_ID);
 135
 136 /**
 137  * Initialise the min-wise independent function of the given sampler element.
 138  *
 139  * @param s_elem the sampler element
 140  * @param auth_key the key to use
 141  */
 142 void
 143 RPS_sampler_elem_set (struct RPS_SamplerElement *s_elem,
 144                       struct GNUNET_CRYPTO_AuthKey auth_key);
 145
 146
 147 #endif /* RPS_SAMPLER_ELEM_H */
 148 /* end of gnunet-service-rps.c */