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