src/block/block.c

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010, 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 block/block.c
  21  * @brief library for data block manipulation
  22  * @author Christian Grothoff
  23  */
  24 #include "platform.h"
  25 #include "gnunet_util_lib.h"
  26 #include "gnunet_constants.h"
  27 #include "gnunet_signatures.h"
  28 #include "gnunet_block_lib.h"
  29 #include "gnunet_block_plugin.h"
  30
  31
  32 /**
  33  * Handle for a plugin.
  34  */
  35 struct Plugin
  36 {
  37   /**
  38    * Name of the shared library.
  39    */
  40   char *library_name;
  41
  42   /**
  43    * Plugin API.
  44    */
  45   struct GNUNET_BLOCK_PluginFunctions *api;
  46 };
  47
  48
  49 /**
  50  * Handle to an initialized block library.
  51  */
  52 struct GNUNET_BLOCK_Context
  53 {
  54   /**
  55    * Array of our plugins.
  56    */
  57   struct Plugin **plugins;
  58
  59   /**
  60    * Size of the 'plugins' array.
  61    */
  62   unsigned int num_plugins;
  63
  64   /**
  65    * Our configuration.
  66    */
  67   const struct GNUNET_CONFIGURATION_Handle *cfg;
  68 };
  69
  70
  71 /**
  72  * Mingle hash with the mingle_number to produce different bits.
  73  *
  74  * @param in original hash code
  75  * @param mingle_number number for hash permutation
  76  * @param hc where to store the result.
  77  */
  78 void
  79 GNUNET_BLOCK_mingle_hash (const struct GNUNET_HashCode *in,
  80                           uint32_t mingle_number,
  81                           struct GNUNET_HashCode *hc)
  82 {
  83   struct GNUNET_HashCode m;
  84
  85   GNUNET_CRYPTO_hash (&mingle_number,
  86                       sizeof (uint32_t),
  87                       &m);
  88   GNUNET_CRYPTO_hash_xor (&m,
  89                           in,
  90                           hc);
  91 }
  92
  93
  94 /**
  95  * Add a plugin to the list managed by the block library.
  96  *
  97  * @param cls the block context
  98  * @param library_name name of the plugin
  99  * @param lib_ret the plugin API
 100  */
 101 static void
 102 add_plugin (void *cls,
 103             const char *library_name,
 104             void *lib_ret)
 105 {
 106   struct GNUNET_BLOCK_Context *ctx = cls;
 107   struct GNUNET_BLOCK_PluginFunctions *api = lib_ret;
 108   struct Plugin *plugin;
 109
 110   GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
 111               "Loading block plugin `%s'\n",
 112               library_name);
 113   plugin = GNUNET_new (struct Plugin);
 114   plugin->api = api;
 115   plugin->library_name = GNUNET_strdup (library_name);
 116   GNUNET_array_append (ctx->plugins,
 117                        ctx->num_plugins,
 118                        plugin);
 119 }
 120
 121
 122
 123 /**
 124  * Create a block context.  Loads the block plugins.
 125  *
 126  * @param cfg configuration to use
 127  * @return NULL on error
 128  */
 129 struct GNUNET_BLOCK_Context *
 130 GNUNET_BLOCK_context_create (const struct GNUNET_CONFIGURATION_Handle *cfg)
 131 {
 132   struct GNUNET_BLOCK_Context *ctx;
 133
 134   ctx = GNUNET_new (struct GNUNET_BLOCK_Context);
 135   ctx->cfg = cfg;
 136   GNUNET_PLUGIN_load_all ("libgnunet_plugin_block_",
 137                           (void *) cfg,
 138                           &add_plugin,
 139                           ctx);
 140   return ctx;
 141 }
 142
 143
 144 /**
 145  * Destroy the block context.
 146  *
 147  * @param ctx context to destroy
 148  */
 149 void
 150 GNUNET_BLOCK_context_destroy (struct GNUNET_BLOCK_Context *ctx)
 151 {
 152   struct Plugin *plugin;
 153
 154   for (unsigned int i = 0; i < ctx->num_plugins; i++)
 155   {
 156     plugin = ctx->plugins[i];
 157     GNUNET_break (NULL ==
 158                   GNUNET_PLUGIN_unload (plugin->library_name,
 159                                         plugin->api));
 160     GNUNET_free (plugin->library_name);
 161     GNUNET_free (plugin);
 162   }
 163   GNUNET_free (ctx->plugins);
 164   GNUNET_free (ctx);
 165 }
 166
 167
 168 /**
 169  * Serialize state of a block group.
 170  *
 171  * @param bg group to serialize
 172  * @param[out] nonce set to the nonce of the @a bg
 173  * @param[out] raw_data set to the serialized state
 174  * @param[out] raw_data_size set to the number of bytes in @a raw_data
 175  * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not
 176  *         supported, #GNUNET_SYSERR on error
 177  */
 178 int
 179 GNUNET_BLOCK_group_serialize (struct GNUNET_BLOCK_Group *bg,
 180                               uint32_t *nonce,
 181                               void **raw_data,
 182                               size_t *raw_data_size)
 183 {
 184   *nonce = 0;
 185   *raw_data = NULL;
 186   *raw_data_size = 0;
 187   if (NULL == bg)
 188     return GNUNET_NO;
 189   if (NULL == bg->serialize_cb)
 190     return GNUNET_NO;
 191   return bg->serialize_cb (bg,
 192                            nonce,
 193                            raw_data,
 194                            raw_data_size);
 195 }
 196
 197
 198 /**
 199  * Destroy resources used by a block group.
 200  *
 201  * @param bg group to destroy, NULL is allowed
 202  */
 203 void
 204 GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg)
 205 {
 206   if (NULL == bg)
 207     return;
 208   bg->destroy_cb (bg);
 209 }
 210
 211
 212 /**
 213  * Try merging two block groups.  Afterwards, @a bg1 should remain
 214  * valid and contain the rules from both @a bg1 and @bg2, and
 215  * @a bg2 should be destroyed (as part of this call).  The latter
 216  * should happen even if merging is not supported.
 217  *
 218  * @param[in,out] bg1 first group to merge, is updated
 219  * @param bg2 second group to merge, is destroyed
 220  * @return #GNUNET_OK on success,
 221  *         #GNUNET_NO if merge failed due to different nonce
 222  *         #GNUNET_SYSERR if merging is not supported
 223  */
 224 int
 225 GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1,
 226                           struct GNUNET_BLOCK_Group *bg2)
 227 {
 228   int ret;
 229
 230   if (NULL == bg2)
 231     return GNUNET_OK;
 232   if (NULL == bg1)
 233   {
 234     bg2->destroy_cb (bg2);
 235     return GNUNET_OK;
 236   }
 237   if (NULL == bg1->merge_cb)
 238     return GNUNET_SYSERR;
 239   GNUNET_assert (bg1->merge_cb == bg1->merge_cb);
 240   ret = bg1->merge_cb (bg1,
 241                        bg2);
 242   bg2->destroy_cb (bg2);
 243   return ret;
 244 }
 245
 246
 247 /**
 248  * Find a plugin for the given type.
 249  *
 250  * @param ctx context to search
 251  * @param type type to look for
 252  * @return NULL if no matching plugin exists
 253  */
 254 static struct GNUNET_BLOCK_PluginFunctions *
 255 find_plugin (struct GNUNET_BLOCK_Context *ctx,
 256              enum GNUNET_BLOCK_Type type)
 257 {
 258   struct Plugin *plugin;
 259   unsigned int j;
 260
 261   for (unsigned i = 0; i < ctx->num_plugins; i++)
 262   {
 263     plugin = ctx->plugins[i];
 264     j = 0;
 265     while (0 != (plugin->api->types[j]))
 266     {
 267       if (type == plugin->api->types[j])
 268         return plugin->api;
 269       j++;
 270     }
 271   }
 272   return NULL;
 273 }
 274
 275
 276 /**
 277  * Create a new block group.
 278  *
 279  * @param ctx block context in which the block group is created
 280  * @param type type of the block for which we are creating the group
 281  * @param nonce random value used to seed the group creation
 282  * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh
 283  * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh
 284  * @return block group handle, NULL if block groups are not supported
 285  *         by this @a type of block (this is not an error)
 286  */
 287 struct GNUNET_BLOCK_Group *
 288 GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx,
 289                            enum GNUNET_BLOCK_Type type,
 290                            uint32_t nonce,
 291                            const void *raw_data,
 292                            size_t raw_data_size,
 293                            ...)
 294 {
 295   struct GNUNET_BLOCK_PluginFunctions *plugin;
 296   struct GNUNET_BLOCK_Group *bg;
 297   va_list ap;
 298
 299   plugin = find_plugin (ctx,
 300                         type);
 301   if (NULL == plugin)
 302     return NULL;
 303   if (NULL == plugin->create_group)
 304     return NULL;
 305   va_start (ap,
 306             raw_data_size);
 307   bg = plugin->create_group (plugin->cls,
 308                              type,
 309                              nonce,
 310                              raw_data,
 311                              raw_data_size,
 312                              ap);
 313   va_end (ap);
 314   return bg;
 315 }
 316
 317
 318 /**
 319  * Function called to validate a reply or a request.  For
 320  * request evaluation, simply pass "NULL" for the reply_block.
 321  * Note that it is assumed that the reply has already been
 322  * matched to the key (and signatures checked) as it would
 323  * be done with the "get_key" function.
 324  *
 325  * @param ctx block contxt
 326  * @param type block type
 327  * @param block block group to use
 328  * @param eo control flags
 329  * @param query original query (hash)
 330  * @param xquery extended query data (can be NULL, depending on type)
 331  * @param xquery_size number of bytes in @a xquery
 332  * @param reply_block response to validate
 333  * @param reply_block_size number of bytes in @a reply_block
 334  * @return characterization of result
 335  */
 336 enum GNUNET_BLOCK_EvaluationResult
 337 GNUNET_BLOCK_evaluate (struct GNUNET_BLOCK_Context *ctx,
 338                        enum GNUNET_BLOCK_Type type,
 339                        struct GNUNET_BLOCK_Group *group,
 340                        enum GNUNET_BLOCK_EvaluationOptions eo,
 341                        const struct GNUNET_HashCode *query,
 342                        const void *xquery,
 343                        size_t xquery_size,
 344                        const void *reply_block,
 345                        size_t reply_block_size)
 346 {
 347   struct GNUNET_BLOCK_PluginFunctions *plugin = find_plugin (ctx,
 348                                                              type);
 349
 350   if (NULL == plugin)
 351     return GNUNET_BLOCK_EVALUATION_TYPE_NOT_SUPPORTED;
 352   return plugin->evaluate (plugin->cls,
 353                            ctx,
 354                            type,
 355                            group,
 356                            eo,
 357                            query,
 358                            xquery,
 359                            xquery_size,
 360                            reply_block,
 361                            reply_block_size);
 362 }
 363
 364
 365 /**
 366  * Function called to obtain the key for a block.
 367  *
 368  * @param ctx block context
 369  * @param type block type
 370  * @param block block to get the key for
 371  * @param block_size number of bytes in @a block
 372  * @param key set to the key (query) for the given block
 373  * @return #GNUNET_OK on success, #GNUNET_SYSERR if type not supported
 374  *         (or if extracting a key from a block of this type does not work)
 375  */
 376 int
 377 GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx,
 378                       enum GNUNET_BLOCK_Type type,
 379                       const void *block,
 380                       size_t block_size,
 381                       struct GNUNET_HashCode *key)
 382 {
 383   struct GNUNET_BLOCK_PluginFunctions *plugin = find_plugin (ctx,
 384                                                              type);
 385
 386   if (plugin == NULL)
 387     return GNUNET_BLOCK_EVALUATION_TYPE_NOT_SUPPORTED;
 388   return plugin->get_key (plugin->cls,
 389                           type,
 390                           block,
 391                           block_size,
 392                           key);
 393 }
 394
 395
 396 /**
 397  * Update block group to filter out the given results.  Note that the
 398  * use of a hash for seen results implies that the caller magically
 399  * knows how the specific block engine hashes for filtering
 400  * duplicates, so this API may not always apply.
 401  *
 402  * @param bf_mutator mutation value to use
 403  * @param seen_results results already seen
 404  * @param seen_results_count number of entries in @a seen_results
 405  * @return #GNUNET_SYSERR if not supported, #GNUNET_OK on success
 406  */
 407 int
 408 GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg,
 409                              const struct GNUNET_HashCode *seen_results,
 410                              unsigned int seen_results_count)
 411 {
 412   if (NULL == bg)
 413     return GNUNET_OK;
 414   if (NULL == bg->mark_seen_cb)
 415     return GNUNET_SYSERR;
 416   bg->mark_seen_cb (bg,
 417                     seen_results,
 418                     seen_results_count);
 419   return GNUNET_OK;
 420 }
 421
 422
 423 /* end of block.c */