updated Doxyfile
[strongswan.git] / src / charon / bus / bus.h
1 /*
2 * Copyright (C) 2006 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 * $Id$
16 */
17
18 /**
19 * @defgroup bus bus
20 * @{ @ingroup charon
21 */
22
23 #ifndef BUS_H_
24 #define BUS_H_
25
26 typedef enum debug_t debug_t;
27 typedef enum level_t level_t;
28 typedef struct listener_t listener_t;
29 typedef struct bus_t bus_t;
30
31 #include <stdarg.h>
32
33 #include <sa/ike_sa.h>
34 #include <sa/child_sa.h>
35 #include <processing/jobs/job.h>
36
37 /**
38 * Debug message group.
39 */
40 enum debug_t {
41 /** daemon main loop */
42 DBG_DMN,
43 /** IKE_SA_MANAGER */
44 DBG_MGR,
45 /** IKE_SA */
46 DBG_IKE,
47 /** CHILD_SA */
48 DBG_CHD,
49 /** job processing */
50 DBG_JOB,
51 /** configuration backends */
52 DBG_CFG,
53 /** kernel interface */
54 DBG_KNL,
55 /** networking/sockets */
56 DBG_NET,
57 /** message encoding/decoding */
58 DBG_ENC,
59 /** libstrongswan via logging hook */
60 DBG_LIB,
61 /** number of groups */
62 DBG_MAX,
63 /** pseudo group with all groups */
64 DBG_ANY = DBG_MAX,
65 };
66
67 /**
68 * short names of debug message group.
69 */
70 extern enum_name_t *debug_names;
71
72 /**
73 * short names of debug message group, lower case.
74 */
75 extern enum_name_t *debug_lower_names;
76
77 /**
78 * Debug levels used to control output verbosity.
79 */
80 enum level_t {
81 /** absolutely silent */
82 LEVEL_SILENT = -1,
83 /** most important auditing logs */
84 LEVEL_AUDIT = 0,
85 /** control flow */
86 LEVEL_CTRL = 1,
87 /** diagnose problems */
88 LEVEL_DIAG = 2,
89 /** raw binary blobs */
90 LEVEL_RAW = 3,
91 /** including sensitive data (private keys) */
92 LEVEL_PRIVATE = 4,
93 };
94
95 #ifndef DEBUG_LEVEL
96 # define DEBUG_LEVEL 4
97 #endif /* DEBUG_LEVEL */
98
99 #if DEBUG_LEVEL >= 0
100 #define DBG0(group, format, ...) charon->bus->log(charon->bus, group, 0, format, ##__VA_ARGS__)
101 #endif /* DEBUG_LEVEL >= 0 */
102 #if DEBUG_LEVEL >= 1
103 #define DBG1(group, format, ...) charon->bus->log(charon->bus, group, 1, format, ##__VA_ARGS__)
104 #endif /* DEBUG_LEVEL >= 1 */
105 #if DEBUG_LEVEL >= 2
106 #define DBG2(group, format, ...) charon->bus->log(charon->bus, group, 2, format, ##__VA_ARGS__)
107 #endif /* DEBUG_LEVEL >= 2 */
108 #if DEBUG_LEVEL >= 3
109 #define DBG3(group, format, ...) charon->bus->log(charon->bus, group, 3, format, ##__VA_ARGS__)
110 #endif /* DEBUG_LEVEL >= 3 */
111 #if DEBUG_LEVEL >= 4
112 #define DBG4(group, format, ...) charon->bus->log(charon->bus, group, 4, format, ##__VA_ARGS__)
113 #endif /* DEBUG_LEVEL >= 4 */
114
115 #ifndef DBG0
116 # define DBG0(...) {}
117 #endif /* DBG0 */
118 #ifndef DBG1
119 # define DBG1(...) {}
120 #endif /* DBG1 */
121 #ifndef DBG2
122 # define DBG2(...) {}
123 #endif /* DBG2 */
124 #ifndef DBG3
125 # define DBG3(...) {}
126 #endif /* DBG3 */
127 #ifndef DBG4
128 # define DBG4(...) {}
129 #endif /* DBG4 */
130
131
132 /**
133 * Listener interface, listens to events if registered to the bus.
134 */
135 struct listener_t {
136
137 /**
138 * Log a debugging message.
139 *
140 * The implementing signal function returns TRUE to stay registered
141 * to the bus, or FALSE to unregister itself.
142 * Calling bus_t.log() inside of a registered listener is possible,
143 * but the bus does not invoke listeners recursively.
144 *
145 * @param singal kind of the signal (up, down, rekeyed, ...)
146 * @param level verbosity level of the signal
147 * @param thread ID of the thread raised this signal
148 * @param ike_sa IKE_SA associated to the event
149 * @param format printf() style format string
150 * @param args vprintf() style va_list argument list
151 " @return TRUE to stay registered, FALSE to unregister
152 */
153 bool (*log) (listener_t *this, debug_t group, level_t level, int thread,
154 ike_sa_t *ike_sa, char* format, va_list args);
155
156 /**
157 * Handle state changes in an IKE_SA.
158 *
159 * @param ike_sa IKE_SA which changes its state
160 * @param state new IKE_SA state this IKE_SA changes to
161 * @return TRUE to stay registered, FALSE to unregister
162 */
163 bool (*ike_state_change)(listener_t *this, ike_sa_t *ike_sa,
164 ike_sa_state_t state);
165
166 /**
167 * Handle state changes in a CHILD_SA.
168 *
169 * @param ike_sa IKE_SA containing the affected CHILD_SA
170 * @param child_sa CHILD_SA which changes its state
171 * @param state new CHILD_SA state this CHILD_SA changes to
172 * @return TRUE to stay registered, FALSE to unregister
173 */
174 bool (*child_state_change)(listener_t *this, ike_sa_t *ike_sa,
175 child_sa_t *child_sa, child_sa_state_t state);
176
177 /**
178 * Hook called for received/sent messages of an IKE_SA.
179 *
180 * @param ike_sa IKE_SA sending/receving a message
181 * @param message message object
182 * @param incoming TRUE for incoming messages, FALSE for outgoing
183 * @return TRUE to stay registered, FALSE to unregister
184 */
185 bool (*message)(listener_t *this, ike_sa_t *ike_sa, message_t *message,
186 bool incoming);
187
188 /**
189 * Hook called with IKE_SA key material.
190 *
191 * @param ike_sa IKE_SA this keymat belongs to
192 * @param dh diffie hellman shared secret
193 * @param nonce_i initiators nonce
194 * @param nonce_r responders nonce
195 * @param rekey IKE_SA we are rekeying, if any
196 * @return TRUE to stay registered, FALSE to unregister
197 */
198 bool (*ike_keys)(listener_t *this, ike_sa_t *ike_sa, diffie_hellman_t *dh,
199 chunk_t nonce_i, chunk_t nonce_r, ike_sa_t *rekey);
200
201 /**
202 * Hook called with CHILD_SA key material.
203 *
204 * @param ike_sa IKE_SA the child sa belongs to
205 * @param child_sa CHILD_SA this keymat is used for
206 * @param dh diffie hellman shared secret
207 * @param nonce_i initiators nonce
208 * @param nonce_r responders nonce
209 * @return TRUE to stay registered, FALSE to unregister
210 */
211 bool (*child_keys)(listener_t *this, ike_sa_t *ike_sa, child_sa_t *child_sa,
212 diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r);
213 };
214
215 /**
216 * The bus receives events and sends them to all registered listeners.
217 *
218 * Any events sent to are delivered to all registered listeners. Threads
219 * may wait actively to events using the blocking listen() call.
220 */
221 struct bus_t {
222
223 /**
224 * Register a listener to the bus.
225 *
226 * A registered listener receives all events which are sent to the bus.
227 * The listener is passive; the thread which emitted the event
228 * processes the listener routine.
229 *
230 * @param listener listener to register.
231 */
232 void (*add_listener) (bus_t *this, listener_t *listener);
233
234 /**
235 * Unregister a listener from the bus.
236 *
237 * @param listener listener to unregister.
238 */
239 void (*remove_listener) (bus_t *this, listener_t *listener);
240
241 /**
242 * Register a listener and block the calling thread.
243 *
244 * This call registers a listener and blocks the calling thread until
245 * its listeners function returns FALSE. This allows to wait for certain
246 * events. The associated job is executed after the listener has been
247 * registered: This allows to listen on events we initiate with the job,
248 * without missing any events to job may fire.
249 *
250 * @param listener listener to register
251 * @param job job to execute asynchronously when registered, or NULL
252 */
253 void (*listen)(bus_t *this, listener_t *listener, job_t *job);
254
255 /**
256 * Set the IKE_SA the calling thread is using.
257 *
258 * To associate an received log message to an IKE_SA without passing it as
259 * parameter each time, the thread registers the currenlty used IKE_SA
260 * during check-out. Before check-in, the thread unregisters the IKE_SA.
261 * This IKE_SA is stored per-thread, so each thread has its own IKE_SA
262 * registered.
263 *
264 * @param ike_sa ike_sa to register, or NULL to unregister
265 */
266 void (*set_sa) (bus_t *this, ike_sa_t *ike_sa);
267
268 /**
269 * Send a log message to the bus.
270 *
271 * The signal specifies the type of the event occured. The format string
272 * specifies an additional informational or error message with a
273 * printf() like variable argument list.
274 * Use the DBG() macros.
275 *
276 * @param group debugging group
277 * @param level verbosity level of the signal
278 * @param format printf() style format string
279 * @param ... printf() style argument list
280 */
281 void (*log)(bus_t *this, debug_t group, level_t level, char* format, ...);
282
283 /**
284 * Send a log message to the bus using va_list arguments.
285 *
286 * Same as bus_t.signal(), but uses va_list argument list.
287 *
288 * @param group kind of the signal (up, down, rekeyed, ...)
289 * @param level verbosity level of the signal
290 * @param format printf() style format string
291 * @param args va_list arguments
292 */
293 void (*vlog)(bus_t *this, debug_t group, level_t level,
294 char* format, va_list args);
295 /**
296 * Send a IKE_SA state change event to the bus.
297 *
298 * @param ike_sa IKE_SA which changes its state
299 * @param state new state IKE_SA changes to
300 */
301 void (*ike_state_change)(bus_t *this, ike_sa_t *ike_sa,
302 ike_sa_state_t state);
303 /**
304 * Send a CHILD_SA state change event to the bus.
305 *
306 * @param child_sa CHILD_SA which changes its state
307 * @param state new state CHILD_SA changes to
308 */
309 void (*child_state_change)(bus_t *this, child_sa_t *child_sa,
310 child_sa_state_t state);
311 /**
312 * Message send/receive hook.
313 *
314 * @param message message to send/receive
315 * @param incoming TRUE for incoming messages, FALSE for outgoing
316 */
317 void (*message)(bus_t *this, message_t *message, bool incoming);
318
319 /**
320 * IKE_SA keymat hook.
321 *
322 * @param ike_sa IKE_SA this keymat belongs to
323 * @param dh diffie hellman shared secret
324 * @param nonce_i initiators nonce
325 * @param nonce_r responders nonce
326 * @param rekey IKE_SA we are rekeying, if any
327 */
328 void (*ike_keys)(bus_t *this, ike_sa_t *ike_sa, diffie_hellman_t *dh,
329 chunk_t nonce_i, chunk_t nonce_r, ike_sa_t *rekey);
330 /**
331 * CHILD_SA keymat hook.
332 *
333 * @param child_sa CHILD_SA this keymat is used for
334 * @param dh diffie hellman shared secret
335 * @param nonce_i initiators nonce
336 * @param nonce_r responders nonce
337 */
338 void (*child_keys)(bus_t *this, child_sa_t *child_sa, diffie_hellman_t *dh,
339 chunk_t nonce_i, chunk_t nonce_r);
340 /**
341 * Destroy the event bus.
342 */
343 void (*destroy) (bus_t *this);
344 };
345
346 /**
347 * Create the event bus which forwards events to its listeners.
348 *
349 * @return event bus instance
350 */
351 bus_t *bus_create();
352
353 #endif /** BUS_H_ @}*/