src/libcharon/plugins/vici/README.md

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