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   unsigned int i;
 155   struct Plugin *plugin;
 156
 157   for (i = 0; i < ctx->num_plugins; i++)
 158   {
 159     plugin = ctx->plugins[i];
 160     GNUNET_break (NULL ==
 161                   GNUNET_PLUGIN_unload (plugin->library_name,
 162                                         plugin->api));
 163     GNUNET_free (plugin->library_name);
 164     GNUNET_free (plugin);
 165   }
 166   GNUNET_free (ctx->plugins);
 167   GNUNET_free (ctx);
 168 }
 169
 170
 171 /**
 172  * Serialize state of a block group.
 173  *
 174  * @param bg group to serialize
 175  * @param[out] nonce set to the nonce of the @a bg
 176  * @param[out] raw_data set to the serialized state
 177  * @param[out] raw_data_size set to the number of bytes in @a raw_data
 178  * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not
 179  *         supported, #GNUNET_SYSERR on error
 180  */
 181 int
 182 GNUNET_BLOCK_group_serialize (struct GNUNET_BLOCK_Group *bg,
 183                               uint32_t *nonce,
 184                               void **raw_data,
 185                               size_t *raw_data_size)
 186 {
 187   *nonce = 0;
 188   *raw_data = NULL;
 189   *raw_data_size = 0;
 190   if (NULL == bg)
 191     return GNUNET_NO;
 192   if (NULL == bg->serialize_cb)
 193     return GNUNET_NO;
 194   return bg->serialize_cb (bg,
 195                            nonce,
 196                            raw_data,
 197                            raw_data_size);
 198 }
 199
 200
 201 /**
 202  * Destroy resources used by a block group.
 203  *
 204  * @param bg group to destroy, NULL is allowed
 205  */
 206 void
 207 GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg)
 208 {
 209   if (NULL == bg)
 210     return;
 211   bg->destroy_cb (bg);
 212 }
 213
 214
 215 /**
 216  * Try merging two block groups.  Afterwards, @a bg1 should remain
 217  * valid and contain the rules from both @a bg1 and @bg2, and
 218  * @a bg2 should be destroyed (as part of this call).  The latter
 219  * should happen even if merging is not supported.
 220  *
 221  * @param[in,out] bg1 first group to merge, is updated
 222  * @param bg2 second group to merge, is destroyed
 223  * @return #GNUNET_OK on success,
 224  *         #GNUNET_NO if merge failed due to different nonce
 225  *         #GNUNET_SYSERR if merging is not supported
 226  */
 227 int
 228 GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1,
 229                           struct GNUNET_BLOCK_Group *bg2)
 230 {
 231   int ret;
 232
 233   if (NULL == bg2)
 234     return GNUNET_OK;
 235   if (NULL == bg1)
 236   {
 237     bg2->destroy_cb (bg2);
 238     return GNUNET_OK;
 239   }
 240   if (NULL == bg1->merge_cb)
 241     return GNUNET_SYSERR;
 242   GNUNET_assert (bg1->merge_cb == bg1->merge_cb);
 243   ret = bg1->merge_cb (bg1,
 244                        bg2);
 245   bg2->destroy_cb (bg2);
 246   return ret;
 247 }
 248
 249
 250 /**
 251  * Find a plugin for the given type.
 252  *
 253  * @param ctx context to search
 254  * @param type type to look for
 255  * @return NULL if no matching plugin exists
 256  */
 257 static struct GNUNET_BLOCK_PluginFunctions *
 258 find_plugin (struct GNUNET_BLOCK_Context *ctx,
 259              enum GNUNET_BLOCK_Type type)
 260 {
 261   struct Plugin *plugin;
 262   unsigned int j;
 263
 264   for (unsigned i = 0; i < ctx->num_plugins; i++)
 265   {
 266     plugin = ctx->plugins[i];
 267     j = 0;
 268     while (0 != (plugin->api->types[j]))
 269     {
 270       if (type == plugin->api->types[j])
 271         return plugin->api;
 272       j++;
 273     }
 274   }
 275   return NULL;
 276 }
 277
 278
 279 /**
 280  * Create a new block group.
 281  *
 282  * @param ctx block context in which the block group is created
 283  * @param type type of the block for which we are creating the group
 284  * @param nonce random value used to seed the group creation
 285  * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh
 286  * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh
 287  * @return block group handle, NULL if block groups are not supported
 288  *         by this @a type of block (this is not an error)
 289  */
 290 struct GNUNET_BLOCK_Group *
 291 GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx,
 292                            enum GNUNET_BLOCK_Type type,
 293                            uint32_t nonce,
 294                            const void *raw_data,
 295                            size_t raw_data_size,
 296                            ...)
 297 {
 298   struct GNUNET_BLOCK_PluginFunctions *plugin;
 299   struct GNUNET_BLOCK_Group *bg;
 300   va_list ap;
 301
 302   plugin = find_plugin (ctx,
 303                         type);
 304   if (NULL == plugin->create_group)
 305     return NULL;
 306   va_start (ap,
 307             raw_data_size);
 308   bg = plugin->create_group (plugin->cls,
 309                              type,
 310                              nonce,
 311                              raw_data,
 312                              raw_data_size,
 313                              ap);
 314   va_end (ap);
 315   return bg;
 316 }
 317
 318
 319 /**
 320  * Function called to validate a reply or a request.  For
 321  * request evaluation, simply pass "NULL" for the reply_block.
 322  * Note that it is assumed that the reply has already been
 323  * matched to the key (and signatures checked) as it would
 324  * be done with the "get_key" function.
 325  *
 326  * @param ctx block contxt
 327  * @param type block type
 328  * @param block block group to use
 329  * @param eo control flags
 330  * @param query original query (hash)
 331  * @param xquery extended query data (can be NULL, depending on type)
 332  * @param xquery_size number of bytes in @a xquery
 333  * @param reply_block response to validate
 334  * @param reply_block_size number of bytes in @a reply_block
 335  * @return characterization of result
 336  */
 337 enum GNUNET_BLOCK_EvaluationResult
 338 GNUNET_BLOCK_evaluate (struct GNUNET_BLOCK_Context *ctx,
 339                        enum GNUNET_BLOCK_Type type,
 340                        struct GNUNET_BLOCK_Group *group,
 341                        enum GNUNET_BLOCK_EvaluationOptions eo,
 342                        const struct GNUNET_HashCode *query,
 343                        const void *xquery,
 344                        size_t xquery_size,
 345                        const void *reply_block,
 346                        size_t reply_block_size)
 347 {
 348   struct GNUNET_BLOCK_PluginFunctions *plugin = find_plugin (ctx,
 349                                                              type);
 350
 351   if (NULL == plugin)
 352     return GNUNET_BLOCK_EVALUATION_TYPE_NOT_SUPPORTED;
 353   return plugin->evaluate (plugin->cls,
 354                            ctx,
 355                            type,
 356                            group,
 357                            eo,
 358                            query,
 359                            xquery,
 360                            xquery_size,
 361                            reply_block,
 362                            reply_block_size);
 363 }
 364
 365
 366 /**
 367  * Function called to obtain the key for a block.
 368  *
 369  * @param ctx block context
 370  * @param type block type
 371  * @param block block to get the key for
 372  * @param block_size number of bytes in @a block
 373  * @param key set to the key (query) for the given block
 374  * @return #GNUNET_OK on success, #GNUNET_SYSERR if type not supported
 375  *         (or if extracting a key from a block of this type does not work)
 376  */
 377 int
 378 GNUNET_BLOCK_get_key (struct GNUNET_BLOCK_Context *ctx,
 379                       enum GNUNET_BLOCK_Type type,
 380                       const void *block,
 381                       size_t block_size,
 382                       struct GNUNET_HashCode *key)
 383 {
 384   struct GNUNET_BLOCK_PluginFunctions *plugin = find_plugin (ctx,
 385                                                              type);
 386
 387   if (plugin == NULL)
 388     return GNUNET_BLOCK_EVALUATION_TYPE_NOT_SUPPORTED;
 389   return plugin->get_key (plugin->cls,
 390                           type,
 391                           block,
 392                           block_size,
 393                           key);
 394 }
 395
 396
 397 /**
 398  * Update block group to filter out the given results.  Note that the
 399  * use of a hash for seen results implies that the caller magically
 400  * knows how the specific block engine hashes for filtering
 401  * duplicates, so this API may not always apply.
 402  *
 403  * @param bf_mutator mutation value to use
 404  * @param seen_results results already seen
 405  * @param seen_results_count number of entries in @a seen_results
 406  * @return #GNUNET_SYSERR if not supported, #GNUNET_OK on success
 407  */
 408 int
 409 GNUNET_BLOCK_group_set_seen (struct GNUNET_BLOCK_Group *bg,
 410                              const struct GNUNET_HashCode *seen_results,
 411                              unsigned int seen_results_count)
 412 {
 413   if (NULL == bg)
 414     return GNUNET_OK;
 415   if (NULL == bg->mark_seen_cb)
 416     return GNUNET_SYSERR;
 417   bg->mark_seen_cb (bg,
 418                     seen_results,
 419                     seen_results_count);
 420   return GNUNET_OK;
 421 }
 422
 423
 424 /* end of block.c */