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