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                 ike = <optional IKE_SA configuraiton name to find child under>
 262                 timeout = <timeout in ms before returning>
 263                 init-limits = <whether limits may prevent initiating the CHILD_SA>
 264                 loglevel = <loglevel to issue "control-log" events for>
 265         } => {
 266                 success = <yes or no>
 267                 errmsg = <error string on failure or timeout>
 268         }
 269
 270 The default timeout of 0 waits indefinitely for a result, and a timeout value
 271 of -1 returns a result immediately.
 272
 273 ### terminate() ###
 274
 275 Terminates an SA while streaming _control-log_ events.
 276
 277         {
 278                 child = <terminate a CHILD_SA by configuration name>
 279                 ike = <terminate an IKE_SA by configuration name>
 280                 child_id = <terminate a CHILD_SA by its reqid>
 281                 ike_id = <terminate an IKE_SA by its unique id>
 282                 timeout = <timeout in ms before returning>
 283                 loglevel = <loglevel to issue "control-log" events for>
 284         } => {
 285                 success = <yes or no>
 286                 errmsg = <error string on failure or timeout>
 287         }
 288
 289 The default timeout of 0 waits indefinitely for a result, and a timeout value
 290 of -1 returns a result immediately.
 291
 292 ### install() ###
 293
 294 Install a trap, drop or bypass policy defined by a CHILD_SA config.
 295
 296         {
 297                 child = <CHILD_SA configuration name to install>
 298                 ike = <optional IKE_SA configuraiton name to find child under>
 299         } => {
 300                 success = <yes or no>
 301                 errmsg = <error string on failure>
 302         }
 303
 304 ### uninstall() ###
 305
 306 Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
 307
 308         {
 309                 child = <CHILD_SA configuration name to install>
 310         } => {
 311                 success = <yes or no>
 312                 errmsg = <error string on failure>
 313         }
 314
 315 ### list-sas() ###
 316
 317 Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
 318 events.
 319
 320         {
 321                 noblock = <use non-blocking mode if key is set>
 322                 ike = <filter listed IKE_SAs by its name>
 323                 ike_id = <filter listed IKE_SA by its unique id>
 324         } => {
 325                 # completes after streaming list-sa events
 326         }
 327
 328 ### list-policies() ###
 329
 330 List currently installed trap, drop and bypass policies by streaming
 331 _list-policy_ events.
 332
 333         {
 334                 drop = <set to yes to list drop policies>
 335                 pass = <set to yes to list bypass policies>
 336                 trap = <set to yes to list trap policies>
 337                 child = <filter by CHILD_SA configuration name>
 338         } => {
 339                 # completes after streaming list-sa events
 340         }
 341
 342 ### list-conns() ###
 343
 344 List currently loaded connections by streaming _list-conn_ events. This
 345 call includes all connections known by the daemon, not only those loaded
 346 over vici.
 347
 348         {
 349                 ike = <list connections matching a given configuration name only>
 350         } => {
 351                 # completes after streaming list-conn events
 352         }
 353
 354 ### get-conns() ###
 355
 356 Return a list of connection names loaded exclusively over vici, not including
 357 connections found in other backends.
 358
 359         {} => {
 360                 conns = [
 361                         <list of connection names>
 362                 ]
 363         }
 364
 365 ### list-certs() ###
 366
 367 List currently loaded certificates by streaming _list-cert_ events. This
 368 call includes all certificates known by the daemon, not only those loaded
 369 over vici.
 370
 371         {
 372                 type = <certificate type to filter for, or ANY>
 373                 subject = <set to list only certificates having subject>
 374         } => {
 375                 # completes after streaming list-cert events
 376         }
 377
 378 ### list-authorities() ###
 379
 380 List currently loaded certification authority information by streaming
 381 _list-authority_ events.
 382
 383         {
 384                 name = <list certification authority of a given name>
 385         } => {
 386                 # completes after streaming list-authority events
 387         }
 388
 389 ### get-authorities() ###
 390
 391 Return a list of currently loaded certification authority names.
 392
 393         {} => {
 394                 authorities = [
 395                         <list of certification authority names>
 396                 ]
 397         }
 398
 399 ### load-conn() ###
 400
 401 Load a single connection definition into the daemon. An existing connection
 402 with the same name gets updated or replaced.
 403
 404         {
 405                 <IKE_SA config name> = {
 406                         # IKE configuration parameters with authentication and CHILD_SA
 407                         # subsections. Refer to swanctl.conf(5) for details.
 408                 } => {
 409                         success = <yes or no>
 410                         errmsg = <error string on failure>
 411                 }
 412         }
 413
 414 ### unload-conn() ###
 415
 416 Unload a previously loaded connection definition by name.
 417
 418         {
 419                 name = <IKE_SA config name>
 420         } => {
 421                 success = <yes or no>
 422                 errmsg = <error string on failure>
 423         }
 424
 425 ### load-cert() ###
 426
 427 Load a certificate into the daemon.
 428
 429         {
 430                 type = <certificate type, X509|X509CA|X509AA|X509CRL|X509AC>
 431                 data = <PEM or DER encoded certificate data>
 432         } => {
 433                 success = <yes or no>
 434                 errmsg = <error string on failure>
 435         }
 436
 437 ### load-key() ###
 438
 439 Load a private key into the daemon.
 440
 441         {
 442                 type = <private key type, RSA|ECDSA>
 443                 data = <PEM or DER encoded key data>
 444         } => {
 445                 success = <yes or no>
 446                 errmsg = <error string on failure>
 447         }
 448
 449 ### load-shared() ###
 450
 451 Load a shared IKE PSK, EAP or XAuth secret into the daemon.
 452
 453         {
 454                 type = <private key type, IKE|EAP|XAUTH>
 455                 data = <raw shared key data>
 456                 owners = [
 457                         <list of shared key owner identities>
 458                 ]
 459         } => {
 460                 success = <yes or no>
 461                 errmsg = <error string on failure>
 462         }
 463
 464 ### clear-creds() ###
 465
 466 Clear all loaded certificate, private key and shared key credentials. This
 467 affects only credentials loaded over vici, but additionally flushes the
 468 credential cache.
 469
 470         {} => {
 471                 success = <yes or no>
 472                 errmsg = <error string on failure>
 473         }
 474
 475 ### load-authority() ###
 476
 477 Load a single certification authority definition into the daemon. An existing
 478 authority with the same name gets replaced.
 479
 480         {
 481                 <certification authority name> = {
 482                         # certification authority parameters
 483                         # refer to swanctl.conf(5) for details.
 484                 } => {
 485                         success = <yes or no>
 486                         errmsg = <error string on failure>
 487                 }
 488         }
 489
 490 ### unload-authority() ###
 491
 492 Unload a previously loaded certification authority definition by name.
 493
 494         {
 495                 name = <certification authority name>
 496         } => {
 497                 success = <yes or no>
 498                 errmsg = <error string on failure>
 499         }
 500
 501 ### load-pool() ###
 502
 503 Load an in-memory virtual IP and configuration attribute pool. Existing
 504 pools with the same name get updated, if possible.
 505
 506         {
 507                 <pool name> = {
 508                         addrs = <subnet of virtual IP pool addresses>
 509                         <attribute type>* = [
 510                                 # attribute type is one of address, dns, nbns, dhcp, netmask,
 511                                 # server, subnet, split_include, split_exclude or a numerical
 512                                 # attribute type identifier.
 513                                 <list of attributes for type>
 514                         ]
 515                 }
 516         } => {
 517                 success = <yes or no>
 518                 errmsg = <error string on failure>
 519         }
 520
 521 ### unload-pool() ###
 522
 523 Unload a previously loaded virtual IP and configuration attribute pool.
 524 Unloading fails for pools with leases currently online.
 525
 526         {
 527                 name = <virtual IP address pool to delete>
 528         } => {
 529                 success = <yes or no>
 530                 errmsg = <error string on failure>
 531         }
 532
 533 ### get-pools() ###
 534
 535 List the currently loaded pools.
 536
 537         {
 538                 leases = <set to yes to include leases>
 539         } => {
 540                 <pool name>* = {
 541                         base = <virtual IP pool base address>
 542                         size = <total number of addresses in the pool>
 543                         online = <number of leases online>
 544                         offline = <number of leases offline>
 545                         leases = {
 546                                 <zero-based index>* = {
 547                                         address = <IP address>
 548                                         identity = <assigned identity>
 549                                         status = <online|offline>
 550                                 }
 551                         }
 552                 }
 553         }
 554
 555 ### get-algorithms() ###
 556
 557 List currently loaded algorithms and their implementation.
 558
 559         {} => {
 560                 <algorithm type> = {
 561                         <algorithm> = <plugin providing the implementation>
 562                 }
 563         }
 564
 565 ## Server-issued events ##
 566
 567 Based on the packet layer, the vici plugin raises event messages using named
 568 EVENT packets wrapping messages. The message contains event details.
 569
 570 ### log ###
 571
 572 The _log_ event is issued to registered clients for each debug log message.
 573 This event is not associated with a command.
 574
 575         {
 576                 group = <subsystem identifier for debug message>
 577                 level = <log level, 0-4>
 578                 thread = <numerical thread identifier issuing the log message>
 579                 ikesa-name = <name of IKE_SA, if log is associated with any>
 580                 ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
 581                 msg = <log message text>
 582         }
 583
 584 ### control-log ###
 585
 586 The _control-log_ event is issued for log events during active _initiate_ or
 587 _terminate_ commands. It is issued only to clients currently having such
 588 a command active.
 589
 590         {
 591                 group = <subsystem identifier for debug message>
 592                 level = <log level, 0-4>
 593                 ikesa-name = <name of IKE_SA, if log associated with any>
 594                 ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
 595                 msg = <log message text>
 596         }
 597
 598 ### list-sa ###
 599
 600 The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
 601 command.
 602
 603         {
 604                 <IKE_SA config name> = {
 605                         uniqueid = <IKE_SA unique identifier>
 606                         version = <IKE version, 1 or 2>
 607                         state = <IKE_SA state name>
 608                         local-host = <local IKE endpoint address>
 609                         local-id = <local IKE identity>
 610                         remote-host = <remote IKE endpoint address>
 611                         remote-id = <remote IKE identity>
 612                         remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
 613                         remote-eap-id = <remote EAP identity, if EAP-authenticated>
 614                         initiator = <yes, if initiator of IKE_SA>
 615                         initiator-spi = <hex encoded initiator SPI / cookie>
 616                         responder-spi = <hex encoded responder SPI / cookie>
 617                         nat-local = <yes, if local endpoint is behind a NAT>
 618                         nat-remote = <yes, if remote endpoint is behind a NAT>
 619                         nat-fake = <yes, if NAT situation has been faked as responder>
 620                         nat-any = <yes, if any endpoint is behind a NAT (also if faked)>
 621                         encr-alg = <IKE encryption algorithm string>
 622                         encr-keysize = <key size for encr-alg, if applicable>
 623                         integ-alg = <IKE integrity algorithm string>
 624                         integ-keysize = <key size for encr-alg, if applicable>
 625                         prf-alg = <IKE pseudo random function string>
 626                         dh-group = <IKE Diffie-Hellman group string>
 627                         established = <seconds the IKE_SA has been established>
 628                         rekey-time = <seconds before IKE_SA gets rekeyed>
 629                         reauth-time = <seconds before IKE_SA gets re-authenticated>
 630                         local-vips = [
 631                                 <list of virtual IPs assigned by the remote peer, installed locally>
 632                         ]
 633                         remote-vips = [
 634                                 <list of virtual IPs assigned to the remote peer>
 635                         ]
 636                         tasks-queued = [
 637                                 <list of currently queued tasks for execution>
 638                         ]
 639                         tasks-active = [
 640                                 <list of tasks currently initiating actively>
 641                         ]
 642                         tasks-passive = [
 643                                 <list of tasks currently handling passively>
 644                         ]
 645                         child-sas = {
 646                                 <child-sa-name>* = {
 647                                         uniqueid = <unique CHILD_SA identifier>
 648                                         reqid = <reqid of CHILD_SA>
 649                                         state = <state string of CHILD_SA>
 650                                         mode = <IPsec mode, tunnel|transport|beet>
 651                                         protocol = <IPsec protocol AH|ESP>
 652                                         encap = <yes if using UDP encapsulation>
 653                                         spi-in = <hex encoded inbound SPI>
 654                                         spi-out = <hex encoded outbound SPI>
 655                                         cpi-in = <hex encoded inbound CPI, if using compression>
 656                                         cpi-out = <hex encoded outbound CPI, if using compression>
 657                                         encr-alg = <ESP encryption algorithm name, if any>
 658                                         encr-keysize = <ESP encryption key size, if applicable>
 659                                         integ-alg = <ESP or AH integrity algorithm name, if any>
 660                                         integ-keysize = <ESP or AH integrity key size, if applicable>
 661                                         prf-alg = <CHILD_SA pseudo random function name>
 662                                         dh-group = <CHILD_SA PFS rekeying DH group name, if any>
 663                                         esn = <1 if using extended sequence numbers>
 664                                         bytes-in = <number of input bytes processed>
 665                                         packets-in = <number of input packets processed>
 666                                         use-in = <seconds since last inbound packet, if any>
 667                                         bytes-out = <number of output bytes processed>
 668                                         packets-out = <number of output packets processed>
 669                                         use-out = <seconds since last outbound packet, if any>
 670                                         rekey-time = <seconds before CHILD_SA gets rekeyed>
 671                                         life-time = <seconds before CHILD_SA expires>
 672                                         install-time = <seconds the CHILD_SA has been installed>
 673                                         local-ts = [
 674                                                 <list of local traffic selectors>
 675                                         ]
 676                                         remote-ts = [
 677                                                 <list of remote traffic selectors>
 678                                         ]
 679                                 }
 680                         }
 681                 }
 682         }
 683
 684 ### list-policy ###
 685
 686 The _list-policy_ event is issued to stream installed policies during an active
 687 _list-policies_ command.
 688
 689         {
 690                 <child-sa-config-name> = {
 691                         mode = <policy mode, tunnel|transport|pass|drop>
 692                         local-ts = [
 693                                 <list of local traffic selectors>
 694                         ]
 695                         remote-ts = [
 696                                 <list of remote traffic selectors>
 697                         ]
 698                 }
 699         }
 700
 701 ### list-conn ###
 702
 703 The _list-conn_ event is issued to stream loaded connection during an active
 704 _list-conns_ command.
 705
 706         {
 707                 <IKE_SA connection name> = {
 708                         local_addrs = [
 709                                 <list of valid local IKE endpoint addresses>
 710                         ]
 711                         remote_addrs = [
 712                                 <list of valid remote IKE endpoint addresses>
 713                         ]
 714                         version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
 715
 716                         local*, remote* = { # multiple local and remote auth sections
 717                                 class = <authentication type>
 718                                 eap-type = <EAP type to authenticate if when using EAP>
 719                                 eap-vendor = <EAP vendor for type, if any>
 720                                 xauth = <xauth backend name>
 721                                 revocation = <revocation policy>
 722                                 id = <IKE identity>
 723                                 aaa_id = <AAA authentication backend identity>
 724                                 eap_id = <EAP identity for authentication>
 725                                 xauth_id = <XAuth username for authentication>
 726                                 groups = [
 727                                         <group membership required to use connection>
 728                                 ]
 729                                 certs = [
 730                                         <certificates allowed for authentication>
 731                                 ]
 732                                 cacerts = [
 733                                         <CA certificates allowed for authentication>
 734                                 ]
 735                         }
 736                         children = {
 737                                 <CHILD_SA config name>* = {
 738                                         mode = <IPsec mode>
 739                                         local-ts = [
 740                                                 <list of local traffic selectors>
 741                                         ]
 742                                         remote-ts = [
 743                                                 <list of remote traffic selectors>
 744                                         ]
 745                                 }
 746                         }
 747                 }
 748         }
 749
 750 ### list-cert ###
 751
 752 The _list-cert_ event is issued to stream loaded certificates during an active
 753 _list-certs_ command.
 754
 755         {
 756                 type = <certificate type>
 757                 has_privkey = <set if a private key for the certificate is available>
 758                 data = <ASN1 encoded certificate data>
 759         }
 760
 761 ### list-authority ###
 762
 763 The _list-authority_ event is issued to stream loaded certification authority
 764 information during an active_list-authorities_ command.
 765
 766         {
 767                 <certification authority name> = {
 768                         cacert = <subject distinguished name of CA certificate>
 769                         crl_uris = [
 770                                 <CRL URI (http, ldap or file)>
 771                         ]
 772                         ocsp_uris = [
 773                                 <OCSP URI (http)>
 774                         ]
 775                         cert_uri_base = <base URI for download of hash-and-URL certificates>
 776                 }
 777         }
 778
 779 ### ike-updown ###
 780
 781 The _ike-updown_ event is issued when an IKE_SA is established or terminated.
 782
 783         {
 784                 up = <yes or no>
 785                 <IKE_SA config name> = {
 786                         <same data as in the list-sas event, but without child-sas section>
 787                 }
 788         }
 789
 790 ### ike-rekey ###
 791
 792 The _ike-rekey_ event is issued when an IKE_SA is rekeyed.
 793
 794         {
 795                 <IKE_SA config name> = {
 796                         old = {
 797                                 <same data as in the list-sas event, but without child-sas section>
 798                         }
 799                         new = {
 800                                 <same data as in the list-sas event, but without child-sas section>
 801                         }
 802                 }
 803         }
 804
 805 ### child-updown ###
 806
 807 The _child-updown_ event is issued when a CHILD_SA is established or terminated.
 808
 809         {
 810                 up = <yes or no>
 811                 <IKE_SA config name> = {
 812                         <same data as in the list-sas event, but with only the affected
 813                          CHILD_SA in the child-sas section>
 814                 }
 815         }
 816
 817 ### child-rekey ###
 818
 819 The _child-rekey_ event is issued when a CHILD_SA is rekeyed.
 820
 821         {
 822                 <IKE_SA config name> = {
 823                         <same data as in the list-sas event, but with the child-sas section
 824                          as follows>
 825                         child-sas = {
 826                                 <child-sa-name> = {
 827                                         old = {
 828                                                 <same data as in the list-sas event>
 829                                         }
 830                                         new = {
 831                                                 <same data as in the list-sas event>
 832                                         }
 833                                 }
 834                         }
 835                 }
 836         }
 837
 838 # libvici C client library #
 839
 840 libvici is the reference implementation of a C client library implementing
 841 the vici protocol. It builds upon libstrongswan, but provides a stable API
 842 to implement client applications in the C programming language. libvici uses
 843 the libstrongswan thread pool to deliver event messages asynchronously.
 844
 845 ## Connecting to the daemon ##
 846
 847 This example shows how to connect to the daemon using the default URI, and
 848 then perform proper cleanup:
 849
 850         #include <stdio.h>
 851         #include <errno.h>
 852         #include <string.h>
 853
 854         #include <libvici.h>
 855
 856         int main(int argc, char *argv[])
 857         {
 858                 vici_conn_t *conn;
 859                 int ret = 0;
 860
 861                 vici_init();
 862                 conn = vici_connect(NULL);
 863                 if (conn)
 864                 {
 865                         /* do stuff */
 866                         vici_disconnect(conn);
 867                 }
 868                 else
 869                 {
 870                         ret = errno;
 871                         fprintf(stderr, "connecting failed: %s\n", strerror(errno));
 872                 }
 873                 vici_deinit();
 874                 return ret;
 875         }
 876
 877 ## A simple client request ##
 878
 879 In the following example, a simple _version_ request is issued to the daemon
 880 and the result is printed:
 881
 882         int get_version(vici_conn_t *conn)
 883         {
 884                 vici_req_t *req;
 885                 vici_res_t *res;
 886                 int ret = 0;
 887
 888                 req = vici_begin("version");
 889                 res = vici_submit(req, conn);
 890                 if (res)
 891                 {
 892                         printf("%s %s (%s, %s, %s)\n",
 893                                 vici_find_str(res, "", "daemon"),
 894                                 vici_find_str(res, "", "version"),
 895                                 vici_find_str(res, "", "sysname"),
 896                                 vici_find_str(res, "", "release"),
 897                                 vici_find_str(res, "", "machine"));
 898                         vici_free_res(res);
 899                 }
 900                 else
 901                 {
 902                         ret = errno;
 903                         fprintf(stderr, "version request failed: %s\n", strerror(errno));
 904                 }
 905                 return ret;
 906         }
 907
 908 ## A request with event streaming and callback parsing ##
 909
 910 In this more advanced example, the _list-conns_ command is used to stream
 911 loaded connections with the _list-conn_ event. The event message is parsed
 912 with a simple callback to print the connection name:
 913
 914         int conn_cb(void *null, vici_res_t *res, char *name)
 915         {
 916                 printf("%s\n", name);
 917                 return 0;
 918         }
 919
 920         void list_cb(void *null, char *name, vici_res_t *res)
 921         {
 922                 if (vici_parse_cb(res, conn_cb, NULL, NULL, NULL) != 0)
 923                 {
 924                         fprintf(stderr, "parsing failed: %s\n", strerror(errno));
 925                 }
 926         }
 927
 928         int list_conns(vici_conn_t *conn)
 929         {
 930                 vici_req_t *req;
 931                 vici_res_t *res;
 932                 int ret = 0;
 933
 934                 if (vici_register(conn, "list-conn", list_cb, NULL) == 0)
 935                 {
 936                         req = vici_begin("list-conns");
 937                         res = vici_submit(req, conn);
 938                         if (res)
 939                         {
 940                                 vici_free_res(res);
 941                         }
 942                         else
 943                         {
 944                                 ret = errno;
 945                                 fprintf(stderr, "request failed: %s\n", strerror(errno));
 946                         }
 947                         vici_register(conn, "list-conn", NULL, NULL);
 948                 }
 949                 else
 950                 {
 951                         ret = errno;
 952                         fprintf(stderr, "registration failed: %s\n", strerror(errno));
 953                 }
 954                 return ret;
 955         }
 956
 957 ## API documentation ##
 958
 959 More information about the libvici API is available in the _libvici.h_ header
 960 file or the generated Doxygen documentation.
 961
 962 # vici ruby gem #
 963
 964 The _vici ruby gem_ is a pure ruby implementation of the VICI protocol to
 965 implement client applications. It is provided in the _ruby_ subdirectory, and
 966 gets built and installed if strongSwan has been _./configure_'d with
 967 _--enable-vici_ and _--enable-ruby-gems_.
 968
 969 The _Connection_ class from the _Vici_ module provides the high level interface,
 970 the underlying classes are usually not required to build ruby applications
 971 using VICI. The _Connection_ class provides methods for the supported VICI
 972 commands and an event listening mechanism.
 973
 974 To represent the VICI message data tree, the gem converts the binary encoding
 975 to ruby data types. The _Connection_ class takes and returns ruby objects for
 976 the exchanged message data:
 977  * Sections get encoded as Hash, containing other sections as Hash, or
 978  * Key/Values, where the values are Strings as Hash values
 979  * Lists get encoded as Arrays with String values
 980 Non-String values that are not a Hash nor an Array get converted with .to_s
 981 during encoding.
 982
 983 ## Connecting to the daemon ##
 984
 985 To create a connection to the daemon, a socket can be passed to the
 986 _Connection_ constructor. If none is passed, a default Unix socket at
 987 _/var/run/charon.vici_ is used:
 988
 989         require "vici"
 990         require "socket"
 991
 992         v = Vici::Connection.new(UNIXSocket.new("/var/run/charon.vici"))
 993
 994 ## A simple client request ##
 995
 996 An example to print the daemon version information is as simple as:
 997
 998         x = v.version
 999         puts "%s %s (%s, %s, %s)" % [
1000                 x["daemon"], x["version"], x["sysname"], x["release"], x["machine"]
1001         ]
1002
1003 ## A request with closure invocation ##
1004
1005 The _Connection_ class takes care of event streaming by invoking a closure
1006 for each event. The following example lists all loaded connections using the
1007 _list-conns_ command and implicitly the _list-conn_ event:
1008
1009         v.list_conns { |conn|
1010                 conn.each { |key, value|
1011                         puts key
1012                 }
1013         }
1014
1015 ## API documentation ##
1016
1017 For more details about the ruby gem refer to the comments in the gem source
1018 code or the generated documentation.
1019
1020 # vici Python egg #
1021
1022 The _vici Python egg_ is a pure Python implementation of the VICI protocol to
1023 implement client applications. It is provided in the _python_ subdirectory, and
1024 gets built and installed if strongSwan has been _./configure_'d with
1025 _--enable-vici_ and _--enable-python-eggs_.
1026
1027 The _vici_ module provides a _Session()_ constructor for a high level interface,
1028 the underlying classes are usually not required to build Python applications
1029 using VICI. The _Session_ class provides methods for the supported VICI
1030 commands.
1031
1032 To represent the VICI message data tree, the library converts the binary
1033 encoding to Python data types. The _Session_ class takes and returns Python
1034 objects for the exchanged message data:
1035  * Sections get encoded as OrderedDict, containing other sections, or
1036  * Key/Values, where the values are strings as dictionary values
1037  * Lists get encoded as Python Lists with string values
1038 Values that do not conform to Python dict or list get converted to strings using
1039 str().
1040
1041 ## Connecting to the daemon ##
1042
1043 To create a connection to the daemon, a socket can be passed to the _Session_
1044 constructor. If none is passed, a default Unix socket at _/var/run/charon.vici_
1045 is used:
1046
1047         import vici
1048         import socket
1049
1050         s = socket.socket(socket.AF_UNIX)
1051         s.connect("/var/run/charon.vici")
1052         v = vici.Session(s)
1053
1054 ## A simple client request ##
1055
1056 An example to print the daemon version information is as simple as:
1057
1058         ver = v.version()
1059
1060         print "{daemon} {version} ({sysname}, {release}, {machine})".format(**ver)
1061
1062 ## A request with response iteration ##
1063
1064 The _Session_ class returns an iterable Python generator for streamed events to
1065 continuously stream objects to the caller. The following example lists all
1066 loaded connections using the _list-conns_ command and implicitly the _list-conn_
1067 event:
1068
1069         for conn in v.list_conns():
1070                 for key in conn:
1071                         print key
1072
1073 Please note that if the returned generator is not iterated completely, it must
1074 be closed using _close()_. This is implicitly done when breaking from a loop,
1075 but an explicit call may be required when directly iterating the generator with
1076 _next()_.
1077
1078 ## Sorting in dictionaries ##
1079
1080 In VICI, in some message trees the order of objects in dictionary matters. In
1081 contrast to ruby Hashes, Python dictionaries do not preserve order of added
1082 objects. It is therefore recommended to use OrderedDicts instead of the default
1083 dictionaries. Objects returned by the library use OrderedDicts.
1084
1085 ## API documentation ##
1086
1087 For more details about the Python egg refer to the comments in the Python source
1088 code.
1089
1090 # Vici::Session Perl CPAN module #
1091
1092 The _Vici::Session Perl CPAN module_ is a pure Perl implementation of the VICI
1093 protocol to implement client applications. It is provided in the _perl_
1094 subdirectory, and gets built and installed if strongSwan has been
1095  _./configure_'d with_--enable-vici_ and _--enable-perl-cpan_.
1096
1097 The _Vici::Session_ module provides a _new()_ constructor for a high level
1098 interface, the underlying _Vici::Packet_ and _Vici::Transport_ classes are
1099 usually not required to build Perl applications using VICI. The _Vici::Session_
1100 class provides methods for the supported VICI commands. The auxiliare
1101  _Vici::Message_ class is used to encode configuration parameters sent to
1102 the daemon and decode data returned by the daemon.
1103
1104 ## Connecting to the daemon ##
1105
1106         use IO::Socket::UNIX;
1107         use Vici::Session;
1108         use Vici::Message;
1109
1110         my $socket = IO::Socket::UNIX->new(
1111                         Type => SOCK_STREAM,
1112                         Peer => '/var/run/charon.vici',
1113         ) or die "Vici socket: $!";
1114
1115         my $session = Vici::Session->new($socket);
1116
1117 ## A simple client request ##
1118
1119 An example to print the daemon version information is as simple as:
1120
1121         my $version = $session->version()->hash();
1122
1123         foreach my $key ('daemon', 'version', 'sysname', 'release', 'machine' ) {
1124                 print $version->{$key}, " ";
1125         }
1126
1127 The _Vici::Session_ methods are explained in the perl/Vici-Session/README.pod
1128 document.