src/include/gnunet_sensor_util_lib.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
   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  * @author Omar Tarabai
  23  *
  24  * @file
  25  * Sensor utilities
  26  *
  27  * @defgroup sensor  Sensor Utilities library
  28  *
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_SENSOR_UTIL_LIB_H
  33 #define GNUNET_SENSOR_UTIL_LIB_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 /**
  44  * Structure containing sensor definition
  45  */
  46 struct GNUNET_SENSOR_SensorInfo
  47 {
  48
  49   /**
  50    * The configuration handle
  51    * carrying sensor information
  52    */
  53   struct GNUNET_CONFIGURATION_Handle *cfg;
  54
  55   /**
  56    * Sensor name
  57    */
  58   char *name;
  59
  60   /**
  61    * Path to definition file
  62    */
  63   char *def_file;
  64
  65   /**
  66    * First part of version number
  67    */
  68   uint16_t version_major;
  69
  70   /**
  71    * Second part of version number
  72    */
  73   uint16_t version_minor;
  74
  75   /**
  76    * Sensor description
  77    */
  78   char *description;
  79
  80   /**
  81    * Sensor currently enabled
  82    */
  83   int enabled;
  84
  85   /**
  86    * Category under which the sensor falls (e.g. tcp, datastore)
  87    */
  88   char *category;
  89
  90   /**
  91    * When does the sensor become active
  92    */
  93   struct GNUNET_TIME_Absolute *start_time;
  94
  95   /**
  96    * When does the sensor expire
  97    */
  98   struct GNUNET_TIME_Absolute *end_time;
  99
 100   /**
 101    * Time interval to collect sensor information (e.g. every 1 min)
 102    */
 103   struct GNUNET_TIME_Relative interval;
 104
 105   /**
 106    * Lifetime of an information sample after which it is deleted from storage
 107    * If not supplied, will default to the interval value
 108    */
 109   struct GNUNET_TIME_Relative lifetime;
 110
 111   /**
 112    * A set of required peer capabilities for the sensor to collect meaningful information (e.g. ipv6)
 113    */
 114   char *capabilities;
 115
 116   /**
 117    * Either "gnunet-statistics" or external "process"
 118    */
 119   char *source;
 120
 121   /**
 122    * Name of the GNUnet service that is the source for the gnunet-statistics entry
 123    */
 124   char *gnunet_stat_service;
 125
 126   /**
 127    * Name of the gnunet-statistics entry
 128    */
 129   char *gnunet_stat_name;
 130
 131   /**
 132    * Handle to statistics get request (OR NULL)
 133    */
 134   struct GNUNET_STATISTICS_GetHandle *gnunet_stat_get_handle;
 135
 136   /**
 137    * Name of the external process to be executed
 138    */
 139   char *ext_process;
 140
 141   /**
 142    * Arguments to be passed to the external process
 143    */
 144   char *ext_args;
 145
 146   /**
 147    * Handle to the external process
 148    */
 149   struct GNUNET_OS_CommandHandle *ext_cmd;
 150
 151   /**
 152    * Did we already receive a value
 153    * from the currently running external
 154    * proccess ? #GNUNET_YES / #GNUNET_NO
 155    */
 156   int ext_cmd_value_received;
 157
 158   /**
 159    * The output datatype to be expected
 160    */
 161   char *expected_datatype;
 162
 163   /**
 164    * Peer-identity of peer running collection point
 165    */
 166   struct GNUNET_PeerIdentity *collection_point;
 167
 168   /**
 169    * Do we report received sensor values to collection point?
 170    * #GNUNET_YES / #GNUNET_NO
 171    */
 172   int report_values;
 173
 174   /**
 175    * Time interval to send sensor values to collection point (e.g. every 30 mins)
 176    */
 177   struct GNUNET_TIME_Relative value_reporting_interval;
 178
 179   /**
 180    * Do we report anomalies to collection point?
 181    * #GNUNET_YES / #GNUNET_NO
 182    */
 183   int report_anomalies;
 184
 185   /**
 186    * Execution task (OR NULL)
 187    */
 188   struct GNUNET_SCHEDULER_Task * execution_task;
 189
 190   /**
 191    * Is the sensor being executed
 192    */
 193   int running;
 194
 195 };
 196
 197 /**
 198  * Anomaly report received and stored by sensor dashboard.
 199  * Sensor name and peer id are not included because they are part of the
 200  * peerstore key.
 201  */
 202 struct GNUNET_SENSOR_DashboardAnomalyEntry
 203 {
 204
 205   /**
 206    * New anomaly status
 207    */
 208   uint16_t anomalous;
 209
 210   /**
 211    * Percentage of neighbors reported the same anomaly
 212    */
 213   float anomalous_neighbors;
 214
 215 };
 216
 217 GNUNET_NETWORK_STRUCT_BEGIN
 218 /**
 219  * Used to communicate brief information about a sensor.
 220  */
 221     struct GNUNET_SENSOR_SensorBriefMessage
 222 {
 223
 224   /**
 225    * GNUNET general message header.
 226    */
 227   struct GNUNET_MessageHeader header;
 228
 229   /**
 230    * Size of sensor name string, allocated at position 0 after this struct.
 231    */
 232   uint16_t name_size;
 233
 234   /**
 235    * First part of sensor version number
 236    */
 237   uint16_t version_major;
 238
 239   /**
 240    * Second part of sensor version number
 241    */
 242   uint16_t version_minor;
 243
 244 };
 245
 246 /**
 247  * Used to communicate full information about a sensor.
 248  */
 249 struct GNUNET_SENSOR_SensorFullMessage
 250 {
 251
 252   /**
 253    * GNUNET general message header.
 254    */
 255   struct GNUNET_MessageHeader header;
 256
 257   /**
 258    * Size of sensor name.
 259    * Name allocated at position 0 after this struct.
 260    */
 261   uint16_t sensorname_size;
 262
 263   /**
 264    * Size of the sensor definition file carrying full sensor information.
 265    * The file content allocated at position 1 after this struct.
 266    */
 267   uint16_t sensorfile_size;
 268
 269   /**
 270    * Name of the file (usually script) associated with this sensor.
 271    * At the moment we only support having one file per sensor.
 272    * The file name is allocated at position 2 after this struct.
 273    */
 274   uint16_t scriptname_size;
 275
 276   /**
 277    * Size of the file (usually script) associated with this sensor.
 278    * The file content is allocated at position 3 after this struct.
 279    */
 280   uint16_t scriptfile_size;
 281
 282 };
 283
 284 /**
 285  * Used to communicate sensor values to
 286  * collection points (SENSORDASHBAORD service)
 287  */
 288 struct GNUNET_SENSOR_ValueMessage
 289 {
 290
 291   /**
 292    * GNUNET general message header
 293    */
 294   struct GNUNET_MessageHeader header;
 295
 296   /**
 297    * Hash of sensor name
 298    */
 299   struct GNUNET_HashCode sensorname_hash;
 300
 301   /**
 302    * First part of sensor version number
 303    */
 304   uint16_t sensorversion_major;
 305
 306   /**
 307    * Second part of sensor version number
 308    */
 309   uint16_t sensorversion_minor;
 310
 311   /**
 312    * Timestamp of recorded reading
 313    */
 314   struct GNUNET_TIME_Absolute timestamp;
 315
 316   /**
 317    * Size of sensor value, allocated at poistion 0 after this struct
 318    */
 319   uint16_t value_size;
 320
 321 };
 322
 323 /**
 324  * Message carrying an anomaly status change report
 325  */
 326 struct GNUNET_SENSOR_AnomalyReportMessage
 327 {
 328
 329   /**
 330    * Hash of sensor name
 331    */
 332   struct GNUNET_HashCode sensorname_hash;
 333
 334   /**
 335    * First part of sensor version number
 336    */
 337   uint16_t sensorversion_major;
 338
 339   /**
 340    * Second part of sensor version name
 341    */
 342   uint16_t sensorversion_minor;
 343
 344   /**
 345    * New anomaly status
 346    */
 347   uint16_t anomalous;
 348
 349   /**
 350    * Percentage of neighbors reported the same anomaly
 351    */
 352   float anomalous_neighbors;
 353
 354 };
 355
 356 GNUNET_NETWORK_STRUCT_END
 357 /**
 358  * Given two version numbers as major and minor, compare them.
 359  *
 360  * @param v1_major First part of first version number
 361  * @param v1_minor Second part of first version number
 362  * @param v2_major First part of second version number
 363  * @param v2_minor Second part of second version number
 364  */
 365     int
 366 GNUNET_SENSOR_version_compare (uint16_t v1_major, uint16_t v1_minor,
 367                                uint16_t v2_major, uint16_t v2_minor);
 368
 369
 370 /**
 371  * Reads sensor definitions from given sensor directory.
 372  *
 373  * @param sensordir Path to sensor directory.
 374  * @return a multihashmap of loaded sensors
 375  */
 376 struct GNUNET_CONTAINER_MultiHashMap *
 377 GNUNET_SENSOR_load_all_sensors (char *sensor_dir);
 378
 379
 380 /**
 381  * Get path to the default directory containing the sensor definition files with
 382  * a trailing directory separator.
 383  *
 384  * @return Default sensor files directory full path
 385  */
 386 char *
 387 GNUNET_SENSOR_get_default_sensor_dir ();
 388
 389
 390 /**
 391  * Destroys a group of sensors in a hashmap and the hashmap itself
 392  *
 393  * @param sensors hashmap containing the sensors
 394  */
 395 void
 396 GNUNET_SENSOR_destroy_sensors (struct GNUNET_CONTAINER_MultiHashMap *sensors);
 397
 398
 399 struct GNUNET_SENSOR_crypto_pow_context;
 400
 401 /**
 402  * Block carrying arbitrary data + its proof-of-work + signature
 403  */
 404 struct GNUNET_SENSOR_crypto_pow_block
 405 {
 406
 407   /**
 408    * Proof-of-work value
 409    */
 410   uint64_t pow;
 411
 412   /**
 413    * Data signature
 414    */
 415   struct GNUNET_CRYPTO_EddsaSignature signature;
 416
 417   /**
 418    * Size of the msg component (allocated after this struct)
 419    */
 420   size_t msg_size;
 421
 422   /**
 423    * Purpose of signing.
 424    * Data is allocated after this (timestamp, public_key, msg).
 425    */
 426   struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 427
 428   /**
 429    * First part of data - timestamp
 430    */
 431   struct GNUNET_TIME_Absolute timestamp;
 432
 433   /**
 434    * Second part of data - Public key
 435    */
 436   struct GNUNET_CRYPTO_EddsaPublicKey public_key;
 437
 438 };
 439
 440
 441 /**
 442  * Continuation called with a status result.
 443  *
 444  * @param cls closure
 445  * @param pow Proof-of-work value
 446  * @param purpose Signed block (size, purpose, data)
 447  * @param signature Signature, NULL on error
 448  */
 449 typedef void (*GNUNET_SENSOR_UTIL_pow_callback) (void *cls,
 450                                                  struct
 451                                                  GNUNET_SENSOR_crypto_pow_block
 452                                                  * block);
 453
 454
 455 /**
 456  * Cancel an operation started by #GNUNET_SENSOR_crypto_pow_sign().
 457  * Call only before callback function passed to #GNUNET_SENSOR_crypto_pow_sign()
 458  * is called with the result.
 459  */
 460 void
 461 GNUNET_SENSOR_crypto_pow_sign_cancel (struct GNUNET_SENSOR_crypto_pow_context
 462                                       *cx);
 463
 464
 465 /**
 466  * Calculate proof-of-work and sign a message.
 467  *
 468  * @param msg Message to calculate pow and sign
 469  * @param msg_size size of msg
 470  * @param timestamp Timestamp to add to the message to protect against replay attacks
 471  * @param public_key Public key of the origin peer, to protect against redirect attacks
 472  * @param private_key Private key of the origin peer to sign the result
 473  * @param matching_bits Number of leading zeros required in the result hash
 474  * @param callback Callback function to call with the result
 475  * @param callback_cls Closure for callback
 476  * @return Operation context
 477  */
 478 struct GNUNET_SENSOR_crypto_pow_context *
 479 GNUNET_SENSOR_crypto_pow_sign (void *msg, size_t msg_size,
 480                                struct GNUNET_TIME_Absolute *timestamp,
 481                                struct GNUNET_CRYPTO_EddsaPublicKey *public_key,
 482                                struct GNUNET_CRYPTO_EddsaPrivateKey
 483                                *private_key, int matching_bits,
 484                                GNUNET_SENSOR_UTIL_pow_callback callback,
 485                                void *callback_cls);
 486
 487
 488 /**
 489  * Verify that proof-of-work and signature in the given block are valid.
 490  * If all valid, a pointer to the payload within the block is set and the size
 491  * of the payload is returned.
 492  *
 493  * **VERY IMPORTANT** : You will still need to verify the timestamp yourself.
 494  *
 495  * @param block The block received and needs to be verified
 496  * @param matching_bits Number of leading zeros in the hash used to verify pow
 497  * @param public_key Public key of the peer that sent this block
 498  * @param payload Where to store the pointer to the payload
 499  * @return Size of the payload
 500  */
 501 size_t
 502 GNUNET_SENSOR_crypto_verify_pow_sign (struct GNUNET_SENSOR_crypto_pow_block *
 503                                       block, int matching_bits,
 504                                       struct GNUNET_CRYPTO_EddsaPublicKey *
 505                                       public_key, void **payload);
 506
 507
 508 #if 0                           /* keep Emacsens' auto-indent happy */
 509 {
 510 #endif
 511 #ifdef __cplusplus
 512 }
 513 #endif
 514
 515 /* ifndef GNUNET_SENSOR_UTIL_LIB_H */
 516 #endif
 517
 518 /** @} */  /* end of group */
 519
 520 /* end of gnunet_sensor_util_lib.h */