src/charon/bus/bus.h

   1 /*
   2  * Copyright (C) 2006-2009 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup bus bus
  18  * @{ @ingroup charon
  19  */
  20
  21 #ifndef BUS_H_
  22 #define BUS_H_
  23
  24 typedef enum debug_t debug_t;
  25 typedef enum level_t level_t;
  26 typedef enum alert_t alert_t;
  27 typedef struct bus_t bus_t;
  28
  29 #include <stdarg.h>
  30
  31 #include <sa/ike_sa.h>
  32 #include <sa/child_sa.h>
  33 #include <processing/jobs/job.h>
  34 #include <bus/listeners/listener.h>
  35
  36 /**
  37  * Debug message group.
  38  */
  39 enum debug_t {
  40         /** daemon main loop */
  41         DBG_DMN,
  42         /** IKE_SA_MANAGER */
  43         DBG_MGR,
  44         /** IKE_SA */
  45         DBG_IKE,
  46         /** CHILD_SA */
  47         DBG_CHD,
  48         /** job processing */
  49         DBG_JOB,
  50         /** configuration backends */
  51         DBG_CFG,
  52         /** kernel interface */
  53         DBG_KNL,
  54         /** networking/sockets */
  55         DBG_NET,
  56         /** message encoding/decoding */
  57         DBG_ENC,
  58         /** libstrongswan via logging hook */
  59         DBG_LIB,
  60         /** number of groups */
  61         DBG_MAX,
  62         /** pseudo group with all groups */
  63         DBG_ANY = DBG_MAX,
  64 };
  65
  66 /**
  67  * short names of debug message group.
  68  */
  69 extern enum_name_t *debug_names;
  70
  71 /**
  72  * short names of debug message group, lower case.
  73  */
  74 extern enum_name_t *debug_lower_names;
  75
  76 /**
  77  * Debug levels used to control output verbosity.
  78  */
  79 enum level_t {
  80         /** absolutely silent */
  81         LEVEL_SILENT =  -1,
  82         /** most important auditing logs */
  83         LEVEL_AUDIT =    0,
  84         /** control flow */
  85         LEVEL_CTRL =     1,
  86         /** diagnose problems */
  87         LEVEL_DIAG =     2,
  88         /** raw binary blobs */
  89         LEVEL_RAW =      3,
  90         /** including sensitive data (private keys) */
  91         LEVEL_PRIVATE =  4,
  92 };
  93
  94 #ifndef DEBUG_LEVEL
  95 # define DEBUG_LEVEL 4
  96 #endif /* DEBUG_LEVEL */
  97
  98 #if DEBUG_LEVEL >= 0
  99 #define DBG0(group, format, ...) charon->bus->log(charon->bus, group, 0, format, ##__VA_ARGS__)
 100 #endif /* DEBUG_LEVEL >= 0 */
 101 #if DEBUG_LEVEL >= 1
 102 #define DBG1(group, format, ...) charon->bus->log(charon->bus, group, 1, format, ##__VA_ARGS__)
 103 #endif /* DEBUG_LEVEL >= 1 */
 104 #if DEBUG_LEVEL >= 2
 105 #define DBG2(group, format, ...) charon->bus->log(charon->bus, group, 2, format, ##__VA_ARGS__)
 106 #endif /* DEBUG_LEVEL >= 2 */
 107 #if DEBUG_LEVEL >= 3
 108 #define DBG3(group, format, ...) charon->bus->log(charon->bus, group, 3, format, ##__VA_ARGS__)
 109 #endif /* DEBUG_LEVEL >= 3 */
 110 #if DEBUG_LEVEL >= 4
 111 #define DBG4(group, format, ...) charon->bus->log(charon->bus, group, 4, format, ##__VA_ARGS__)
 112 #endif /* DEBUG_LEVEL >= 4 */
 113
 114 #ifndef DBG0
 115 # define DBG0(...) {}
 116 #endif /* DBG0 */
 117 #ifndef DBG1
 118 # define DBG1(...) {}
 119 #endif /* DBG1 */
 120 #ifndef DBG2
 121 # define DBG2(...) {}
 122 #endif /* DBG2 */
 123 #ifndef DBG3
 124 # define DBG3(...) {}
 125 #endif /* DBG3 */
 126 #ifndef DBG4
 127 # define DBG4(...) {}
 128 #endif /* DBG4 */
 129
 130 /**
 131  * Kind of alerts to raise.
 132  */
 133 enum alert_t {
 134         /* a RADIUS server did not respond, no additional arguments */
 135         ALERT_RADIUS_NOT_RESPONDING,
 136         /* a shutdown signal has been received, argument is a int with the signal */
 137         ALERT_SHUTDOWN_SIGNAL,
 138 };
 139
 140 /**
 141  * The bus receives events and sends them to all registered listeners.
 142  *
 143  * Any events sent to are delivered to all registered listeners. Threads
 144  * may wait actively to events using the blocking listen() call.
 145  */
 146 struct bus_t {
 147
 148         /**
 149          * Register a listener to the bus.
 150          *
 151          * A registered listener receives all events which are sent to the bus.
 152          * The listener is passive; the thread which emitted the event
 153          * processes the listener routine.
 154          *
 155          * @param listener      listener to register.
 156          */
 157         void (*add_listener) (bus_t *this, listener_t *listener);
 158
 159         /**
 160          * Unregister a listener from the bus.
 161          *
 162          * @param listener      listener to unregister.
 163          */
 164         void (*remove_listener) (bus_t *this, listener_t *listener);
 165
 166         /**
 167          * Register a listener and block the calling thread.
 168          *
 169          * This call registers a listener and blocks the calling thread until
 170          * its listeners function returns FALSE. This allows to wait for certain
 171          * events. The associated job is executed after the listener has been
 172          * registered: This allows to listen on events we initiate with the job,
 173          * without missing any events to job may fire.
 174          *
 175          * @param listener      listener to register
 176          * @param job           job to execute asynchronously when registered, or NULL
 177          */
 178         void (*listen)(bus_t *this, listener_t *listener, job_t *job);
 179
 180         /**
 181          * Set the IKE_SA the calling thread is using.
 182          *
 183          * To associate an received log message to an IKE_SA without passing it as
 184          * parameter each time, the thread registers the currenlty used IKE_SA
 185          * during check-out. Before check-in, the thread unregisters the IKE_SA.
 186          * This IKE_SA is stored per-thread, so each thread has its own IKE_SA
 187          * registered.
 188          *
 189          * @param ike_sa        ike_sa to register, or NULL to unregister
 190          */
 191         void (*set_sa) (bus_t *this, ike_sa_t *ike_sa);
 192
 193         /**
 194          * Get the IKE_SA the calling thread is currently using.
 195          *
 196          * If a thread currently does not know what IKE_SA it is processing,
 197          * it can call get_sa() to look up the SA set during checkout via set_sa().
 198          *
 199          * @return                      registered ike_sa, NULL if none registered
 200          */
 201         ike_sa_t* (*get_sa)(bus_t *this);
 202
 203         /**
 204          * Send a log message to the bus.
 205          *
 206          * The signal specifies the type of the event occured. The format string
 207          * specifies an additional informational or error message with a
 208          * printf() like variable argument list.
 209          * Use the DBG() macros.
 210          *
 211          * @param group         debugging group
 212          * @param level         verbosity level of the signal
 213          * @param format        printf() style format string
 214          * @param ...           printf() style argument list
 215          */
 216         void (*log)(bus_t *this, debug_t group, level_t level, char* format, ...);
 217
 218         /**
 219          * Send a log message to the bus using va_list arguments.
 220          *
 221          * Same as bus_t.signal(), but uses va_list argument list.
 222          *
 223          * @param group         kind of the signal (up, down, rekeyed, ...)
 224          * @param level         verbosity level of the signal
 225          * @param format        printf() style format string
 226          * @param args          va_list arguments
 227          */
 228         void (*vlog)(bus_t *this, debug_t group, level_t level,
 229                                  char* format, va_list args);
 230
 231         /**
 232          * Raise an alert over the bus.
 233          *
 234          * @param alert         kind of alert
 235          * @param ...           alert specific attributes
 236          */
 237         void (*alert)(bus_t *this, alert_t alert, ...);
 238
 239         /**
 240          * Send a IKE_SA state change event to the bus.
 241          *
 242          * @param ike_sa        IKE_SA which changes its state
 243          * @param state         new state IKE_SA changes to
 244          */
 245         void (*ike_state_change)(bus_t *this, ike_sa_t *ike_sa,
 246                                                          ike_sa_state_t state);
 247         /**
 248          * Send a CHILD_SA state change event to the bus.
 249          *
 250          * @param child_sa      CHILD_SA which changes its state
 251          * @param state         new state CHILD_SA changes to
 252          */
 253         void (*child_state_change)(bus_t *this, child_sa_t *child_sa,
 254                                                            child_sa_state_t state);
 255         /**
 256          * Message send/receive hook.
 257          *
 258          * @param message       message to send/receive
 259          * @param incoming      TRUE for incoming messages, FALSE for outgoing
 260          */
 261         void (*message)(bus_t *this, message_t *message, bool incoming);
 262
 263         /**
 264          * IKE_SA authorization hook.
 265          *
 266          * @param final         TRUE if this is the final invocation
 267          * @return                      TRUE to establish IKE_SA, FALSE to send AUTH_FAILED
 268          */
 269         bool (*authorize)(bus_t *this, bool final);
 270
 271         /**
 272          * IKE_SA keymat hook.
 273          *
 274          * @param ike_sa        IKE_SA this keymat belongs to
 275          * @param dh            diffie hellman shared secret
 276          * @param nonce_i       initiators nonce
 277          * @param nonce_r       responders nonce
 278          * @param rekey         IKE_SA we are rekeying, if any
 279          */
 280         void (*ike_keys)(bus_t *this, ike_sa_t *ike_sa, diffie_hellman_t *dh,
 281                                          chunk_t nonce_i, chunk_t nonce_r, ike_sa_t *rekey);
 282         /**
 283          * CHILD_SA keymat hook.
 284          *
 285          * @param child_sa      CHILD_SA this keymat is used for
 286          * @param dh            diffie hellman shared secret
 287          * @param nonce_i       initiators nonce
 288          * @param nonce_r       responders nonce
 289          */
 290         void (*child_keys)(bus_t *this, child_sa_t *child_sa, diffie_hellman_t *dh,
 291                                            chunk_t nonce_i, chunk_t nonce_r);
 292
 293         /**
 294          * IKE_SA up/down hook.
 295          *
 296          * @param ike_sa        IKE_SA coming up/going down
 297          * @param up            TRUE for an up event, FALSE for a down event
 298          */
 299         void (*ike_updown)(bus_t *this, ike_sa_t *ike_sa, bool up);
 300
 301         /**
 302          * IKE_SA rekeying hook.
 303          *
 304          * @param old           rekeyed and obsolete IKE_SA
 305          * @param new           new IKE_SA replacing old
 306          */
 307         void (*ike_rekey)(bus_t *this, ike_sa_t *old, ike_sa_t *new);
 308
 309         /**
 310          * CHILD_SA up/down hook.
 311          *
 312          * @param child_sa      CHILD_SA coming up/going down
 313          * @param up            TRUE for an up event, FALSE for a down event
 314          */
 315         void (*child_updown)(bus_t *this, child_sa_t *child_sa, bool up);
 316
 317         /**
 318          * CHILD_SA rekeying hook.
 319          *
 320          * @param old           rekeyed and obsolete CHILD_SA
 321          * @param new           new CHILD_SA replacing old
 322          */
 323         void (*child_rekey)(bus_t *this, child_sa_t *old, child_sa_t *new);
 324
 325         /**
 326          * Destroy the event bus.
 327          */
 328         void (*destroy) (bus_t *this);
 329 };
 330
 331 /**
 332  * Create the event bus which forwards events to its listeners.
 333  *
 334  * @return              event bus instance
 335  */
 336 bus_t *bus_create();
 337
 338 #endif /** BUS_H_ @}*/