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