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      SPDX-License-Identifier: AGPL3.0-or-later
  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  * Create a block context.  Loads the block plugins.
 126  *
 127  * @param cfg configuration to use
 128  * @return NULL on error
 129  */
 130 struct GNUNET_BLOCK_Context *
 131 GNUNET_BLOCK_context_create (const struct GNUNET_CONFIGURATION_Handle *cfg)
 132 {
 133   struct GNUNET_BLOCK_Context *ctx;
 134
 135   ctx = GNUNET_new (struct GNUNET_BLOCK_Context);
 136   ctx->cfg = cfg;
 137   GNUNET_PLUGIN_load_all ("libgnunet_plugin_block_",
 138                           (void *) cfg,
 139                           &add_plugin,
 140                           ctx);
 141   return ctx;
 142 }
 143
 144
 145 /**
 146  * Destroy the block context.
 147  *
 148  * @param ctx context to destroy
 149  */
 150 void
 151 GNUNET_BLOCK_context_destroy (struct GNUNET_BLOCK_Context *ctx)
 152 {
 153   struct Plugin *plugin;
 154
 155   for (unsigned int i = 0; i < ctx->num_plugins; i++)
 156   {
 157     plugin = ctx->plugins[i];
 158     GNUNET_break (NULL ==
 159                   GNUNET_PLUGIN_unload (plugin->library_name,
 160                                         plugin->api));
 161     GNUNET_free (plugin->library_name);
 162     GNUNET_free (plugin);
 163   }
 164   GNUNET_free (ctx->plugins);
 165   GNUNET_free (ctx);
 166 }
 167
 168
 169 /**
 170  * Serialize state of a block group.
 171  *
 172  * @param bg group to serialize
 173  * @param[out] nonce set to the nonce of the @a bg
 174  * @param[out] raw_data set to the serialized state
 175  * @param[out] raw_data_size set to the number of bytes in @a raw_data
 176  * @return #GNUNET_OK on success, #GNUNET_NO if serialization is not
 177  *         supported, #GNUNET_SYSERR on error
 178  */
 179 int
 180 GNUNET_BLOCK_group_serialize (struct GNUNET_BLOCK_Group *bg,
 181                               uint32_t *nonce,
 182                               void **raw_data,
 183                               size_t *raw_data_size)
 184 {
 185   *nonce = 0;
 186   *raw_data = NULL;
 187   *raw_data_size = 0;
 188   if (NULL == bg)
 189     return GNUNET_NO;
 190   if (NULL == bg->serialize_cb)
 191     return GNUNET_NO;
 192   return bg->serialize_cb (bg,
 193                            nonce,
 194                            raw_data,
 195                            raw_data_size);
 196 }
 197
 198
 199 /**
 200  * Destroy resources used by a block group.
 201  *
 202  * @param bg group to destroy, NULL is allowed
 203  */
 204 void
 205 GNUNET_BLOCK_group_destroy (struct GNUNET_BLOCK_Group *bg)
 206 {
 207   if (NULL == bg)
 208     return;
 209   bg->destroy_cb (bg);
 210 }
 211
 212
 213 /**
 214  * Try merging two block groups.  Afterwards, @a bg1 should remain
 215  * valid and contain the rules from both @a bg1 and @bg2, and
 216  * @a bg2 should be destroyed (as part of this call).  The latter
 217  * should happen even if merging is not supported.
 218  *
 219  * @param[in,out] bg1 first group to merge, is updated
 220  * @param bg2 second group to merge, is destroyed
 221  * @return #GNUNET_OK on success,
 222  *         #GNUNET_NO if merge failed due to different nonce
 223  *         #GNUNET_SYSERR if merging is not supported
 224  */
 225 int
 226 GNUNET_BLOCK_group_merge (struct GNUNET_BLOCK_Group *bg1,
 227                           struct GNUNET_BLOCK_Group *bg2)
 228 {
 229   int ret;
 230
 231   if (NULL == bg2)
 232     return GNUNET_OK;
 233   if (NULL == bg1)
 234   {
 235     bg2->destroy_cb (bg2);
 236     return GNUNET_OK;
 237   }
 238   if (NULL == bg1->merge_cb)
 239     return GNUNET_SYSERR;
 240   GNUNET_assert (bg1->merge_cb == bg1->merge_cb);
 241   ret = bg1->merge_cb (bg1,
 242                        bg2);
 243   bg2->destroy_cb (bg2);
 244   return ret;
 245 }
 246
 247
 248 /**
 249  * Find a plugin for the given type.
 250  *
 251  * @param ctx context to search
 252  * @param type type to look for
 253  * @return NULL if no matching plugin exists
 254  */
 255 static struct GNUNET_BLOCK_PluginFunctions *
 256 find_plugin (struct GNUNET_BLOCK_Context *ctx,
 257              enum GNUNET_BLOCK_Type type)
 258 {
 259   struct Plugin *plugin;
 260   unsigned int j;
 261
 262   for (unsigned i = 0; i < ctx->num_plugins; i++)
 263   {
 264     plugin = ctx->plugins[i];
 265     j = 0;
 266     while (0 != (plugin->api->types[j]))
 267     {
 268       if (type == plugin->api->types[j])
 269         return plugin->api;
 270       j++;
 271     }
 272   }
 273   return NULL;
 274 }
 275
 276
 277 /**
 278  * Create a new block group.
 279  *
 280  * @param ctx block context in which the block group is created
 281  * @param type type of the block for which we are creating the group
 282  * @param nonce random value used to seed the group creation
 283  * @param raw_data optional serialized prior state of the group, NULL if unavailable/fresh
 284  * @param raw_data_size number of bytes in @a raw_data, 0 if unavailable/fresh
 285  * @return block group handle, NULL if block groups are not supported
 286  *         by this @a type of block (this is not an error)
 287  */
 288 struct GNUNET_BLOCK_Group *
 289 GNUNET_BLOCK_group_create (struct GNUNET_BLOCK_Context *ctx,
 290                            enum GNUNET_BLOCK_Type type,
 291                            uint32_t nonce,
 292                            const void *raw_data,
 293                            size_t raw_data_size,
 294                            ...)
 295 {
 296   struct GNUNET_BLOCK_PluginFunctions *plugin;
 297   struct GNUNET_BLOCK_Group *bg;
 298   va_list ap;
 299
 300   plugin = find_plugin (ctx,
 301                         type);
 302   if (NULL == plugin)
 303     return NULL;
 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 */