57058e292be46553436e404842ed97e405226e81
[strongswan.git] / src / libcharon / plugins / vici / libvici.h
1 /*
2 * Copyright (C) 2014 Martin Willi
3 * Copyright (C) 2014 revosec AG
4 *
5 * Copyright (C) 2015 Andreas Steffen
6 * HSR Hochschule fuer Technik Rapperswil
7
8 * libvici.h is MIT-licensed to simplify reuse, but please note that libvici.c
9 * is not, as it depends on the GPLv2 licensed libstrongswan.
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
27 * THE SOFTWARE.
28 */
29
30 /**
31 * @defgroup libvici libvici
32 * @{ @ingroup vici
33 *
34 * libvici is a low-level client library for the "Versatile IKE Control
35 * Interface" protocol. While it uses libstrongswan and its thread-pool for
36 * asynchronous message delivery, this interface does not directly depend on
37 * libstrongswan interfaces and should be stable.
38 *
39 * This interface provides the following basic functions:
40 *
41 * - vici_init()/vici_deinit(): Library initialization functions
42 * - vici_connect(): Connect to a vici service
43 * - vici_disconnect(): Disconnect from a vici service
44 *
45 * Library initialization implicitly initializes libstrongswan and a small
46 * thread pool.
47 *
48 * Connecting requires an uri, which is currently either a UNIX socket path
49 * prefixed with unix://, or a hostname:port touple prefixed with tcp://.
50 * Passing NULL takes the system default socket path.
51 *
52 * After the connection has been established, request messages can be sent.
53 * Only a single thread may operate on a single connection instance
54 * simultaneously. To construct request messages, use the following functions:
55 *
56 * - vici_add_key_value() / vici_add_key_valuef(): Add key/value pairs
57 * - vici_begin(): Start constructing a new request message
58 * - vici_begin_section(): Open a new section to add contents to
59 * - vici_end_section(): Close a previously opened session
60 * - vici_begin_list(): Open a new list to add list items to
61 * - vici_end_list(): Close a previously opened list
62 * - vici_add_list_item() / vici_add_list_itemf(): Add list item
63 *
64 * Once the request message is complete, it can be sent or cancelled with:
65 *
66 * - vici_submit()
67 * - vici_free_req()
68 *
69 * If submitting a message is successful, a response message is returned. It
70 * can be processed using the following functions:
71 *
72 * - vici_parse(): Parse content type
73 * - vici_parse_name(): Parse name if content type provides one
74 * - vici_parse_name_eq(): Parse name and check if matches string
75 * - vici_parse_value() / vici_parse_value_str(): Parse value for content type
76 * - vici_dump(): Dump a full response to a FILE stream
77 * - vici_free_res(): Free response after use
78 *
79 * Usually vici_parse() is called in a loop, and depending on the returned
80 * type the name and value can be inspected.
81 *
82 * To register or unregister for asynchronous event messages vici_register() is
83 * used. The registered callback gets invoked by an asynchronous thread. To
84 * parse the event message, the vici_parse*() functions can be used.
85 */
86
87 #ifndef LIBVICI_H_
88 #define LIBVICI_H_
89
90 #include <stdio.h>
91
92 /**
93 * Vici versions
94 */
95 typedef enum {
96 /** default version if vici key/value pair is missing in message */
97 VICI_1_0,
98 /** current version, vici key/value pair is explicitly sent in message */
99 VICI_2_0,
100 } vici_version_t;
101
102 /**
103 * Current vici version
104 */
105 #define VICI_VERSION VICI_2_0
106
107 /**
108 * Opaque vici connection contex.
109 */
110 typedef struct vici_conn_t vici_conn_t;
111
112 /**
113 * Opaque vici request message.
114 */
115 typedef struct vici_req_t vici_req_t;
116
117 /**
118 * Opaque vici response/event message.
119 */
120 typedef struct vici_res_t vici_res_t;
121
122 /**
123 * Vici parse result, as returned by vici_parse().
124 */
125 typedef enum {
126 /** encountered a section start, has a name */
127 VICI_PARSE_BEGIN_SECTION,
128 /** encountered a section end */
129 VICI_PARSE_END_SECTION,
130 /** encountered a list start, has a name */
131 VICI_PARSE_BEGIN_LIST,
132 /** encountered a list element, has a value */
133 VICI_PARSE_LIST_ITEM,
134 /** encountered a list end */
135 VICI_PARSE_END_LIST,
136 /** encountered a key/value pair, has a name and a value */
137 VICI_PARSE_KEY_VALUE,
138 /** encountered valid end of message */
139 VICI_PARSE_END,
140 /** parse error */
141 VICI_PARSE_ERROR,
142 } vici_parse_t;
143
144 /**
145 * Callback function invoked for received event messages.
146 *
147 * It is not allowed to call vici_submit() from this callback.
148 *
149 * @param user user data, as passed to vici_connect
150 * @param name name of received event
151 * @param msg associated event message, destroyed by libvici
152 */
153 typedef void (*vici_event_cb_t)(void *user, char *name, vici_res_t *msg);
154
155 /**
156 * Callback function for key/value and list items, invoked by vici_parse_cb().
157 *
158 * @param user user data, as passed to vici_parse_cb()
159 * @param res message currently parsing
160 * @param name name of key or list
161 * @param value value buffer
162 * @param len length of value buffer
163 * @return 0 if parsed successfully
164 */
165 typedef int (*vici_parse_value_cb_t)(void *user, vici_res_t *res, char *name,
166 void *value, int len);
167
168 /**
169 * Callback function for sections, invoked by vici_parse_cb().
170 *
171 * @param user user data, as passed to vici_parse_cb()
172 * @param res message currently parsing
173 * @param name name of the section
174 * @return 0 if parsed successfully
175 */
176 typedef int (*vici_parse_section_cb_t)(void *user, vici_res_t *res, char *name);
177
178 /**
179 * Open a new vici connection.
180 *
181 * On error, NULL is returned and errno is set appropriately.
182 *
183 * @param uri URI to connect to, NULL to use system default
184 * @return opaque vici connection context, NULL on error
185 */
186 vici_conn_t* vici_connect(char *uri);
187
188 /**
189 * Close a vici connection.
190 *
191 * @param conn connection context
192 */
193 void vici_disconnect(vici_conn_t *conn);
194
195 /**
196 * Begin a new vici message request.
197 *
198 * This function always succeeds.
199 *
200 * @param name name of request command
201 * @return request message, to add contents
202 */
203 vici_req_t* vici_begin(char *name);
204
205 /**
206 * Begin a new section in a vici request message.
207 *
208 * @param req request message to create a new section in
209 * @param name name of section to create
210 */
211 void vici_begin_section(vici_req_t *req, char *name);
212
213 /**
214 * End a previously opened section.
215 *
216 * @param req request message to close an open section in
217 */
218 void vici_end_section(vici_req_t *req);
219
220 /**
221 * Add a key/value pair, using an as-is blob as value.
222 *
223 * @param req request message to add key/value pair to
224 * @param key key name of key/value pair
225 * @param buf pointer to blob to add as value
226 * @param len length of value blob to add
227 */
228 void vici_add_key_value(vici_req_t *req, char *key, void *buf, int len);
229
230 /**
231 * Add a key/value pair, setting value from a printf() format string.
232 *
233 * @param req request message to add key/value pair to
234 * @param key key name of key/value pair
235 * @param fmt format string for value
236 * @param ... arguments to format string
237 */
238 void vici_add_key_valuef(vici_req_t *req, char *key, char *fmt, ...);
239
240 /**
241 * Add a vici version key/value pair (not not needed for VICI 1.0)
242 *
243 * @param req request message to add vici version key/value pair to
244 * @param version vici version
245 */
246 void vici_add_version(vici_req_t *req, vici_version_t version);
247
248 /**
249 * Begin a list in a request message.
250 *
251 * After starting a list, only list items can be added until the list gets
252 * closed by vici_end_list().
253 *
254 * @param req request message to begin list in
255 * @param name name of list to begin
256 */
257 void vici_begin_list(vici_req_t *req, char *name);
258
259 /**
260 * Add a list item to a currently open list, using an as-is blob.
261 *
262 * @param req request message to add list item to
263 * @param buf pointer to blob to add as value
264 * @param len length of value blob to add
265 */
266 void vici_add_list_item(vici_req_t *req, void *buf, int len);
267
268 /**
269 * Add a list item to a currently open list, using a printf() format string.
270 *
271 * @param req request message to add list item to
272 * @param fmt format string to create value from
273 * @param ... arguments to format string
274 */
275 void vici_add_list_itemf(vici_req_t *req, char *fmt, ...);
276
277 /**
278 * End a previously opened list in a request message.
279 *
280 * @param req request message to end list in
281 */
282 void vici_end_list(vici_req_t *req);
283
284 /**
285 * Submit a request message, and wait for response.
286 *
287 * The request messages gets cleaned up by this call and gets invalid.
288 * On error, NULL is returned an errno is set to:
289 * - EINVAL if the request is invalid/incomplete
290 * - ENOENT if the command is unknown
291 * - EBADMSG if the response is invalid
292 * - Any other IO related errno
293 *
294 * @param req request message to send
295 * @param conn connection context to send message over
296 * @return response message, NULL on error
297 */
298 vici_res_t* vici_submit(vici_req_t *req, vici_conn_t *conn);
299
300 /**
301 * Cancel a request message started.
302 *
303 * If a request created by vici_begin() does not get submitted using
304 * vici_submit(), it has to get freed using this call.
305 *
306 * @param req request message to clean up
307 */
308 void vici_free_req(vici_req_t *req);
309
310 /**
311 * Dump a message text representation to a FILE stream.
312 *
313 * On error, errno is set to:
314 * - EBADMSG if the message is invalid
315 *
316 * @param res response message to dump
317 * @param label a label to print for this message
318 * @param pretty use pretty print with indentation
319 * @param out FILE to dump to
320 * @return 0 if dumped complete message, 1 on error
321 */
322 int vici_dump(vici_res_t *res, char *label, int pretty, FILE *out);
323
324 /**
325 * Parse next element from a vici response message.
326 *
327 * @param res response message to parse
328 * @return parse result
329 */
330 vici_parse_t vici_parse(vici_res_t *res);
331
332 /**
333 * Parse name tag / key of a previously parsed element.
334 *
335 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
336 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
337 *
338 * The string is valid until vici_free_res() is called.
339 *
340 * On error, errno is set to:
341 *- EINVAL if not in valid parser state
342 *
343 * @param res response message to parse
344 * @return name tag / key, NULL on error
345 */
346 char* vici_parse_name(vici_res_t *res);
347
348 /**
349 * Compare name tag / key of a previusly parsed element.
350 *
351 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
352 * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
353 *
354 * @param res response message to parse
355 * @param name string to compare
356 * @return 1 if name equals, 0 if not
357 */
358 int vici_parse_name_eq(vici_res_t *res, char *name);
359
360 /**
361 * Parse value of a previously parsed element, as a blob.
362 *
363 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
364 * VICI_PARSE_LIST_ITEM.
365 *
366 * The string is valid until vici_free_res() is called.
367 *
368 * On error, errno is set to:
369 * - EINVAL if not in valid parser state
370 *
371 * @param res response message to parse
372 * @param len pointer receiving value length
373 * @return pointer to value, NULL on error
374 */
375 void* vici_parse_value(vici_res_t *res, int *len);
376
377 /**
378 * Parse value of a previously parsed element, as a string.
379 *
380 * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
381 * VICI_PARSE_LIST_ITEM.
382 *
383 * This call is successful only if the value contains no non-printable
384 * characters. The string is valid until vici_free_res() is called.
385 *
386 * On error, errno is set to:
387 * - EBADMSG if value is not a printable string
388 * - EINVAL if not in valid parser state
389 *
390 * @param res response message to parse
391 * @return value as string, NULL on error
392 */
393 char* vici_parse_value_str(vici_res_t *res);
394
395 /**
396 * Parse a complete message with callbacks.
397 *
398 * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
399 * invoked for the current section level only. To descent into sections, call
400 * vici_parse_cb() from within a section callback.
401 *
402 * On error, errno is set to:
403 * - EBADMSG if message encoding invalid
404 * - Any other errno set by the invoked callbacks
405 *
406 * @param res message to parse
407 * @param section callback invoked for each section
408 * @param kv callback invoked for key/value pairs
409 * @param li callback invoked for list items
410 * @param user user data to pass to callbacks
411 * @return 0 if parsing successful
412 */
413 int vici_parse_cb(vici_res_t *res, vici_parse_section_cb_t section,
414 vici_parse_value_cb_t kv, vici_parse_value_cb_t li,
415 void *user);
416
417 /*
418 * Find a blob value in a message for a given key.
419 *
420 * Sections can be selected by prefixing them separated by dots.
421 *
422 * @param res response message to parse
423 * @param len length of returned object
424 * @param fmt printf format string of key and sections
425 * @param ... arguments to format string
426 * @return blob value, having *len bytes, NULL if not found
427 */
428 void *vici_find(vici_res_t *res, int *len, char *fmt, ...);
429
430 /**
431 * Find a string value in a message for a given key.
432 *
433 * Sections can be selected by prefixing them separated by dots.
434 *
435 * @param res response message to parse
436 * @param def default value, if key not found
437 * @param fmt printf format string of key and sections
438 * @param ... arguments to format string
439 * @return string, def if not found
440 */
441 char* vici_find_str(vici_res_t *res, char *def, char *fmt, ...);
442
443 /**
444 * Find an integer value in a message for a given key.
445 *
446 * Sections can be selected by prefixing them separated by dots.
447 *
448 * @param res response message to parse
449 * @param def default value, if key not found
450 * @param fmt printf format string of key and sections
451 * @param ... arguments to format string
452 * @return integer value, def if not found
453 */
454 int vici_find_int(vici_res_t *res, int def, char *fmt, ...);
455
456 /**
457 * Clean up a received response message.
458 *
459 * Event messages get cleaned up by the library, it is not allowed to call
460 * vici_free_res() from within a vici_event_cb_t.
461 *
462 * @param res response message to free
463 */
464 void vici_free_res(vici_res_t *res);
465
466 /**
467 * (Un-)Register for events of a given kind.
468 *
469 * Events callbacks get invoked by a different thread from the libstrongswan
470 * thread pool.
471 * On failure, errno is set to:
472 * - ENOENT if the event name is unknown
473 * - EBADMSG if the response is invalid
474 * - Any other IO related errno
475 *
476 * @param conn connection context
477 * @param name name of event messages to register to
478 * @param cb callback function to register, NULL to unregister
479 * @param user user data passed to callback invocations
480 * @return 0 if registered successfully
481 */
482 int vici_register(vici_conn_t *conn, char *name, vici_event_cb_t cb, void *user);
483
484 /**
485 * Initialize libvici before first time use.
486 */
487 void vici_init();
488
489 /**
490 * Deinitialize libvici after use.
491 */
492 void vici_deinit();
493
494 #endif /** LIBVICI_H_ @}*/