src/charon/bus/bus.h

   1 /**
   2  * @file bus.h
   3  *
   4  * @brief Interface of bus_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2006 Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef BUS_H_
  24 #define BUS_H_
  25
  26 #include <stdarg.h>
  27
  28 #include <sa/ike_sa.h>
  29 #include <sa/child_sa.h>
  30
  31
  32 typedef enum signal_t signal_t;
  33
  34 /**
  35  * @brief signals ommited by the daemon.
  36  *
  37  * Signaling is for different purporses. First, it allows debugging via
  38  * "debugging signal messages", sencondly, it allows to follow certain
  39  * mechanisms currently going on in the daemon. As we are multithreaded,
  40  * and a multiple messages are involved, it's not possible to follow
  41  * one connection setup without further infrastructure. These infrastructure
  42  * is provided by the bus and the signals the whole daemon ommits to the bus.
  43  *
  44  * @par Schema 1: Signals involved in IKE_SA/CHILD_SA initiation
  45  *
  46  * In the initiation of a IKE- or CHILD_SA is triggered by three possible
  47  * sources: User request, a request from the other peer, or a request
  48  * triggered by the kernel.
  49  * Once the user requests initiation, the SIG_INITIATE signal is ommited.
  50  * This signal contains the IKE_SA that got created. Any further signals
  51  * have the same IKE_SA and are therefore easy to trace.
  52  * If the kernel initiates, a SIG_ACQUIRE is sent over the bus.
  53  * If a new IKE_SA is needed, it is set up. If it succeeds, a
  54  * SIG_IKE_ESTABLISHED is ommitted. If the peer didn't accept our DH
  55  * group, the initiation fails. A SIG_DH_INVALID is sent over the bus. It still
  56  * contains the the old IKE_SA. Shortly afterwards, a SIG_DH_RETRY is ommited.
  57  * It contains the NEW IKE_SA. This mechanism allows us to trace the setup even
  58  * beyond a INVALID_KE_PAYLOUD error.
  59  * If the setup fails, SIG_IKE_ESTABLISH_FAILED is sent.
  60  * After a successful establishment of the IKE_SA, or if an already established
  61  * IKE_SA is reused, the child establishment begins. If it is set up with
  62  * the ike_auth transaction, the SIG_CHILD_ESTABLISHED signal is ommited
  63  * directly after the SIG_IKE_ESTABLISHED signal, as both are set up
  64  * simultaneously. The child setup may fail (in a ike_auth, or in a
  65  * create_child_sa exchange), if so, the SIG_CHID_ESTABLISH_FAILED signal
  66  * is raised.
  67  *
  68  * @verbatim
  69
  70           "ipsec up"  "peer msg"  "kernel acquire"
  71                 |         |          |
  72                 V         |          V
  73             SIG_INITIATE  | SIG_ACQUIRE
  74                        \  | /
  75                         \ |/______________________________________________
  76                          \/________________________________               \
  77                          /\                           \    \              |
  78                         |  |                          |    |              |
  79                         V  V                          |    V              |
  80       SIG_IKE_ESTABLISHED  SIG_IKE_ESTABLISH_FALIED   |  SIG_DH_INVALID   |
  81                         \                |            |    |              |
  82                          \               X            |    V              |
  83                           \___________________________/  SIG_DH_RETRY     |
  84                           /\                               \______________/
  85                          |  |
  86                          V  V
  87      SIG_CHILD_ESTABLISHED  SIG_CHILD_ESTABLISH_FAILED
  88                                           |
  89                                           X
  90    @endverbatim
  91  * Other scenarios are much simpler. Termination is just indicated with
  92  * a simple SIG_CHILD_TERMINATED and/or SIG_IKE_TERMINATED signal. There
  93  * are other signals as SIG_CHILD_ROUTED or SIG_CHILD_UNROUTED. Rekeying is
  94  * also trivial (SIG_IKE_REKEYED/SIG_CHILD_REKEYED), but may contain
  95  * SIG_DH_INVALID...
  96  *
  97  * @ingroup bus
  98  */
  99 enum signal_t {
 100         /** pseudo signal, representing any other signal */
 101         SIG_ANY,
 102
 103         /** debugging messages printed from daemon main loop */
 104         SIG_DBG_DMN,
 105         /** debugging message printed from IKE_SA_MANAGER */
 106         SIG_DBG_MGR,
 107         /** debugging message printed from an IKE_SA */
 108         SIG_DBG_IKE,
 109         /** debugging message printed from a CHILD_SA */
 110         SIG_DBG_CHD,
 111         /** debugging message printed from job processing */
 112         SIG_DBG_JOB,
 113         /** debugging message printed from configuration backends */
 114         SIG_DBG_CFG,
 115         /** debugging message printed from kernel interface */
 116         SIG_DBG_KNL,
 117         /** debugging message printed from networking */
 118         SIG_DBG_NET,
 119         /** debugging message printed from message encoding/decoding */
 120         SIG_DBG_ENC,
 121         /** debugging message printed from libstrongswan via logging hook */
 122         SIG_DBG_LIB,
 123
 124         /** number of debug signals */
 125         SIG_DBG_MAX,
 126
 127         /** initiation started on user request */
 128         SIG_INITIATE,
 129         /** acquiring on kernel request */
 130         SIG_ACQUIRE,
 131
 132         /** an IKE_SA has been established */
 133         SIG_IKE_UP,
 134         /** an IKE_SA has been closed as requested */
 135         SIG_IKE_DOWN,
 136         /** an IKE_SA got deleted due an error */
 137         SIG_IKE_FAILED,
 138         /** an IKE_SA has been rekeyed */
 139         SIG_IKE_REKEY,
 140
 141         /** a CHILD_SA has been established */
 142         SIG_CHILD_UP,
 143         /** a CHILD_SA has been closed as requested */
 144         SIG_CHILD_DOWN,
 145         /** a CHILD_SA got deleted due an error */
 146         SIG_CHILD_FAILED,
 147         /** a CHILD_SA has been rekeyed */
 148         SIG_CHILD_REKEY,
 149         /** a CHILD_SA has been routed */
 150         SIG_CHILD_ROUTE,
 151         /** a CHILD_SA has been unrouted */
 152         SIG_CHILD_UNROUTE,
 153
 154         SIG_MAX
 155 };
 156
 157 /**
 158  * short names of signals using 3 chars
 159  */
 160 extern enum_name_t *signal_names;
 161
 162 typedef enum level_t level_t;
 163
 164 /**
 165  * Signal levels used to control output verbosity.
 166  */
 167 enum level_t {
 168         /** numerical levels from 0 to 4 */
 169         LEVEL_0 = 0,
 170         LEVEL_1 = 1,
 171         LEVEL_2 = 2,
 172         LEVEL_3 = 3,
 173         LEVEL_4 = 4,
 174         /** absolutely silent, no signal is ommited with this level */
 175         LEVEL_SILENT = -1,
 176         /** alias for numberical levels */
 177         LEVEL_AUDIT = LEVEL_0,
 178         LEVEL_CTRL = LEVEL_1,
 179         LEVEL_CTRLMORE = LEVEL_2,
 180         LEVEL_RAW = LEVEL_3,
 181         LEVEL_PRIVATE = LEVEL_4,
 182 };
 183
 184 /**
 185  * @brief Raise a signal for an occured event.
 186  *
 187  * @param sig           signal_t signal description
 188  * @param format        printf() style format string
 189  * @param ...           printf() style agument list
 190  */
 191 #define SIG(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_0, format, ##__VA_ARGS__)
 192
 193 /**
 194  * @brief Log a debug message via the signal bus.
 195  *
 196  * @param signal        signal_t signal description
 197  * @param format        printf() style format string
 198  * @param ...           printf() style agument list
 199  */
 200 #define DBG1(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_1, format, ##__VA_ARGS__)
 201 #define DBG2(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_2, format, ##__VA_ARGS__)
 202 #define DBG3(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_3, format, ##__VA_ARGS__)
 203 #define DBG4(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_4, format, ##__VA_ARGS__)
 204
 205 /**
 206  * @brief Get the type of a signal.
 207  *
 208  * A signal may be a debugging signal with a specific context. They have
 209  * a level specific for their context > 0. All audit signals use the
 210  * type 0. This allows filtering of singals by their type.
 211  *
 212  * @param signal        signal to get the type from
 213  * @return                      type of the signal, between 0..(SIG_DBG_MAX-1)
 214  */
 215 #define SIG_TYPE(sig) (sig > SIG_DBG_MAX ? SIG_ANY : sig)
 216
 217
 218 typedef struct bus_listener_t bus_listener_t;
 219
 220 /**
 221  * @brief Interface for registering at the signal bus.
 222  *
 223  * To receive signals from the bus, the client implementing the
 224  * bus_listener_t interface registers itself at the signal bus.
 225  *
 226  * @ingroup bus
 227  */
 228 struct bus_listener_t {
 229
 230         /**
 231          * @brief Send a signal to a bus listener.
 232          *
 233          * A numerical identification for the thread is included, as the
 234          * associated IKE_SA, if any. Signal specifies the type of
 235          * the event occured. The format string specifies
 236          * an additional informational or error message with a printf() like
 237          * variable argument list. This is in the va_list form, as forwarding
 238          * a "..." parameters to functions is not (cleanly) possible.
 239          *
 240          * @param this          listener
 241          * @param singal        kind of the signal (up, down, rekeyed, ...)
 242          * @param level         verbosity level of the signal
 243          * @param thread        ID of the thread raised this signal
 244          * @param ike_sa        IKE_SA associated to the event
 245          * @param format        printf() style format string
 246          * @param args          vprintf() style va_list argument list
 247          */
 248         void (*signal) (bus_listener_t *this, signal_t signal, level_t level,
 249                                         int thread, ike_sa_t *ike_sa, char* format, va_list args);
 250 };
 251
 252
 253 typedef struct bus_t bus_t;
 254
 255 /**
 256  * @brief Signal bus which sends signals to registered listeners.
 257  *
 258  * The signal bus is not much more than a multiplexer. A listener interested
 259  * in receiving event signals registers at the bus. Any signals sent to
 260  * are delivered to all registered listeners.
 261  * To deliver signals to threads, the blocking listen() call may be used
 262  * to wait for a signal.
 263  *
 264  * @ingroup bus
 265  */
 266 struct bus_t {
 267
 268         /**
 269          * @brief Register a listener to the bus.
 270          *
 271          * A registered listener receives all signals which are sent to the bus.
 272          * The listener is passive; the thread which ommited the signal
 273          * processes the listener routine.
 274          *
 275          * @param this          bus
 276          * @param listener      listener to register.
 277          */
 278         void (*add_listener) (bus_t *this, bus_listener_t *listener);
 279
 280         /**
 281          * @brief Listen actively on the bus.
 282          *
 283          * As we are fully multithreaded, we must provide a mechanism
 284          * for active threads to listen to the bus. With the listen() method,
 285          * a thread waits until a signal occurs, and then processes it.
 286          * To prevent the listen() calling thread to miss signals ommited while
 287          * it processes a signal, registration is required. This is done through
 288          * the set_listen_state() method, see below.
 289          *
 290          * @param this          bus
 291          * @param level         verbosity level of the signal
 292          * @param thread        receives thread number ommited the signal
 293          * @param ike_sa        receives the IKE_SA involved in the signal, or NULL
 294          * @param format        receives the format string supplied with the signal
 295          * @param va_list       receives the variable argument list for format
 296          * @return                      the ommited signal type
 297          */
 298         signal_t (*listen) (bus_t *this, level_t* level, int *thread,
 299                                                 ike_sa_t **ike_sa, char** format, va_list* args);
 300
 301         /**
 302          * @brief Set the listening state of the calling thread.
 303          *
 304          * To prevent message loss for active listeners using listen(), threads
 305          * must register themself to the bus before starting to listen(). When
 306          * a signal occurs, the ommiter waits until all threads with listen_state
 307          * TRUE are waiting in the listen() method to process the signal.
 308          * It is important that a thread with liste_state TRUE calls listen()
 309          * periodically, or sets it's listening state to FALSE; otherwise
 310          * all signal omitting threads get blocked on the bus.
 311          *
 312          * @param this          bus
 313          * @param active        TRUE to set to listening
 314          */
 315         void (*set_listen_state) (bus_t *this, bool active);
 316
 317         /**
 318          * @brief Set the IKE_SA the calling thread is using.
 319          *
 320          * To associate an received signal to an IKE_SA without passing it as
 321          * parameter each time, the thread registers it's used IKE_SA each
 322          * time it checked it out. Before checking it in, the thread unregisters
 323          * the IKE_SA (by passing NULL). This IKE_SA is stored per-thread, so each
 324          * thread has one IKE_SA registered (or not).
 325          *
 326          * @param this          bus
 327          * @param ike_sa        ike_sa to register, or NULL to unregister
 328          */
 329         void (*set_sa) (bus_t *this, ike_sa_t *ike_sa);
 330
 331         /**
 332          * @brief Send a signal to the bus.
 333          *
 334          * The signal specifies the type of the event occured. The format string
 335          * specifies an additional informational or error message with a
 336          * printf() like variable argument list.
 337          * Some useful macros are available to shorten this call.
 338          * @see SIG(), DBG1()
 339          *
 340          * @param this          bus
 341          * @param singal        kind of the signal (up, down, rekeyed, ...)
 342          * @param level         verbosity level of the signal
 343          * @param format        printf() style format string
 344          * @param ...           printf() style argument list
 345          */
 346         void (*signal) (bus_t *this, signal_t signal, level_t level, char* format, ...);
 347
 348         /**
 349          * @brief Send a signal to the bus using va_list arguments.
 350          *
 351          * Same as bus_t.signal(), but uses va_list argument list.
 352          *
 353          * @param this          bus
 354          * @param singal        kind of the signal (up, down, rekeyed, ...)
 355          * @param level         verbosity level of the signal
 356          * @param format        printf() style format string
 357          * @param args          va_list arguments
 358          */
 359         void (*vsignal) (bus_t *this, signal_t signal, level_t level, char* format, va_list args);
 360
 361         /**
 362          * @brief Destroy the signal bus.
 363          *
 364          * @param this          bus to destroy
 365          */
 366         void (*destroy) (bus_t *this);
 367 };
 368
 369 /**
 370  * @brief Create the signal bus which multiplexes signals to its listeners.
 371  *
 372  * @return              signal bus instance
 373  *
 374  * @ingroup bus
 375  */
 376 bus_t *bus_create();
 377
 378 #endif /* BUS_H_ */