src/libcharon/plugins/vici/libvici.h

   1 /*
   2  * Copyright (C) 2014 Martin Willi
   3  * Copyright (C) 2014 revosec AG
   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 libvici libvici
  18  * @{ @ingroup vici
  19  *
  20  * libvici is a low-level client library for the "Versatile IKE Control
  21  * Interface" protocol. While it uses libstrongswan and its thread-pool for
  22  * asynchronous message delivery, this interface does not directly depend on
  23  * libstrongswan interfaces and should be stable.
  24  *
  25  * This interface provides the following basic functions:
  26  *
  27  * - vici_init()/vici_deinit(): Library initialization functions
  28  * - vici_connect(): Connect to a vici service
  29  * - vici_disconnect(): Disconnect from a vici service
  30  *
  31  * Library initialization is basically required to set up libstrongswan and
  32  * a small thread pool. Initialize libstrongswan manually instead.
  33  *
  34  * Connecting requires an uri, which is currently either a UNIX socket path
  35  * prefixed with unix://, or a hostname:port touple prefixed with tcp://.
  36  * Passing NULL takes the system default socket path.
  37  *
  38  * After the connection has been established, request messages can be sent.
  39  * Only a single thread may operate on a single connection instance
  40  * simultaneously. To construct request messages, use the following functions:
  41  *
  42  * - vici_add_key_value() / vici_add_key_valuef(): Add key/value pairs
  43  * - vici_begin(): Start constructing a new request message
  44  * - vici_begin_section(): Open a new section to add contents to
  45  * - vici_end_section(): Close a previously opened session
  46  * - vici_begin_list(): Open a new list to add list items to
  47  * - vici_end_list(): Close a previously opened list
  48  * - vici_add_list_item() / vici_add_list_itemf(): Add list item
  49  *
  50  * Once the request message is complete, it can be sent or cancelled with:
  51  *
  52  * - vici_submit()
  53  * - vici_free_req()
  54  *
  55  * If submitting a message is successful, a response message is returned. It
  56  * can be processed using the following functions:
  57  *
  58  * - vici_parse(): Parse content type
  59  * - vici_parse_name(): Parse name if content type provides one
  60  * - vici_parse_name_eq(): Parse name and check if matches string
  61  * - vici_parse_value() / vici_parse_value_str(): Parse value for content type
  62  * - vici_dump(): Dump a full response to a FILE stream
  63  * - vici_free_res(): Free response after use
  64  *
  65  * Usually vici_parse() is called in a loop, and depending on the returned
  66  * type the name and value can be inspected.
  67  *
  68  * To register or unregister for asynchronous event messages vici_register() is
  69  * used. The registered callback gets invoked by an asynchronous thread. To
  70  * parse the event message, the vici_parse*() functions can be used.
  71  */
  72
  73 #ifndef LIBVICI_H_
  74 #define LIBVICI_H_
  75
  76 #include <stdio.h>
  77
  78 /**
  79  * Opaque vici connection contex.
  80  */
  81 typedef struct vici_conn_t vici_conn_t;
  82
  83 /**
  84  * Opaque vici request message.
  85  */
  86 typedef struct vici_req_t vici_req_t;
  87
  88 /**
  89  * Opaque vici response/event message.
  90  */
  91 typedef struct vici_res_t vici_res_t;
  92
  93 /**
  94  * Vici parse result, as returned by vici_parse().
  95  */
  96 typedef enum {
  97         /** encountered a section start, has a name */
  98         VICI_PARSE_BEGIN_SECTION,
  99         /** encountered a section end */
 100         VICI_PARSE_END_SECTION,
 101         /** encountered a list start, has a name */
 102         VICI_PARSE_BEGIN_LIST,
 103         /** encountered a list element, has a value */
 104         VICI_PARSE_LIST_ITEM,
 105         /** encountered a list end */
 106         VICI_PARSE_END_LIST,
 107         /** encountered a key/value pair, has a name and a value */
 108         VICI_PARSE_KEY_VALUE,
 109         /** encountered valid end of message */
 110         VICI_PARSE_END,
 111         /** parse error */
 112         VICI_PARSE_ERROR,
 113 } vici_parse_t;
 114
 115 /**
 116  * Callback function invoked for received event messages.
 117  *
 118  * It is not allowed to call vici_submit() from this callback.
 119  *
 120  * @param user          user data, as passed to vici_connect
 121  * @param name          name of received event
 122  * @param msg           associated event message, destroyed by libvici
 123  */
 124 typedef void (*vici_event_cb_t)(void *user, char *name, vici_res_t *msg);
 125
 126 /**
 127  * Callback function for key/value and list items, invoked by vici_parse_cb().
 128  *
 129  * @param user          user data, as passed to vici_parse_cb()
 130  * @param res           message currently parsing
 131  * @param name          name of key or list
 132  * @param value         value buffer
 133  * @param len           length of value buffer
 134  * @return                      0 if parsed successfully
 135  */
 136 typedef int     (*vici_parse_value_cb_t)(void *user, vici_res_t *res, char *name,
 137                                                                          void *value, int len);
 138
 139 /**
 140  * Callback function for sections, invoked by vici_parse_cb().
 141  *
 142  * @param user          user data, as passed to vici_parse_cb()
 143  * @param res           message currently parsing
 144  * @param name          name of the section
 145  * @return                      0 if parsed successfully
 146  */
 147 typedef int (*vici_parse_section_cb_t)(void *user, vici_res_t *res, char *name);
 148
 149 /**
 150  * Open a new vici connection.
 151  *
 152  * On error, NULL is returned and errno is set appropriately.
 153  *
 154  * @param uri           URI to connect to, NULL to use system default
 155  * @return                      opaque vici connection context, NULL on error
 156  */
 157 vici_conn_t* vici_connect(char *uri);
 158
 159 /**
 160  * Close a vici connection.
 161  *
 162  * @param conn          connection context
 163  */
 164 void vici_disconnect(vici_conn_t *conn);
 165
 166 /**
 167  * Begin a new vici message request.
 168  *
 169  * This function always succeeds.
 170  *
 171  * @param name          name of request command
 172  * @return                      request message, to add contents
 173  */
 174 vici_req_t* vici_begin(char *name);
 175
 176 /**
 177  * Begin a new section in a vici request message.
 178  *
 179  * @param req           request message to create a new section in
 180  * @param name          name of section to create
 181  */
 182 void vici_begin_section(vici_req_t *req, char *name);
 183
 184 /**
 185  * End a previously opened section.
 186  *
 187  * @param req           request message to close an open section in
 188  */
 189 void vici_end_section(vici_req_t *req);
 190
 191 /**
 192  * Add a key/value pair, using an as-is blob as value.
 193  *
 194  * @param req           request message to add key/value pair to
 195  * @param key           key name of key/value pair
 196  * @param buf           pointer to blob to add as value
 197  * @param len           length of value blob to add
 198  */
 199 void vici_add_key_value(vici_req_t *req, char *key, void *buf, int len);
 200
 201 /**
 202  * Add a key/value pair, setting value from a printf() format string.
 203  *
 204  * @param req           request message to add key/value pair to
 205  * @param key           key name of key/value pair
 206  * @param fmt           format string for value
 207  * @param ...           arguments to format string
 208  */
 209 void vici_add_key_valuef(vici_req_t *req, char *key, char *fmt, ...);
 210
 211 /**
 212  * Begin a list in a request message.
 213  *
 214  * After starting a list, only list items can be added until the list gets
 215  * closed by vici_end_list().
 216  *
 217  * @param req           request message to begin list in
 218  * @param name          name of list to begin
 219  */
 220 void vici_begin_list(vici_req_t *req, char *name);
 221
 222 /**
 223  * Add a list item to a currently open list, using an as-is blob.
 224  *
 225  * @param req           request message to add list item to
 226  * @param buf           pointer to blob to add as value
 227  * @param len           length of value blob to add
 228  */
 229 void vici_add_list_item(vici_req_t *req, void *buf, int len);
 230
 231 /**
 232  * Add a list item to a currently open list, using a printf() format string.
 233  *
 234  * @param req           request message to add list item to
 235  * @param fmt           format string to create value from
 236  * @param ...           arguments to format string
 237  */
 238 void vici_add_list_itemf(vici_req_t *req, char *fmt, ...);
 239
 240 /**
 241  * End a previously opened list in a request message.
 242  *
 243  * @param req           request message to end list in
 244  */
 245 void vici_end_list(vici_req_t *req);
 246
 247 /**
 248  * Submit a request message, and wait for response.
 249  *
 250  * On error, NULL is returned an errno is set appropriately. The request
 251  * messages gets cleaned up by this call and gets invalid.
 252  *
 253  * @param req           request message to send
 254  * @param conn          connection context to send message over
 255  * @return                      response message, NULL on error
 256  */
 257 vici_res_t* vici_submit(vici_req_t *req, vici_conn_t *conn);
 258
 259 /**
 260  * Cancel a request message started.
 261  *
 262  * If a request created by vici_begin() does not get submitted using
 263  * vici_submit(), it has to get freed using this call.
 264  *
 265  * @param req           request message to clean up
 266  */
 267 void vici_free_req(vici_req_t *req);
 268
 269 /**
 270  * Dump a message text representation to a FILE stream.
 271  *
 272  * @param res           response message to dump
 273  * @param label         a label to print for this message
 274  * @param out           FILE to dump to
 275  * @return                      0 if dumped complete message, 1 on error
 276  */
 277 int vici_dump(vici_res_t *res, char *label, FILE *out);
 278
 279 /**
 280  * Parse next element from a vici response message.
 281  *
 282  * @param res           response message to parse
 283  * @return                      parse result
 284  */
 285 vici_parse_t vici_parse(vici_res_t *res);
 286
 287 /**
 288  * Parse name tag / key of a previously parsed element.
 289  *
 290  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
 291  * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
 292  *
 293  * The string is valid until vici_free_res() is called.
 294  *
 295  * @param res           response message to parse
 296  * @return                      name tag / key, NULL on error
 297  */
 298 char* vici_parse_name(vici_res_t *res);
 299
 300 /**
 301  * Compare name tag / key of a previusly parsed element.
 302  *
 303  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE,
 304  * VICI_PARSE_BEGIN_SECTION or VICI_PARSE_BEGIN_LIST.
 305  *
 306  * @param res           response message to parse
 307  * @param name          string to compare
 308  * @return                      1 if name equals, 0 if not
 309  */
 310 int vici_parse_name_eq(vici_res_t *res, char *name);
 311
 312 /**
 313  * Parse value of a previously parsed element, as a blob.
 314  *
 315  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
 316  * VICI_PARSE_LIST_ITEM.
 317  * The string is valid until vici_free_res() is called.
 318  */
 319 void* vici_parse_value(vici_res_t *res, int *len);
 320
 321 /**
 322  * Parse value of a previously parsed element, as a string.
 323  *
 324  * This call is valid only after vici_parse() returned VICI_PARSE_KEY_VALUE or
 325  * VICI_PARSE_LIST_ITEM.
 326  * This call is successful only if the value contains no non-printable
 327  * characters. The string is valid until vici_free_res() is called.
 328  *
 329  * @param res           response message to parse
 330  * @return                      value as string, NULL on error
 331  */
 332 char* vici_parse_value_str(vici_res_t *res);
 333
 334 /**
 335  * Parse a complete message with callbacks.
 336  *
 337  * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
 338  * invoked for the current section level only. To descent into sections, call
 339  * vici_parse_cb() from within a section callback.
 340  *
 341  * @param res           message to parse
 342  * @param section       callback invoked for each section
 343  * @param kv            callback invoked for key/value pairs
 344  * @param li            callback invoked for list items
 345  * @param user          user data to pass to callbacks
 346  * @return                      0 if parsing successful
 347  */
 348 int vici_parse_cb(vici_res_t *res, vici_parse_section_cb_t section,
 349                                   vici_parse_value_cb_t kv, vici_parse_value_cb_t li,
 350                                   void *user);
 351
 352 /*
 353  * Find a blob value in a message for a given key.
 354  *
 355  * Sections can be selected by prefixing them separated by dots.
 356  *
 357  * @param res           response message to parse
 358  * @param len           length of returned object
 359  * @param fmt           printf format string of key and sections
 360  * @param ...           arguments to format string
 361  * @return                      blob value, having *len bytes, NULL if not found
 362  */
 363 void *vici_find(vici_res_t *res, int *len, char *fmt, ...);
 364
 365 /**
 366  * Find a string value in a message for a given key.
 367  *
 368  * Sections can be selected by prefixing them separated by dots.
 369  *
 370  * @param res           response message to parse
 371  * @param def           default value, if key not found
 372  * @param fmt           printf format string of key and sections
 373  * @param ...           arguments to format string
 374  * @return                      string, def if not found
 375  */
 376 char* vici_find_str(vici_res_t *res, char *def, char *fmt, ...);
 377
 378 /**
 379  * Find an integer value in a message for a given key.
 380  *
 381  * Sections can be selected by prefixing them separated by dots.
 382  *
 383  * @param res           response message to parse
 384  * @param def           default value, if key not found
 385  * @param fmt           printf format string of key and sections
 386  * @param ...           arguments to format string
 387  * @return                      integer value, def if not found
 388  */
 389 int vici_find_int(vici_res_t *res, int def, char *fmt, ...);
 390
 391 /**
 392  * Clean up a received response message.
 393  *
 394  * Event messages get cleaned up by the library, it is not allowed to call
 395  * vici_free_res() from within a vici_event_cb_t.
 396  *
 397  * @param res           response message to free
 398  */
 399 void vici_free_res(vici_res_t *res);
 400
 401 /**
 402  * (Un-)Register for events of a given kind.
 403  *
 404  * Events callbacks get invoked by a different thread from the libstrongswan
 405  * thread pool. On failure, errno is set appropriately.
 406  *
 407  * @param conn          connection context
 408  * @param name          name of event messages to register to
 409  * @param cb            callback function to register, NULL to unregister
 410  * @param user          user data passed to callback invocations
 411  * @return                      0 if registered successfully
 412  */
 413 int vici_register(vici_conn_t *conn, char *name, vici_event_cb_t cb, void *user);
 414
 415 /**
 416  * Initialize libvici before first time use.
 417  */
 418 void vici_init();
 419
 420 /**
 421  * Deinitialize libvici after use.
 422  */
 423 void vici_deinit();
 424
 425 #endif /** LIBVICI_H_ @}*/