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