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