src/libcharon/bus/bus.h

   1 /*
   2  * Copyright (C) 2012 Tobias Brunner
   3  * Copyright (C) 2006-2009 Martin Willi
   4  * Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup bus bus
  19  * @{ @ingroup libcharon
  20  */
  21
  22 #ifndef BUS_H_
  23 #define BUS_H_
  24
  25 typedef enum alert_t alert_t;
  26 typedef enum narrow_hook_t narrow_hook_t;
  27 typedef struct bus_t bus_t;
  28
  29 #include <stdarg.h>
  30
  31 #include <debug.h>
  32 #include <sa/ike_sa.h>
  33 #include <sa/child_sa.h>
  34 #include <processing/jobs/job.h>
  35 #include <bus/listeners/logger.h>
  36 #include <bus/listeners/listener.h>
  37
  38 /* undefine the definitions from libstrongswan */
  39 #undef DBG0
  40 #undef DBG1
  41 #undef DBG2
  42 #undef DBG3
  43 #undef DBG4
  44
  45 #ifndef DEBUG_LEVEL
  46 # define DEBUG_LEVEL 4
  47 #endif /* DEBUG_LEVEL */
  48
  49 #if DEBUG_LEVEL >= 0
  50 #define DBG0(group, format, ...) charon->bus->log(charon->bus, group, 0, format, ##__VA_ARGS__)
  51 #endif /* DEBUG_LEVEL >= 0 */
  52 #if DEBUG_LEVEL >= 1
  53 #define DBG1(group, format, ...) charon->bus->log(charon->bus, group, 1, format, ##__VA_ARGS__)
  54 #endif /* DEBUG_LEVEL >= 1 */
  55 #if DEBUG_LEVEL >= 2
  56 #define DBG2(group, format, ...) charon->bus->log(charon->bus, group, 2, format, ##__VA_ARGS__)
  57 #endif /* DEBUG_LEVEL >= 2 */
  58 #if DEBUG_LEVEL >= 3
  59 #define DBG3(group, format, ...) charon->bus->log(charon->bus, group, 3, format, ##__VA_ARGS__)
  60 #endif /* DEBUG_LEVEL >= 3 */
  61 #if DEBUG_LEVEL >= 4
  62 #define DBG4(group, format, ...) charon->bus->log(charon->bus, group, 4, format, ##__VA_ARGS__)
  63 #endif /* DEBUG_LEVEL >= 4 */
  64
  65 #ifndef DBG0
  66 # define DBG0(...) {}
  67 #endif /* DBG0 */
  68 #ifndef DBG1
  69 # define DBG1(...) {}
  70 #endif /* DBG1 */
  71 #ifndef DBG2
  72 # define DBG2(...) {}
  73 #endif /* DBG2 */
  74 #ifndef DBG3
  75 # define DBG3(...) {}
  76 #endif /* DBG3 */
  77 #ifndef DBG4
  78 # define DBG4(...) {}
  79 #endif /* DBG4 */
  80
  81 /**
  82  * Kind of alerts to raise.
  83  */
  84 enum alert_t {
  85         /** a RADIUS server did not respond, no additional arguments */
  86         ALERT_RADIUS_NOT_RESPONDING,
  87         /** a shutdown signal has been received, argument is the signal (int) */
  88         ALERT_SHUTDOWN_SIGNAL,
  89         /** peer authentication failed, no arguments */
  90         ALERT_PEER_AUTH_FAILED,
  91         /** failed to resolve peer address, no arguments */
  92         ALERT_PEER_ADDR_FAILED,
  93         /** peer did not respond to initial message, current try (int, 0-based) */
  94         ALERT_PEER_INIT_UNREACHABLE,
  95         /** received IKE message with invalid SPI, argument is message_t* */
  96         ALERT_INVALID_IKE_SPI,
  97         /** received IKE message with invalid header, argument is message_t* */
  98         ALERT_PARSE_ERROR_HEADER,
  99 };
 100
 101 /**
 102  * Kind of narrow hook.
 103  *
 104  * There is a non-authenticated (IKE_AUTH) and a authenticated
 105  * (CREATE_CHILD_SA) narrowing hook for the initiator. Only one of these
 106  * hooks is invoked before the exchange.
 107  * To verify the traffic selectors negotiated, each PRE hook has a POST
 108  * counterpart that follows. POST hooks are invoked with an authenticated peer.
 109  * It is usually not a good idea to narrow in the POST hooks,
 110  * as the resulting traffic selector is not negotiated and results
 111  * in non-matching policies.
 112  */
 113 enum narrow_hook_t {
 114         /** invoked as initiator before exchange, peer is not yet authenticated */
 115         NARROW_INITIATOR_PRE_NOAUTH,
 116         /** invoked as initiator before exchange, peer is authenticated */
 117         NARROW_INITIATOR_PRE_AUTH,
 118         /** invoked as responder during exchange, peer is authenticated */
 119         NARROW_RESPONDER,
 120         /** invoked as responder after exchange, peer is authenticated */
 121         NARROW_RESPONDER_POST,
 122         /** invoked as initiator after exchange, follows a INITIATOR_PRE_NOAUTH */
 123         NARROW_INITIATOR_POST_NOAUTH,
 124         /** invoked as initiator after exchange, follows a INITIATOR_PRE_AUTH */
 125         NARROW_INITIATOR_POST_AUTH,
 126 };
 127
 128 /**
 129  * The bus receives events and sends them to all registered listeners.
 130  *
 131  * Loggers are handled separately.
 132  */
 133 struct bus_t {
 134
 135         /**
 136          * Register a listener to the bus.
 137          *
 138          * A registered listener receives all events which are sent to the bus.
 139          * The listener is passive; the thread which emitted the event
 140          * processes the listener routine.
 141          *
 142          * @param listener      listener to register.
 143          */
 144         void (*add_listener) (bus_t *this, listener_t *listener);
 145
 146         /**
 147          * Unregister a listener from the bus.
 148          *
 149          * @param listener      listener to unregister.
 150          */
 151         void (*remove_listener) (bus_t *this, listener_t *listener);
 152
 153         /**
 154          * Register a logger with the bus.
 155          *
 156          * The logger is passive; the thread which emitted the event
 157          * processes the logger routine.  This routine may be called concurrently
 158          * by multiple threads.  Recursive calls are not prevented, so logger that
 159          * may cause recursive calls are responsible to avoid infinite loops.
 160          *
 161          * During registration get_level() is called for all log groups and the
 162          * logger is registered to receive log messages for groups for which
 163          * the requested log level is > LEVEL_SILENT and whose level is lower
 164          * or equal than the requested level.
 165          *
 166          * To update the registered log levels call add_logger again with the
 167          * same logger and return the new levels from get_level().
 168          *
 169          * @param logger        logger to register.
 170          */
 171         void (*add_logger) (bus_t *this, logger_t *logger);
 172
 173         /**
 174          * Unregister a logger from the bus.
 175          *
 176          * @param logger        logger to unregister.
 177          */
 178         void (*remove_logger) (bus_t *this, logger_t *logger);
 179
 180         /**
 181          * Set the IKE_SA the calling thread is using.
 182          *
 183          * To associate a received log message with an IKE_SA without passing it as
 184          * parameter each time, the thread registers the currently 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 format string specifies an additional informational or error
 207          * message with a printf() like variable argument list.
 208          * Use the DBG() macros.
 209          *
 210          * @param group         debugging group
 211          * @param level         verbosity level of the signal
 212          * @param format        printf() style format string
 213          * @param ...           printf() style argument list
 214          */
 215         void (*log)(bus_t *this, debug_t group, level_t level, char* format, ...);
 216
 217         /**
 218          * Send a log message to the bus using va_list arguments.
 219          *
 220          * Same as bus_t.log(), but uses va_list argument list.
 221          *
 222          * @param group         kind of the signal (up, down, rekeyed, ...)
 223          * @param level         verbosity level of the signal
 224          * @param format        printf() style format string
 225          * @param args          va_list arguments
 226          */
 227         void (*vlog)(bus_t *this, debug_t group, level_t level,
 228                                  char* format, va_list args);
 229
 230         /**
 231          * Raise an alert over the bus.
 232          *
 233          * @param alert         kind of alert
 234          * @param ...           alert specific arguments
 235          */
 236         void (*alert)(bus_t *this, alert_t alert, ...);
 237
 238         /**
 239          * Send a IKE_SA state change event to the bus.
 240          *
 241          * @param ike_sa        IKE_SA which changes its state
 242          * @param state         new state IKE_SA changes to
 243          */
 244         void (*ike_state_change)(bus_t *this, ike_sa_t *ike_sa,
 245                                                          ike_sa_state_t state);
 246         /**
 247          * Send a CHILD_SA state change event to the bus.
 248          *
 249          * @param child_sa      CHILD_SA which changes its state
 250          * @param state         new state CHILD_SA changes to
 251          */
 252         void (*child_state_change)(bus_t *this, child_sa_t *child_sa,
 253                                                            child_sa_state_t state);
 254         /**
 255          * Message send/receive hook.
 256          *
 257          * The hook is invoked twice for each message: Once with plain, parsed data
 258          * and once encoded and encrypted.
 259          *
 260          * @param message       message to send/receive
 261          * @param incoming      TRUE for incoming messages, FALSE for outgoing
 262          * @param plain         TRUE if message is parsed and decrypted, FALSE it not
 263          */
 264         void (*message)(bus_t *this, message_t *message, bool incoming, bool plain);
 265
 266         /**
 267          * IKE_SA authorization hook.
 268          *
 269          * @param final         TRUE if this is the final invocation
 270          * @return                      TRUE to establish IKE_SA, FALSE to send AUTH_FAILED
 271          */
 272         bool (*authorize)(bus_t *this, bool final);
 273
 274         /**
 275          * CHILD_SA traffic selector narrowing hook.
 276          *
 277          * @param child_sa      CHILD_SA set up with these traffic selectors
 278          * @param type          type of hook getting invoked
 279          * @param local         list of local traffic selectors to narrow
 280          * @param remote        list of remote traffic selectors to narrow
 281          */
 282         void (*narrow)(bus_t *this, child_sa_t *child_sa, narrow_hook_t type,
 283                                    linked_list_t *local, linked_list_t *remote);
 284
 285         /**
 286          * IKE_SA keymat hook.
 287          *
 288          * @param ike_sa        IKE_SA this keymat belongs to
 289          * @param dh            diffie hellman shared secret
 290          * @param dh_other      others DH public value (IKEv1 only)
 291          * @param nonce_i       initiators nonce
 292          * @param nonce_r       responders nonce
 293          * @param rekey         IKE_SA we are rekeying, if any (IKEv2 only)
 294          * @param shared        shared key used for key derivation (IKEv1-PSK only)
 295          */
 296         void (*ike_keys)(bus_t *this, ike_sa_t *ike_sa, diffie_hellman_t *dh,
 297                                          chunk_t dh_other, chunk_t nonce_i, chunk_t nonce_r,
 298                                          ike_sa_t *rekey, shared_key_t *shared);
 299
 300         /**
 301          * CHILD_SA keymat hook.
 302          *
 303          * @param child_sa      CHILD_SA this keymat is used for
 304          * @param initiator     initiator of the CREATE_CHILD_SA exchange
 305          * @param dh            diffie hellman shared secret
 306          * @param nonce_i       initiators nonce
 307          * @param nonce_r       responders nonce
 308          */
 309         void (*child_keys)(bus_t *this, child_sa_t *child_sa, bool initiator,
 310                                            diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
 311
 312         /**
 313          * IKE_SA up/down hook.
 314          *
 315          * @param ike_sa        IKE_SA coming up/going down
 316          * @param up            TRUE for an up event, FALSE for a down event
 317          */
 318         void (*ike_updown)(bus_t *this, ike_sa_t *ike_sa, bool up);
 319
 320         /**
 321          * IKE_SA rekeying hook.
 322          *
 323          * @param old           rekeyed and obsolete IKE_SA
 324          * @param new           new IKE_SA replacing old
 325          */
 326         void (*ike_rekey)(bus_t *this, ike_sa_t *old, ike_sa_t *new);
 327
 328         /**
 329          * IKE_SA reestablishing hook.
 330          *
 331          * @param old           reestablished and obsolete IKE_SA
 332          * @param new           new IKE_SA replacing old
 333          */
 334         void (*ike_reestablish)(bus_t *this, ike_sa_t *old, ike_sa_t *new);
 335
 336         /**
 337          * CHILD_SA up/down hook.
 338          *
 339          * @param child_sa      CHILD_SA coming up/going down
 340          * @param up            TRUE for an up event, FALSE for a down event
 341          */
 342         void (*child_updown)(bus_t *this, child_sa_t *child_sa, bool up);
 343
 344         /**
 345          * CHILD_SA rekeying hook.
 346          *
 347          * @param old           rekeyed and obsolete CHILD_SA
 348          * @param new           new CHILD_SA replacing old
 349          */
 350         void (*child_rekey)(bus_t *this, child_sa_t *old, child_sa_t *new);
 351
 352         /**
 353          * Destroy the event bus.
 354          */
 355         void (*destroy) (bus_t *this);
 356 };
 357
 358 /**
 359  * Create the event bus which forwards events to its listeners.
 360  *
 361  * @return              event bus instance
 362  */
 363 bus_t *bus_create();
 364
 365 #endif /** BUS_H_ @}*/