src/libcharon/plugins/vici/README.md

   1 # The Versatile IKE Control Interface (VICI) protocol #
   2
   3 The vici plugin implements the server side of an IPC protocol to configure,
   4 monitor and control the IKE daemon charon. It uses request/response and event
   5 messages to communicate over a reliable stream based transport.
   6
   7 ## Transport protocol ##
   8
   9 To provide the service, the plugin opens a listening socket using a reliable,
  10 stream based transport. charon relies on the different stream service
  11 abstractions provided by libstrongswan, such as TCP and UNIX sockets.
  12
  13 A client connects to this service to access functionality. It may send an
  14 arbitrary number of packets over the connection before closing it.
  15
  16 To exchange data, the transport protocol is segmented into byte sequences.
  17 Each byte sequence is prefixed by a 32-bit length header in network order,
  18 followed by the data. The maximum segment length is currently limited to 512KB
  19 of data, and the length field contains the length of the data only, not
  20 including the length field itself.
  21
  22 The order of byte sequences must be strict, byte sequences must arrive in the
  23 same order as sent.
  24
  25 ## Packet layer ##
  26
  27 Within the byte sequences defined by the transport layer, both the client
  28 and the server can exchange packets. The type of packet defines its structure
  29 and purpose. The packet type is a 8-bit identifier, and is the first byte
  30 in a transport layer byte sequence. The length of the packet is given by the
  31 transport layer.
  32
  33 While a packet type may define the format of the wrapped data freely, currently
  34 all types either contain a name, a message or both. The following packet types
  35 are currently defined:
  36
  37 * _CMD_REQUEST = 0_: A named request message
  38 * _CMD_RESPONSE = 1_: An unnamed response message for a request
  39 * _CMD_UNKNOWN = 2_: An unnamed response if requested command is unknown
  40 * _EVENT_REGISTER = 3_: A named event registration request
  41 * _EVENT_UNREGISTER = 4_: A named event deregistration request
  42 * _EVENT_CONFIRM = 5_: An unnamed response for successful event (de-)registration
  43 * _EVENT_UNKNOWN = 6_: A unnamed response if event (de-)registration failed
  44 * _EVENT = 7_: A named event message
  45
  46 For packets having a named type, after the packet type an 8-bit length header
  47 of the name follows, indicating the string length in bytes of the name tag, not
  48 including the length field itself. The name is an ASCII string that is not
  49 null-terminated.
  50
  51 The rest of the packet forms the exchanged message, the length is determined
  52 by the transport byte sequence length, subtracting the packet type and
  53 the optional name tag in some messages.
  54
  55 ### Commands ###
  56
  57 Commands are currently always requested by the client. The server replies with
  58 a response, or with a CMD_UNKNOWN failure message to let the client know
  59 that it does not have a handler for such a command. There is no sequence number
  60 to associate responses to requests, so only one command can be active at
  61 a time on a single connection.
  62
  63 ### Events ###
  64
  65 To receive event messages, the client explicitly registers for events by name,
  66 and also unregisters if it does not want to receive events of the named kind
  67 anymore. The server confirms event registration using EVENT_CONFIRM, or
  68 indicates that there is no such event source with EVENT_UNKNOWN.
  69
  70 Events may get raised at any time while registered, even during an active
  71 request command. This mechanism is used to feed continuous data during a request,
  72 for example.
  73
  74 ## Message format ##
  75
  76 The defined packet types optionally wrap a message with additional data.
  77 Messages are currently used in CMD_REQUEST/CMD_RESPONSE, and in EVENT packets.
  78 A message uses a hierarchial tree of sections. Each section (or the implicit
  79 root section) contains an arbitrary set of key/value pairs, lists and
  80 sub-sections. The length of a message is not part of the message itself, but
  81 the wrapping layer, usually calculated from the transport byte sequence length.
  82
  83 The message encoding consists of a sequence of elements. Each element starts
  84 with the element type, optionally followed by an element name and/or an element
  85 value. Currently the following message element types are defined:
  86
  87 * _SECTION_START = 1_: Begin a new section having a name
  88 * _SECTION_END = 2_: End a previously started section
  89 * _KEY_VALUE = 3_: Define a value for a named key in the current section
  90 * _LIST_START = 4_: Begin a named list for list items
  91 * _LIST_ITEM = 5_: Define an unnamed item value in the current list
  92 * _LIST_END = 6_: End a previously started list
  93
  94 Types are encoded as 8-bit values. Types having a name (SECTION_START,
  95 KEY_VALUE and LIST_START) have an ASCII string following the type, which itself
  96 uses an 8-bit length header. The string must not be null-terminated, the string
  97 length does not include the length field itself.
  98
  99 Types having a value (KEY_VALUE and LIST_ITEM) have a raw blob sequence,
 100 prefixed with a 16-bit network order length. The blob follows the type or the
 101 name tag if available, the length defined by the length field does not include
 102 the length field itself.
 103
 104 The interpretation of any value is not defined by the message format; it can
 105 take arbitrary blobs. The application may specify types for specific keys, such
 106 as strings or integer representations. The vici plugin currently uses
 107 non-null terminated strings as values only; numbers get encoded as strings.
 108
 109 ### Sections ###
 110
 111 Sections may be opened in the implicit root section, or any previously section.
 112 They can be nested to arbitrary levels. A SECTION_END marker always closes
 113 the last opened section; SECTION_START and SECTION_END items must be balanced
 114 in a valid message.
 115
 116 ### Key/Values ###
 117
 118 Key/Value pair elements may appear in the implicit root section or any explicit
 119 sub-section at any level. Key names must be unique in the current section, use
 120 lists to define multiple values for a key. Key/values may not appear in lists,
 121 use a sub-section instead.
 122
 123 ### Lists ###
 124
 125 Lists may appear at the same locations as Key/Values, and may not be nested.
 126 Only a single list may be opened at the same time, and all lists must be closed
 127 in valid messages. After opening a list, only list items may appear before the
 128 list closing element. Empty lists are allowed, list items may appear within
 129 lists only.
 130
 131 ### Encoding example ###
 132
 133 Consider the following structure using pseudo-markup for this example:
 134
 135         key1 = value1
 136         section1 = {
 137                 sub-section = {
 138                         key2 = value2
 139                 }
 140                 list1 = [ item1, item2 ]
 141         }
 142
 143 The example above reprensents a valid tree structure, that gets encoded as
 144 the following C array:
 145
 146         char msg[] = {
 147                 /* key1 = value1 */
 148                 3, 4,'k','e','y','1', 0,6,'v','a','l','u','e','1',
 149                 /* section1 */
 150                 1, 8,'s','e','c','t','i','o','n','1',
 151                 /* sub-section */
 152                 1, 11,'s','u','b','-','s','e','c','t','i','o','n',
 153                 /* key2 = value2 */
 154                 3, 4,'k','e','y','2', 0,6,'v','a','l','u','e','2',
 155                 /* sub-section end */
 156                 2,
 157                 /* list1 */
 158                 4, 5, 'l','i','s','t','1',
 159                 /* item1 */
 160                 5, 0,5,'i','t','e','m','1',
 161                 /* item2 */
 162                 5, 0,5,'i','t','e','m','2',
 163                 /* list1 end */
 164                 6,
 165                 /* section1 end */
 166                 2,
 167         };
 168
 169 ## Client-initiated commands ##
 170
 171 Based on the packet layer, VICI implements commands requested by the client
 172 and responded to by the server using named _CMD_REQUEST_ and _CMD_RESPONSE_
 173 packets wrapping messages. The request message may contain command arguments,
 174 the response message the reply.
 175
 176 Some commands use response streaming, that is, a request triggers a series of
 177 events to consecutively stream data to the client before the response message
 178 completes the stream. A client must register for the appropriate event to
 179 receive the stream, and unregister after the response has been received.
 180
 181 The following client issued commands with the appropriate command input and
 182 output messages are currently defined:
 183
 184 ### version() ###
 185
 186 Returns daemon and system specific version information.
 187
 188         {} => {
 189                 daemon = <IKE daemon name>
 190                 version = <strongSwan version>
 191                 sysname = <operating system name>
 192                 release = <operating system release>
 193                 machine = <hardware identifier>
 194         }
 195
 196 ### stats() ###
 197
 198 Returns IKE daemon statistics and load information.
 199
 200         {} => {
 201                 uptime = {
 202                         running = <relative uptime in human-readable form>
 203                         since = <absolute startup time>
 204                 }
 205                 workers = {
 206                         total = <total number of worker threads>
 207                         idle = <worker threads currently idle>
 208                         active = {
 209                                 critical = <threads processing "critical" priority jobs>
 210                                 high = <threads processing "high" priority jobs>
 211                                 medium = <threads processing "medium" priority jobs>
 212                                 low = <threads processing "low" priority jobs>
 213                         }
 214                 }
 215                 queues = {
 216                         critical = <jobs queued with "critical" priority>
 217                         high = <jobs queued with "high" priority>
 218                         medium = <jobs queued with "medium" priority>
 219                         low = <jobs queued with "low" priority>
 220                 }
 221                 scheduled = <number of jobs scheduled for timed execution>
 222                 ikesas = {
 223                         total = <total number of IKE_SAs active>
 224                         half-open = <number of IKE_SAs in half-open state>
 225                 }
 226                 plugins = [
 227                         <names of loaded plugins>
 228                 ]
 229                 mem = { # available if built with leak-detective or on Windows
 230                         total = <total heap memory usage in bytes>
 231                         allocs = <total heap allocation blocks>
 232                         <heap-name>* = { # on Windows only
 233                                 total = <heap memory usage in bytes by this heap>
 234                                 allocs = <allocated blocks for this heap>
 235                         }
 236                 }
 237                 mallinfo = { # available with mallinfo() support
 238                         sbrk = <non-mmaped space available>
 239                         mmap = <mmaped space available>
 240                         used = <total number of bytes used>
 241                         free = <available but unused bytes>
 242                 }
 243         }
 244
 245 ### reload-settings() ###
 246
 247 Reloads _strongswan.conf_ settings and all plugins supporting configuration
 248 reload.
 249
 250         {} => {
 251                 success = <yes or no>
 252                 errmsg = <error string on failure>
 253         }
 254
 255 ### initiate() ###
 256
 257 Initiates an SA while streaming _control-log_ events.
 258
 259         {
 260                 child = <CHILD_SA configuration name to initiate>
 261                 timeout = <timeout in seconds before returning>
 262                 loglevel = <loglevel to issue "control-log" events for>
 263         } => {
 264                 success = <yes or no>
 265                 errmsg = <error string on failure or timeout>
 266         }
 267
 268 ### terminate() ###
 269
 270 Terminates an SA while streaming _control-log_ events.
 271
 272         {
 273                 child = <terminate a CHILD_SA by configuration name>
 274                 ike = <terminate an IKE_SA by configuration name>
 275                 child_id = <terminate a CHILD_SA by its reqid>
 276                 ike_id = <terminate an IKE_SA by its unique id>
 277                 timeout = <timeout in seconds before returning>
 278                 loglevel = <loglevel to issue "control-log" events for>
 279         } => {
 280                 success = <yes or no>
 281                 errmsg = <error string on failure or timeout>
 282         }
 283
 284 ### install() ###
 285
 286 Install a trap, drop or bypass policy defined by a CHILD_SA config.
 287
 288         {
 289                 child = <CHILD_SA configuration name to install>
 290         } => {
 291                 success = <yes or no>
 292                 errmsg = <error string on failure>
 293         }
 294
 295 ### uninstall() ###
 296
 297 Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
 298
 299         {
 300                 child = <CHILD_SA configuration name to install>
 301         } => {
 302                 success = <yes or no>
 303                 errmsg = <error string on failure>
 304         }
 305
 306 ### list-sas() ###
 307
 308 Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
 309 events.
 310
 311         {
 312                 noblock = <use non-blocking mode if key is set>
 313                 ike = <filter listed IKE_SAs by its name>
 314                 ike_id = <filter listed IKE_SA by its unique id>
 315         } => {
 316                 # completes after streaming list-sa events
 317         }
 318
 319 ### list-policies() ###
 320
 321 List currently installed trap, drop and bypass policies by streaming
 322 _list-policy_ events.
 323
 324         {
 325                 drop = <set to yes to list drop policies>
 326                 pass = <set to yes to list bypass policies>
 327                 trap = <set to yes to list trap policies>
 328                 child = <filter by CHILD_SA configuration name>
 329         } => {
 330                 # completes after streaming list-sa events
 331         }
 332
 333 ### list-conns() ###
 334
 335 List currently loaded connections by streaming _list-conn_ events. This
 336 call includes all connections known by the daemon, not only those loaded
 337 over vici.
 338
 339         {
 340                 ike = <list connections matching a given configuration name only>
 341         } => {
 342                 # completes after streaming list-conn events
 343         }
 344
 345 ### get-conns() ###
 346
 347 Return a list of connection names loaded exclusively over vici, not including
 348 connections found in other backends.
 349
 350         {} => {
 351                 conns = [
 352                         <list of connection names>
 353                 ]
 354         }
 355
 356 ### list-certs() ###
 357
 358 List currently loaded certificates by streaming _list-cert_ events. This
 359 call includes all certificates known by the daemon, not only those loaded
 360 over vici.
 361
 362         {
 363                 type = <certificate type to filter for, or ANY>
 364                 subject = <set to list only certificates having subject>
 365         } => {
 366                 # completes after streaming list-cert events
 367         }
 368
 369 ### load-conn() ###
 370
 371 Load a single connection definition into the daemon. An existing connection
 372 with the same name gets updated or replaced.
 373
 374         {
 375                 <IKE_SA config name> = {
 376                         # IKE configuration parameters with authentication and CHILD_SA
 377                         # subsections. Refer to swanctl.conf(5) for details.
 378                 } => {
 379                         success = <yes or no>
 380                         errmsg = <error string on failure>
 381                 }
 382         }
 383
 384 ### unload-conn() ###
 385
 386 Unload a previously loaded connection definition by name.
 387
 388         {
 389                 name = <IKE_SA config name>
 390         } => {
 391                 success = <yes or no>
 392                 errmsg = <error string on failure>
 393         }
 394
 395 ### load-cert() ###
 396
 397 Load a certificate into the daemon.
 398
 399         {
 400                 type = <certificate type, X509|X509CA|X509AA|X509CRL|X509AC>
 401                 data = <PEM or DER encoded certificate data>
 402         } => {
 403                 success = <yes or no>
 404                 errmsg = <error string on failure>
 405         }
 406
 407 ### load-key() ###
 408
 409 Load a private key into the daemon.
 410
 411         {
 412                 type = <private key type, RSA|ECDSA>
 413                 data = <PEM or DER encoded key data>
 414         } => {
 415                 success = <yes or no>
 416                 errmsg = <error string on failure>
 417         }
 418
 419 ### load-shared() ###
 420
 421 Load a shared IKE PSK, EAP or XAuth secret into the daemon.
 422
 423         {
 424                 type = <private key type, IKE|EAP|XAUTH>
 425                 data = <raw shared key data>
 426                 owners = [
 427                         <list of shared key owner identities>
 428                 ]
 429         } => {
 430                 success = <yes or no>
 431                 errmsg = <error string on failure>
 432         }
 433
 434 ### clear-creds() ###
 435
 436 Clear all loaded certificate, private key and shared key credentials. This
 437 affects only credentials loaded over vici, but additionally flushes the
 438 credential cache.
 439
 440         {} => {
 441                 success = <yes or no>
 442                 errmsg = <error string on failure>
 443         }
 444
 445 ### load-pool() ###
 446
 447 Load an in-memory virtual IP and configuration attribute pool. Existing
 448 pools with the same name get updated, if possible.
 449
 450         {
 451                 <pool name> = {
 452                         addrs = <subnet of virtual IP pool addresses>
 453                         <attribute type>* = [
 454                                 # attribute type is one of address, dns, nbns, dhcp, netmask,
 455                                 # server, subnet, split_include, split_exclude or a numerical
 456                                 # attribute type identifier.
 457                                 <list of attributes for type>
 458                         ]
 459                 }
 460         } => {
 461                 success = <yes or no>
 462                 errmsg = <error string on failure>
 463         }
 464
 465 ### unload-pool() ###
 466
 467 Unload a previously loaded virtual IP and configuration attribute pool.
 468 Unloading fails for pools with leases currently online.
 469
 470         {
 471                 name = <virtual IP address pool to delete>
 472         } => {
 473                 success = <yes or no>
 474                 errmsg = <error string on failure>
 475         }
 476
 477 ### get-pools() ###
 478
 479 List the currently loaded pools.
 480
 481         {} => {
 482                 <pool name>* = {
 483                         base = <virtual IP pool base address>
 484                         size = <total number of addresses in the pool>
 485                         online = <number of leases online>
 486                         offline = <number of leases offline>
 487                 }
 488         }
 489
 490 ## Server-issued events ##
 491
 492 Based on the packet layer, the vici plugin raises event messages using named
 493 EVENT packets wrapping messages. The message contains event details.
 494
 495 ### log ###
 496
 497 The _log_ event is issued to registered clients for each debug log message.
 498 This event is not associated with a command.
 499
 500         {
 501                 group = <subsystem identifier for debug message>
 502                 level = <log level, 0-4>
 503                 thread = <numerical thread identifier issuing the log message>
 504                 ikesa-name = <name of IKE_SA, if log is associated with any>
 505                 ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
 506                 msg = <log message text>
 507         }
 508
 509 ### control-log ###
 510
 511 The _control-log_ event is issued for log events during active _initiate_ or
 512 _terminate_ commands. It is issued only to clients currently having such
 513 a command active.
 514
 515         {
 516                 group = <subsystem identifier for debug message>
 517                 level = <log level, 0-4>
 518                 ikesa-name = <name of IKE_SA, if log associated with any>
 519                 ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
 520                 msg = <log message text>
 521         }
 522
 523 ### list-sa ###
 524
 525 The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
 526 command.
 527
 528         {
 529                 <IKE_SA config name> = {
 530                         uniqueid = <IKE_SA unique identifier>
 531                         version = <IKE version, 1 or 2>
 532                         state = <IKE_SA state name>
 533                         local-host = <local IKE endpoint address>
 534                         local-id = <local IKE identity>
 535                         remote-host = <remote IKE endpoint address>
 536                         remote-id = <remote IKE identity>
 537                         remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
 538                         remote-eap-id = <remote EAP identity, if EAP-authenticated>
 539                         initiator = <yes, if initiator of IKE_SA>
 540                         initiator-spi = <hex encoded initiator SPI / cookie>
 541                         responder-spi = <hex encoded responder SPI / cookie>
 542                         encr-alg = <IKE encryption algorithm string>
 543                         encr-keysize = <key size for encr-alg, if applicable>
 544                         integ-alg = <IKE integrity algorithm string>
 545                         integ-keysize = <key size for encr-alg, if applicable>
 546                         prf-alg = <IKE pseudo random function string>
 547                         dh-group = <IKE Diffie-Hellman group string>
 548                         established = <seconds the IKE_SA has been established>
 549                         rekey-time = <seconds before IKE_SA gets rekeyed>
 550                         reauth-time = <seconds before IKE_SA gets re-authenticated>
 551                         tasks-queued = [
 552                                 <list of currently queued tasks for execution>
 553                         ]
 554                         tasks-active = [
 555                                 <list of tasks currently initiating actively>
 556                         ]
 557                         tasks-passive = [
 558                                 <list of tasks currently handling passively>
 559                         ]
 560                         child-sas = {
 561                                 <child-sa-name>* = {
 562                                         uniqueid = <unique CHILD_SA identifier>
 563                                         reqid = <reqid of CHILD_SA>
 564                                         state = <state string of CHILD_SA>
 565                                         mode = <IPsec mode, tunnel|transport|beet>
 566                                         protocol = <IPsec protocol AH|ESP>
 567                                         encap = <yes if using UDP encapsulation>
 568                                         spi-in = <hex encoded inbound SPI>
 569                                         spi-out = <hex encoded outbound SPI>
 570                                         cpi-in = <hex encoded inbound CPI, if using compression>
 571                                         cpi-out = <hex encoded outbound CPI, if using compression>
 572                                         encr-alg = <ESP encryption algorithm name, if any>
 573                                         encr-keysize = <ESP encryption key size, if applicable>
 574                                         integ-alg = <ESP or AH integrity algorithm name, if any>
 575                                         integ-keysize = <ESP or AH integrity key size, if applicable>
 576                                         prf-alg = <CHILD_SA pseudo random function name>
 577                                         dh-group = <CHILD_SA PFS rekeying DH group name, if any>
 578                                         esn = <1 if using extended sequence numbers>
 579                                         bytes-in = <number of input bytes processed>
 580                                         packets-in = <number of input packets processed>
 581                                         use-in = <seconds since last inbound packet, if any>
 582                                         bytes-out = <number of output bytes processed>
 583                                         packets-out = <number of output packets processed>
 584                                         use-out = <seconds since last outbound packet, if any>
 585                                         rekey-time = <seconds before CHILD_SA gets rekeyed>
 586                                         life-time = <seconds before CHILD_SA expires>
 587                                         install-time = <seconds the CHILD_SA has been installed>
 588                                         local-ts = [
 589                                                 <list of local traffic selectors>
 590                                         ]
 591                                         remote-ts = [
 592                                                 <list of remote traffic selectors>
 593                                         ]
 594                                 }
 595                         }
 596                 }
 597         }
 598
 599 ### list-policy ###
 600
 601 The _list-policy_ event is issued to stream installed policies during an active
 602 _list-policies_ command.
 603
 604         {
 605                 <child-sa-config-name> = {
 606                         mode = <policy mode, tunnel|transport|pass|drop>
 607                         local-ts = [
 608                                 <list of local traffic selectors>
 609                         ]
 610                         remote-ts = [
 611                                 <list of remote traffic selectors>
 612                         ]
 613                 }
 614         }
 615
 616 ### list-conn ###
 617
 618 The _list-conn_ event is issued to stream loaded connection during an active
 619 _list-conns_ command.
 620
 621         {
 622                 <IKE_SA connection name> = {
 623                         local_addrs = [
 624                                 <list of valid local IKE endpoint addresses>
 625                         ]
 626                         remote_addrs = [
 627                                 <list of valid remote IKE endpoint addresses>
 628                         ]
 629                         version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
 630
 631                         local*, remote* = { # multiple local and remote auth sections
 632                                 class = <authentication type>
 633                                 eap-type = <EAP type to authenticate if when using EAP>
 634                                 eap-vendor = <EAP vendor for type, if any>
 635                                 xauth = <xauth backend name>
 636                                 revocation = <revocation policy>
 637                                 id = <IKE identity>
 638                                 aaa_id = <AAA authentication backend identity>
 639                                 eap_id = <EAP identity for authentication>
 640                                 xauth_id = <XAuth username for authentication>
 641                                 groups = [
 642                                         <group membership required to use connection>
 643                                 ]
 644                                 certs = [
 645                                         <certificates allowed for authentication>
 646                                 ]
 647                                 cacerts = [
 648                                         <CA certificates allowed for authentication>
 649                                 ]
 650                         }
 651                         children = {
 652                                 <CHILD_SA config name>* = {
 653                                         mode = <IPsec mode>
 654                                         local-ts = [
 655                                                 <list of local traffic selectors>
 656                                         ]
 657                                         remote-ts = [
 658                                                 <list of remote traffic selectors>
 659                                         ]
 660                                 }
 661                         }
 662                 }
 663         }
 664
 665 ### list-cert ###
 666
 667 The _list-cert_ event is issued to stream loaded certificates during an active
 668 _list-certs_ command.
 669
 670         {
 671                 type = <certificate type>
 672                 has_privkey = <set if a private key for the certificate is available>
 673                 data = <ASN1 encoded certificate data>
 674         }
 675
 676
 677 # libvici C client library #
 678
 679 libvici is the reference implementation of a C client library implementing
 680 the vici protocol. It builds upon libstrongswan, but provides a stable API
 681 to implement client applications in the C programming language. libvici uses
 682 the libstrongswan thread pool to deliver event messages asynchronously.
 683
 684 ## Connecting to the daemon ##
 685
 686 This example shows how to connect to the daemon using the default URI, and
 687 then perform proper cleanup:
 688
 689         #include <stdio.h>
 690         #include <errno.h>
 691         #include <string.h>
 692
 693         #include <libvici.h>
 694
 695         int main(int argc, char *argv[])
 696         {
 697                 vici_conn_t *conn;
 698                 int ret = 0;
 699
 700                 vici_init();
 701                 conn = vici_connect(NULL);
 702                 if (conn)
 703                 {
 704                         /* do stuff */
 705                         vici_disconnect(conn);
 706                 }
 707                 else
 708                 {
 709                         ret = errno;
 710                         fprintf(stderr, "connecting failed: %s\n", strerror(errno));
 711                 }
 712                 vici_deinit();
 713                 return ret;
 714         }
 715
 716 ## A simple client request ##
 717
 718 In the following example, a simple _version_ request is issued to the daemon
 719 and the result is printed:
 720
 721         int get_version(vici_conn_t *conn)
 722         {
 723                 vici_req_t *req;
 724                 vici_res_t *res;
 725                 int ret = 0;
 726
 727                 req = vici_begin("version");
 728                 res = vici_submit(req, conn);
 729                 if (res)
 730                 {
 731                         printf("%s %s (%s, %s, %s)\n",
 732                                 vici_find_str(res, "", "daemon"),
 733                                 vici_find_str(res, "", "version"),
 734                                 vici_find_str(res, "", "sysname"),
 735                                 vici_find_str(res, "", "release"),
 736                                 vici_find_str(res, "", "machine"));
 737                         vici_free_res(res);
 738                 }
 739                 else
 740                 {
 741                         ret = errno;
 742                         fprintf(stderr, "version request failed: %s\n", strerror(errno));
 743                 }
 744                 return ret;
 745         }
 746
 747 ## A request with event streaming and callback parsing ##
 748
 749 In this more advanced example, the _list-conns_ command is used to stream
 750 loaded connections with the _list-conn_ event. The event message is parsed
 751 with a simple callback to print the connection name:
 752
 753         int conn_cb(void *null, vici_res_t *res, char *name)
 754         {
 755                 printf("%s\n", name);
 756                 return 0;
 757         }
 758
 759         void list_cb(void *null, char *name, vici_res_t *res)
 760         {
 761                 if (vici_parse_cb(res, conn_cb, NULL, NULL, NULL) != 0)
 762                 {
 763                         fprintf(stderr, "parsing failed: %s\n", strerror(errno));
 764                 }
 765         }
 766
 767         int list_conns(vici_conn_t *conn)
 768         {
 769                 vici_req_t *req;
 770                 vici_res_t *res;
 771                 int ret = 0;
 772
 773                 if (vici_register(conn, "list-conn", list_cb, NULL) == 0)
 774                 {
 775                         req = vici_begin("list-conns");
 776                         res = vici_submit(req, conn);
 777                         if (res)
 778                         {
 779                                 vici_free_res(res);
 780                         }
 781                         else
 782                         {
 783                                 ret = errno;
 784                                 fprintf(stderr, "request failed: %s\n", strerror(errno));
 785                         }
 786                         vici_register(conn, "list-conn", NULL, NULL);
 787                 }
 788                 else
 789                 {
 790                         ret = errno;
 791                         fprintf(stderr, "registration failed: %s\n", strerror(errno));
 792                 }
 793                 return ret;
 794         }
 795
 796 ## API documentation ##
 797
 798 More information about the libvici API is available in the _libvici.h_ header
 799 file or the generated Doxygen documentation.
 800
 801 # vici ruby gem #
 802
 803 The _vici ruby gem_ is a pure ruby implementation of the VICI protocol to
 804 implement client applications. It is provided in the _ruby_ subdirectory, and
 805 gets built and installed if strongSwan has been _./configure_'d with
 806 _--enable-vici_ and _--enable-ruby-gems_.
 807
 808 The _Connection_ class from the _Vici_ module provides the high level interface,
 809 the underlying classes are usually not required to build ruby applications
 810 using VICI. The _Connection_ class provides methods for the supported VICI
 811 commands and an event listening mechanism.
 812
 813 To represent the VICI message data tree, the gem converts the binary encoding
 814 to ruby data types. The _Connection_ class takes and returns ruby objects for
 815 the exchanged message data:
 816  * Sections get encoded as Hash, containing other sections as Hash, or
 817  * Key/Values, where the values are Strings as Hash values
 818  * Lists get encoded as Arrays with String values
 819 Non-String values that are not a Hash nor an Array get converted with .to_s
 820 during encoding.
 821
 822 ## Connecting to the daemon ##
 823
 824 To create a connection to the daemon, a socket can be passed to the
 825 _Connection_ constructor. If none is passed, a default Unix socket at
 826 _/var/run/charon.vici_ is used:
 827
 828         require "vici"
 829         require "socket"
 830
 831         v = Vici::Connection.new(UNIXSocket.new("/var/run/charon.vici"))
 832
 833 ## A simple client request ##
 834
 835 An example to print the daemon version information is as simple as:
 836
 837         x = v.version
 838         puts "%s %s (%s, %s, %s)" % [
 839                 x["daemon"], x["version"], x["sysname"], x["release"], x["machine"]
 840         ]
 841
 842 ## A request with closure invocation ##
 843
 844 The _Connection_ class takes care of event streaming by invoking a closure
 845 for each event. The following example lists all loaded connections using the
 846 _list-conns_ command and implicitly the _list-conn_ event:
 847
 848         v.list_conns { |conn|
 849                 conn.each { |key, value|
 850                         puts key
 851                 }
 852         }
 853
 854 ## API documentation ##
 855
 856 For more details about the ruby gem refer to the comments in the gem source
 857 code or the generated documentation.
 858
 859 # vici Python egg #
 860
 861 The _vici Python egg_ is a pure Python implementation of the VICI protocol to
 862 implement client applications. It is provided in the _python_ subdirectory, and
 863 gets built and installed if strongSwan has been _./configure_'d with
 864 _--enable-vici_ and _--enable-python-eggs_.
 865
 866 The _vici_ module provides a _Session()_ constructor for a high level interface,
 867 the underlying classes are usually not required to build Python applications
 868 using VICI. The _Session_ class provides methods for the supported VICI
 869 commands.
 870
 871 To represent the VICI message data tree, the library converts the binary
 872 encoding to Python data types. The _Session_ class takes and returns Python
 873 objects for the exchanged message data:
 874  * Sections get encoded as OrderedDict, containing other sections, or
 875  * Key/Values, where the values are strings as dictionary values
 876  * Lists get encoded as Python Lists with string values
 877 Values that do not conform to Python dict or list get converted to strings using
 878 str().
 879
 880 ## Connecting to the daemon ##
 881
 882 To create a connection to the daemon, a socket can be passed to the _Session_
 883 constructor. If none is passed, a default Unix socket at _/var/run/charon.vici_
 884 is used:
 885
 886         import vici
 887         import socket
 888
 889         s = socket.socket(socket.AF_UNIX)
 890         s.connect("/var/run/charon.vici")
 891         v = vici.Session(s)
 892
 893 ## A simple client request ##
 894
 895 An example to print the daemon version information is as simple as:
 896
 897         ver = v.version()
 898
 899         print "{daemon} {version} ({sysname}, {release}, {machine})".format(**ver)
 900
 901 ## A request with response iteration ##
 902
 903 The _Session_ class returns an iterable list for streamed events. Currently a
 904 list is returned with all streamed event messages, but a future release might
 905 provide more scalable object streaming. The following example lists all loaded
 906 connections using the _list-conns_ command and implicitly the _list-conn_ event:
 907
 908         for conn in v.list_conns():
 909                 for key in conn:
 910                         print key
 911
 912 ## Sorting in dictionaries ##
 913
 914 In VICI, in some message trees the order of objects in dictionary matters. In
 915 contrast to ruby Hashes, Python dictionaries do not preserve order of added
 916 objects. It is therefore recommended to use OrderedDicts instead of the default
 917 dictionaries. Objects returned by the library use OrderedDicts.
 918
 919 ## API documentation ##
 920
 921 For more details about the Python egg refer to the comments in the Python source
 922 code.