Annotation of embedaddon/strongswan/src/libcharon/plugins/vici/README.md, revision 1.1.1.2
1.1 misho 1: # The Versatile IKE Control Interface (VICI) protocol #
2:
3: The vici _[ˈvitʃi]_ plugin implements the server side of an IPC protocol to
4: configure, monitor and control the IKE daemon charon. It uses request/response
5: and event messages to communicate over a reliable stream based transport.
6:
7: ## Transport protocol ##
8:
9: To provide the service, the plugin opens a listening socket using a reliable,
10: stream based transport. charon relies on the different stream service
11: abstractions provided by libstrongswan, such as TCP and UNIX sockets.
12:
13: A client connects to this service to access functionality. It may send an
14: arbitrary number of packets over the connection before closing it.
15:
16: To exchange data, the transport protocol is segmented into byte sequences.
17: Each byte sequence is prefixed by a 32-bit length header in network order,
18: followed by the data. The maximum segment length is currently limited to 512KB
19: of data, and the length field contains the length of the data only, not
20: including the length field itself.
21:
22: The order of byte sequences must be strict, byte sequences must arrive in the
23: same order as sent.
24:
25: ## Packet layer ##
26:
27: Within the byte sequences defined by the transport layer, both the client
28: and the server can exchange packets. The type of packet defines its structure
29: and purpose. The packet type is a 8-bit identifier, and is the first byte
30: in a transport layer byte sequence. The length of the packet is given by the
31: transport layer.
32:
33: While a packet type may define the format of the wrapped data freely, currently
34: all types either contain a name, a message or both. The following packet types
35: are currently defined:
36:
37: * _CMD_REQUEST = 0_: A named request message
38: * _CMD_RESPONSE = 1_: An unnamed response message for a request
39: * _CMD_UNKNOWN = 2_: An unnamed response if requested command is unknown
40: * _EVENT_REGISTER = 3_: A named event registration request
41: * _EVENT_UNREGISTER = 4_: A named event deregistration request
42: * _EVENT_CONFIRM = 5_: An unnamed response for successful event (de-)registration
43: * _EVENT_UNKNOWN = 6_: A unnamed response if event (de-)registration failed
44: * _EVENT = 7_: A named event message
45:
46: For packets having a named type, after the packet type an 8-bit length header
47: of the name follows, indicating the string length in bytes of the name tag, not
48: including the length field itself. The name is an ASCII string that is not
49: null-terminated.
50:
51: The rest of the packet forms the exchanged message, the length is determined
52: by the transport byte sequence length, subtracting the packet type and
53: the optional name tag in some messages.
54:
55: ### Commands ###
56:
57: Commands are currently always requested by the client. The server replies with
58: a response, or with a CMD_UNKNOWN failure message to let the client know
59: that it does not have a handler for such a command. There is no sequence number
60: to associate responses to requests, so only one command can be active at
61: a time on a single connection.
62:
63: ### Events ###
64:
65: To receive event messages, the client explicitly registers for events by name,
66: and also unregisters if it does not want to receive events of the named kind
67: anymore. The server confirms event registration using EVENT_CONFIRM, or
68: indicates that there is no such event source with EVENT_UNKNOWN.
69:
70: Events may get raised at any time while registered, even during an active
71: request command. This mechanism is used to feed continuous data during a request,
72: for example.
73:
74: ## Message format ##
75:
76: The defined packet types optionally wrap a message with additional data.
77: Messages are currently used in CMD_REQUEST/CMD_RESPONSE, and in EVENT packets.
78: A message uses a hierarchical tree of sections. Each section (or the implicit
79: root section) contains an arbitrary set of key/value pairs, lists and
80: sub-sections. The length of a message is not part of the message itself, but
81: the wrapping layer, usually calculated from the transport byte sequence length.
82:
83: The message encoding consists of a sequence of elements. Each element starts
84: with the element type, optionally followed by an element name and/or an element
85: value. Currently the following message element types are defined:
86:
87: * _SECTION_START = 1_: Begin a new section having a name
88: * _SECTION_END = 2_: End a previously started section
89: * _KEY_VALUE = 3_: Define a value for a named key in the current section
90: * _LIST_START = 4_: Begin a named list for list items
91: * _LIST_ITEM = 5_: Define an unnamed item value in the current list
92: * _LIST_END = 6_: End a previously started list
93:
94: Types are encoded as 8-bit values. Types having a name (SECTION_START,
95: KEY_VALUE and LIST_START) have an ASCII string following the type, which itself
96: uses an 8-bit length header. The string must not be null-terminated, the string
97: length does not include the length field itself.
98:
99: Types having a value (KEY_VALUE and LIST_ITEM) have a raw blob sequence,
100: prefixed with a 16-bit network order length. The blob follows the type or the
101: name tag if available, the length defined by the length field does not include
102: the length field itself.
103:
104: The interpretation of any value is not defined by the message format; it can
105: take arbitrary blobs. The application may specify types for specific keys, such
106: as strings or integer representations. The vici plugin currently uses
107: non-null terminated strings as values only; numbers get encoded as strings.
108:
109: ### Sections ###
110:
111: Sections may be opened in the implicit root section, or any previously section.
112: They can be nested to arbitrary levels. A SECTION_END marker always closes
113: the last opened section; SECTION_START and SECTION_END items must be balanced
114: in a valid message.
115:
116: ### Key/Values ###
117:
118: Key/Value pair elements may appear in the implicit root section or any explicit
119: sub-section at any level. Key names must be unique in the current section, use
120: lists to define multiple values for a key. Key/values may not appear in lists,
121: use a sub-section instead.
122:
123: ### Lists ###
124:
125: Lists may appear at the same locations as Key/Values, and may not be nested.
126: Only a single list may be opened at the same time, and all lists must be closed
127: in valid messages. After opening a list, only list items may appear before the
128: list closing element. Empty lists are allowed, list items may appear within
129: lists only.
130:
131: ### Encoding example ###
132:
133: Consider the following structure using pseudo-markup for this example:
134:
135: key1 = value1
136: section1 = {
137: sub-section = {
138: key2 = value2
139: }
140: list1 = [ item1, item2 ]
141: }
142:
143: The example above represents a valid tree structure, that gets encoded as
144: the following C array:
145:
146: char msg[] = {
147: /* key1 = value1 */
148: 3, 4,'k','e','y','1', 0,6,'v','a','l','u','e','1',
149: /* section1 */
150: 1, 8,'s','e','c','t','i','o','n','1',
151: /* sub-section */
152: 1, 11,'s','u','b','-','s','e','c','t','i','o','n',
153: /* key2 = value2 */
154: 3, 4,'k','e','y','2', 0,6,'v','a','l','u','e','2',
155: /* sub-section end */
156: 2,
157: /* list1 */
158: 4, 5, 'l','i','s','t','1',
159: /* item1 */
160: 5, 0,5,'i','t','e','m','1',
161: /* item2 */
162: 5, 0,5,'i','t','e','m','2',
163: /* list1 end */
164: 6,
165: /* section1 end */
166: 2,
167: };
168:
169: ## Client-initiated commands ##
170:
171: Based on the packet layer, VICI implements commands requested by the client
172: and responded to by the server using named _CMD_REQUEST_ and _CMD_RESPONSE_
173: packets wrapping messages. The request message may contain command arguments,
174: the response message the reply.
175:
176: Some commands use response streaming, that is, a request triggers a series of
177: events to consecutively stream data to the client before the response message
178: completes the stream. A client must register for the appropriate event to
179: receive the stream, and unregister after the response has been received.
180:
181: The following client issued commands with the appropriate command input and
182: output messages are currently defined:
183:
184: ### version() ###
185:
186: Returns daemon and system specific version information.
187:
188: {} => {
189: daemon = <IKE daemon name>
190: version = <strongSwan version>
191: sysname = <operating system name>
192: release = <operating system release>
193: machine = <hardware identifier>
194: }
195:
196: ### stats() ###
197:
198: Returns IKE daemon statistics and load information.
199:
200: {} => {
201: uptime = {
202: running = <relative uptime in human-readable form>
203: since = <absolute startup time>
204: }
205: workers = {
206: total = <total number of worker threads>
207: idle = <worker threads currently idle>
208: active = {
209: critical = <threads processing "critical" priority jobs>
210: high = <threads processing "high" priority jobs>
211: medium = <threads processing "medium" priority jobs>
212: low = <threads processing "low" priority jobs>
213: }
214: }
215: queues = {
216: critical = <jobs queued with "critical" priority>
217: high = <jobs queued with "high" priority>
218: medium = <jobs queued with "medium" priority>
219: low = <jobs queued with "low" priority>
220: }
221: scheduled = <number of jobs scheduled for timed execution>
222: ikesas = {
223: total = <total number of IKE_SAs active>
224: half-open = <number of IKE_SAs in half-open state>
225: }
226: plugins = [
227: <names of loaded plugins>
228: ]
229: mem = { # available if built with leak-detective or on Windows
230: total = <total heap memory usage in bytes>
231: allocs = <total heap allocation blocks>
232: <heap-name>* = { # on Windows only
233: total = <heap memory usage in bytes by this heap>
234: allocs = <allocated blocks for this heap>
235: }
236: }
237: mallinfo = { # available with mallinfo() support
238: sbrk = <non-mmaped space available>
239: mmap = <mmaped space available>
240: used = <total number of bytes used>
241: free = <available but unused bytes>
242: }
243: }
244:
245: ### reload-settings() ###
246:
247: Reloads _strongswan.conf_ settings and all plugins supporting configuration
248: reload.
249:
250: {} => {
251: success = <yes or no>
252: errmsg = <error string on failure>
253: }
254:
255: ### initiate() ###
256:
257: Initiates an SA while streaming _control-log_ events.
258:
259: {
260: child = <CHILD_SA configuration name to initiate>
261: ike = <IKE_SA configuration name to initiate or to find child under>
262: timeout = <timeout in ms before returning>
263: init-limits = <whether limits may prevent initiating the CHILD_SA>
264: loglevel = <loglevel to issue "control-log" events for>
265: } => {
266: success = <yes or no>
267: errmsg = <error string on failure or timeout>
268: }
269:
270: The default timeout of 0 waits indefinitely for a result, and a timeout value
271: of -1 returns a result immediately.
272:
273: ### terminate() ###
274:
275: Terminates an SA while streaming _control-log_ events.
276:
277: {
278: child = <terminate a CHILD_SA by configuration name>
279: ike = <terminate an IKE_SA by configuration name>
280: child-id = <terminate a CHILD_SA by its reqid>
281: ike-id = <terminate an IKE_SA by its unique id>
282: force = <terminate IKE_SA without waiting for proper DELETE, if timeout
283: is given, waits for a response until it is reached>
284: timeout = <timeout in ms before returning, see below>
285: loglevel = <loglevel to issue "control-log" events for>
286: } => {
287: success = <yes or no>
288: matches = <number of matched SAs>
289: terminated = <number of terminated SAs>
290: errmsg = <error string on failure or timeout>
291: }
292:
293: The default timeout of 0 waits indefinitely for a result, and a timeout value
294: of -1 returns a result immediately.
295:
296: ### rekey() ###
297:
298: Initiate the rekeying of an SA.
299:
300: {
301: child = <rekey a CHILD_SA by configuration name>
302: ike = <rekey an IKE_SA by configuration name>
303: child-id = <rekey a CHILD_SA by its reqid>
304: ike-id = <rekey an IKE_SA by its unique id>
305: reauth = <reauthenticate instead of rekey an IKEv2 SA>
306: } => {
307: success = <yes or no>
308: matches = <number of matched SAs>
309: errmsg = <error string on failure>
310: }
311:
312: ### redirect() ###
313:
314: Redirect a client-initiated IKE_SA to another gateway. Only for IKEv2 and if
315: supported by the peer.
316:
317: {
318: ike = <redirect an IKE_SA by configuration name>
319: ike-id = <redirect an IKE_SA by its unique id>
320: peer-ip = <redirect an IKE_SA with matching peer IP, may also be a
321: subnet in CIDR notation or an IP range>
322: peer-id = <redirect an IKE_SA with matching peer identity, may contain
323: wildcards>
324: } => {
325: success = <yes or no>
326: matches = <number of matched SAs>
327: errmsg = <error string on failure>
328: }
329:
330: ### install() ###
331:
332: Install a trap, drop or bypass policy defined by a CHILD_SA config.
333:
334: {
335: child = <CHILD_SA configuration name to install>
336: ike = <optional IKE_SA configuration name to find child under>
337: } => {
338: success = <yes or no>
339: errmsg = <error string on failure>
340: }
341:
342: ### uninstall() ###
343:
344: Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
345:
346: {
347: child = <CHILD_SA configuration name to install>
348: ike = <optional IKE_SA configuration name to find child under,
349: if not given the first policy matching child is removed>
350: } => {
351: success = <yes or no>
352: errmsg = <error string on failure>
353: }
354:
355: ### list-sas() ###
356:
357: Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
358: events.
359:
360: {
361: noblock = <use non-blocking mode if key is set>
362: ike = <filter listed IKE_SAs by its name>
363: ike-id = <filter listed IKE_SA by its unique id>
364: } => {
365: # completes after streaming list-sa events
366: }
367:
368: ### list-policies() ###
369:
370: List currently installed trap, drop and bypass policies by streaming
371: _list-policy_ events.
372:
373: {
374: drop = <set to yes to list drop policies>
375: pass = <set to yes to list bypass policies>
376: trap = <set to yes to list trap policies>
377: child = <filter by CHILD_SA configuration name>
378: ike = <filter by IKE_SA configuration name>
379: } => {
380: # completes after streaming list-sa events
381: }
382:
383: ### list-conns() ###
384:
385: List currently loaded connections by streaming _list-conn_ events. This
386: call includes all connections known by the daemon, not only those loaded
387: over vici.
388:
389: {
390: ike = <list connections matching a given configuration name only>
391: } => {
392: # completes after streaming list-conn events
393: }
394:
395: ### get-conns() ###
396:
397: Return a list of connection names loaded exclusively over vici, not including
398: connections found in other backends.
399:
400: {} => {
401: conns = [
402: <list of connection names>
403: ]
404: }
405:
406: ### list-certs() ###
407:
408: List currently loaded certificates by streaming _list-cert_ events. This
409: call includes all certificates known by the daemon, not only those loaded
410: over vici.
411:
412: {
413: type = <certificate type to filter for, X509|X509_AC|X509_CRL|
414: OCSP_RESPONSE|PUBKEY or ANY>
415: flag = <X.509 certificate flag to filter for, NONE|CA|AA|OCSP or ANY>
416: subject = <set to list only certificates having subject>
417: } => {
418: # completes after streaming list-cert events
419: }
420:
421: ### list-authorities() ###
422:
423: List currently loaded certification authority information by streaming
424: _list-authority_ events.
425:
426: {
427: name = <list certification authority of a given name>
428: } => {
429: # completes after streaming list-authority events
430: }
431:
432: ### get-authorities() ###
433:
434: Return a list of currently loaded certification authority names.
435:
436: {} => {
437: authorities = [
438: <list of certification authority names>
439: ]
440: }
441:
442: ### load-conn() ###
443:
444: Load a single connection definition into the daemon. An existing connection
445: with the same name gets updated or replaced.
446:
447: {
448: <IKE_SA config name> = {
449: # IKE configuration parameters with authentication and CHILD_SA
450: # subsections. Refer to swanctl.conf(5) for details.
451: }
452: } => {
453: success = <yes or no>
454: errmsg = <error string on failure>
455: }
456:
457: ### unload-conn() ###
458:
459: Unload a previously loaded connection definition by name.
460:
461: {
462: name = <IKE_SA config name>
463: } => {
464: success = <yes or no>
465: errmsg = <error string on failure>
466: }
467:
468: ### load-cert() ###
469:
470: Load a certificate into the daemon.
471:
472: {
473: type = <certificate type, X509|X509_AC|X509_CRL>
474: flag = <X.509 certificate flag, NONE|CA|AA|OCSP>
475: data = <PEM or DER encoded certificate data>
476: } => {
477: success = <yes or no>
478: errmsg = <error string on failure>
479: }
480:
481: ### load-key() ###
482:
483: Load a private key into the daemon.
484:
485: {
1.1.1.2 ! misho 486: type = <private key type, rsa|ecdsa|ed25519|ed448|bliss|any>
1.1 misho 487: data = <PEM or DER encoded key data>
488: } => {
489: success = <yes or no>
490: errmsg = <error string on failure>
491: id = <hex-encoded SHA-1 key identifier of the public key on success>
492: }
493:
494: ### unload-key() ###
495:
496: Unload the private key with the given key identifier.
497:
498: {
499: id = <hex-encoded SHA-1 key identifier of the private key to unload>
500: } => {
501: success = <yes or no>
502: errmsg = <error string on failure>
503: }
504:
505: ### get-keys() ###
506:
507: Return a list of identifiers of private keys loaded exclusively over vici, not
508: including keys found in other backends.
509:
510: {} => {
511: keys = [
512: <list of hex-encoded SHA-1 key identifiers>
513: ]
514: }
515:
516: ### load-token() ###
517:
518: Load a private key located on a token into the daemon. Such keys may be listed
519: and unloaded using the _get-keys_ and _unload-key_ commands, respectively (based
520: on the key identifier derived from the public key).
521:
522: {
523: handle = <hex-encoded CKA_ID of the private key on token>
524: slot = <optional slot number>
525: module = <optional PKCS#11 module>
526: pin = <optional PIN to access the key, has to be provided via other
527: means if not given>
528: } => {
529: success = <yes or no>
530: errmsg = <error string on failure>
531: id = <hex-encoded SHA-1 key identifier of the public key on success>
532: }
533:
534: ### load-shared() ###
535:
536: Load a shared IKE PSK, EAP, XAuth or NTLM secret into the daemon.
537:
538: {
539: id = <optional unique identifier of this shared key>
540: type = <shared key type, IKE|EAP|XAUTH|NTLM>
541: data = <raw shared key data>
542: owners = [
543: <list of shared key owner identities>
544: ]
545: } => {
546: success = <yes or no>
547: errmsg = <error string on failure>
548: }
549:
550: ### unload-shared() ###
551:
552: Unload a previously loaded shared IKE PSK, EAP, XAuth or NTLM secret by its
553: unique identifier.
554:
555: {
556: id = <unique identifier of the shared key to unload>
557: } => {
558: success = <yes or no>
559: errmsg = <error string on failure>
560: }
561:
562: ### get-shared() ###
563:
564: Return a list of unique identifiers of shared keys loaded exclusively over vici,
565: not including keys found in other backends.
566:
567: {} => {
568: keys = [
569: <list of unique identifiers>
570: ]
571: }
572:
573: ### flush-certs() ###
574:
575: Flushes the certificate cache. The optional type argument allows to flush
576: only certificates of a given type, e.g. all cached CRLs.
577:
578: {
579: type = <certificate type to filter for, X509|X509_AC|X509_CRL|
580: OCSP_RESPONSE|PUBKEY or ANY>
581: } => {
582: success = <yes or no>
583: errmsg = <error string on failure>
584: }
585:
586: ### clear-creds() ###
587:
588: Clear all loaded certificate, private key and shared key credentials. This
589: affects only credentials loaded over vici, but additionally flushes the
590: credential cache.
591:
592: {} => {
593: success = <yes or no>
594: errmsg = <error string on failure>
595: }
596:
597: ### load-authority() ###
598:
599: Load a single certification authority definition into the daemon. An existing
600: authority with the same name gets replaced.
601:
602: {
603: <certification authority name> = {
604: # certification authority parameters
605: # refer to swanctl.conf(5) for details.
606: }
607: } => {
608: success = <yes or no>
609: errmsg = <error string on failure>
610: }
611:
612: ### unload-authority() ###
613:
614: Unload a previously loaded certification authority definition by name.
615:
616: {
617: name = <certification authority name>
618: } => {
619: success = <yes or no>
620: errmsg = <error string on failure>
621: }
622:
623: ### load-pool() ###
624:
625: Load an in-memory virtual IP and configuration attribute pool. Existing
626: pools with the same name get updated, if possible.
627:
628: {
629: <pool name> = {
630: addrs = <subnet of virtual IP pool addresses>
631: <attribute type>* = [
632: # attribute type is one of address, dns, nbns, dhcp, netmask,
633: # server, subnet, split_include, split_exclude or a numerical
634: # attribute type identifier.
635: <list of attributes for type>
636: ]
637: }
638: } => {
639: success = <yes or no>
640: errmsg = <error string on failure>
641: }
642:
643: ### unload-pool() ###
644:
645: Unload a previously loaded virtual IP and configuration attribute pool.
646: Unloading fails for pools with leases currently online.
647:
648: {
649: name = <virtual IP address pool to delete>
650: } => {
651: success = <yes or no>
652: errmsg = <error string on failure>
653: }
654:
655: ### get-pools() ###
656:
657: List the currently loaded pools.
658:
659: {
660: leases = <set to yes to include leases>
661: name = <optional name of the pool to query>
662: } => {
663: <pool name>* = {
664: base = <virtual IP pool base address>
665: size = <total number of addresses in the pool>
666: online = <number of leases online>
667: offline = <number of leases offline>
668: leases = {
669: <zero-based index>* = {
670: address = <IP address>
671: identity = <assigned identity>
672: status = <online|offline>
673: }
674: }
675: }
676: }
677:
678: ### get-algorithms() ###
679:
680: List currently loaded algorithms and their implementation.
681:
682: {} => {
683: <algorithm type> = {
684: <algorithm> = <plugin providing the implementation>
685: }
686: }
687:
688: ### get-counters() ###
689:
690: List global or connection-specific counters for several IKE events.
691:
692: {
693: name = <optional connection name, omit for global counters>
694: all = <yes to get counters for all connections, name is ignored>
695: } => {
696: counters = {
697: <name|empty for global counters> = {
698: <pairs of counter name and 64-bit counter value>
699: }
700: }
701: success = <yes or no>
702: errmsg = <error string on failure>
703: }
704:
705: ### reset-counters() ###
706:
707: Reset global or connection-specific IKE event counters.
708:
709: {
710: name = <optional connection name, omit for global counters>
711: all = <yes to reset counters for all connections, name is ignored>
712: } => {
713: success = <yes or no>
714: errmsg = <error string on failure>
715: }
716:
717: ## Server-issued events ##
718:
719: Based on the packet layer, the vici plugin raises event messages using named
720: EVENT packets wrapping messages. The message contains event details.
721:
722: ### log ###
723:
724: The _log_ event is issued to registered clients for each debug log message.
725: This event is not associated with a command.
726:
727: {
728: group = <subsystem identifier for debug message>
729: level = <log level, 0-4>
730: thread = <numerical thread identifier issuing the log message>
731: ikesa-name = <name of IKE_SA, if log is associated with any>
732: ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
733: msg = <log message text>
734: }
735:
736: ### control-log ###
737:
738: The _control-log_ event is issued for log events during active _initiate_ or
739: _terminate_ commands. It is issued only to clients currently having such
740: a command active.
741:
742: {
743: group = <subsystem identifier for debug message>
744: level = <log level, 0-4>
745: ikesa-name = <name of IKE_SA, if log associated with any>
746: ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
747: msg = <log message text>
748: }
749:
750: ### list-sa ###
751:
752: The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
753: command.
754:
755: {
756: <IKE_SA config name> = {
757: uniqueid = <IKE_SA unique identifier>
758: version = <IKE version, 1 or 2>
759: state = <IKE_SA state name>
760: local-host = <local IKE endpoint address>
761: local-port = <local IKE endpoint port>
762: local-id = <local IKE identity>
763: remote-host = <remote IKE endpoint address>
764: remote-port = <remote IKE endpoint port>
765: remote-id = <remote IKE identity>
766: remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
767: remote-eap-id = <remote EAP identity, if EAP-authenticated>
768: initiator = <yes, if initiator of IKE_SA>
769: initiator-spi = <hex encoded initiator SPI / cookie>
770: responder-spi = <hex encoded responder SPI / cookie>
771: nat-local = <yes, if local endpoint is behind a NAT>
772: nat-remote = <yes, if remote endpoint is behind a NAT>
773: nat-fake = <yes, if NAT situation has been faked as responder>
774: nat-any = <yes, if any endpoint is behind a NAT (also if faked)>
775: if-id-in = <hex encoded default inbound XFRM interface ID>
776: if-id-out = <hex encoded default outbound XFRM interface ID>
777: encr-alg = <IKE encryption algorithm string>
778: encr-keysize = <key size for encr-alg, if applicable>
779: integ-alg = <IKE integrity algorithm string>
780: integ-keysize = <key size for encr-alg, if applicable>
781: prf-alg = <IKE pseudo random function string>
782: dh-group = <IKE Diffie-Hellman group string>
783: established = <seconds the IKE_SA has been established>
784: rekey-time = <seconds before IKE_SA gets rekeyed>
785: reauth-time = <seconds before IKE_SA gets re-authenticated>
786: local-vips = [
787: <list of virtual IPs assigned by the remote peer, installed locally>
788: ]
789: remote-vips = [
790: <list of virtual IPs assigned to the remote peer>
791: ]
792: tasks-queued = [
793: <list of currently queued tasks for execution>
794: ]
795: tasks-active = [
796: <list of tasks currently initiating actively>
797: ]
798: tasks-passive = [
799: <list of tasks currently handling passively>
800: ]
801: child-sas = {
802: <unique child-sa-name>* = {
803: name = <name of the CHILD_SA>
804: uniqueid = <unique CHILD_SA identifier>
805: reqid = <reqid of CHILD_SA>
806: state = <state string of CHILD_SA>
807: mode = <IPsec mode, tunnel|transport|beet>
808: protocol = <IPsec protocol AH|ESP>
809: encap = <yes if using UDP encapsulation>
810: spi-in = <hex encoded inbound SPI>
811: spi-out = <hex encoded outbound SPI>
812: cpi-in = <hex encoded inbound CPI, if using compression>
813: cpi-out = <hex encoded outbound CPI, if using compression>
814: mark-in = <hex encoded inbound Netfilter mark value>
815: mark-mask-in = <hex encoded inbound Netfilter mark mask>
816: mark-out = <hex encoded outbound Netfilter mark value>
817: mark-mask-out = <hex encoded outbound Netfilter mark mask>
818: if-id-in = <hex encoded inbound XFRM interface ID>
819: if-id-out = <hex encoded outbound XFRM interface ID>
820: encr-alg = <ESP encryption algorithm name, if any>
821: encr-keysize = <ESP encryption key size, if applicable>
822: integ-alg = <ESP or AH integrity algorithm name, if any>
823: integ-keysize = <ESP or AH integrity key size, if applicable>
824: prf-alg = <CHILD_SA pseudo random function name>
825: dh-group = <CHILD_SA PFS rekeying DH group name, if any>
826: esn = <1 if using extended sequence numbers>
827: bytes-in = <number of input bytes processed>
828: packets-in = <number of input packets processed>
829: use-in = <seconds since last inbound packet, if any>
830: bytes-out = <number of output bytes processed>
831: packets-out = <number of output packets processed>
832: use-out = <seconds since last outbound packet, if any>
833: rekey-time = <seconds before CHILD_SA gets rekeyed>
834: life-time = <seconds before CHILD_SA expires>
835: install-time = <seconds the CHILD_SA has been installed>
836: local-ts = [
837: <list of local traffic selectors>
838: ]
839: remote-ts = [
840: <list of remote traffic selectors>
841: ]
842: }
843: }
844: }
845: }
846:
847: ### list-policy ###
848:
849: The _list-policy_ event is issued to stream installed policies during an active
850: _list-policies_ command.
851:
852: {
853: <ike-sa-config-name/child-sa-config-name> = {
854: child = <CHILD_SA configuration name>
855: ike = <IKE_SA configuration name or namespace, if available>
856: mode = <policy mode, tunnel|transport|pass|drop>
857: local-ts = [
858: <list of local traffic selectors>
859: ]
860: remote-ts = [
861: <list of remote traffic selectors>
862: ]
863: }
864: }
865:
866: ### list-conn ###
867:
868: The _list-conn_ event is issued to stream loaded connection during an active
869: _list-conns_ command.
870:
871: {
872: <IKE_SA connection name> = {
873: local_addrs = [
874: <list of valid local IKE endpoint addresses>
875: ]
876: remote_addrs = [
877: <list of valid remote IKE endpoint addresses>
878: ]
879: version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
880: reauth_time = <IKE_SA reauthentication interval in seconds>
881: rekey_time = <IKE_SA rekeying interval in seconds>
882:
883: local*, remote* = { # multiple local and remote auth sections
884: class = <authentication type>
885: eap-type = <EAP type to authenticate if when using EAP>
886: eap-vendor = <EAP vendor for type, if any>
887: xauth = <xauth backend name>
888: revocation = <revocation policy>
889: id = <IKE identity>
890: aaa_id = <AAA authentication backend identity>
891: eap_id = <EAP identity for authentication>
892: xauth_id = <XAuth username for authentication>
893: groups = [
894: <group membership required to use connection>
895: ]
896: certs = [
897: <certificates allowed for authentication>
898: ]
899: cacerts = [
900: <CA certificates allowed for authentication>
901: ]
902: }
903: children = {
904: <CHILD_SA config name>* = {
905: mode = <IPsec mode>
906: rekey_time = <CHILD_SA rekeying interval in seconds>
907: rekey_bytes = <CHILD_SA rekeying interval in bytes>
908: rekey_packets = <CHILD_SA rekeying interval in packets>
909: local-ts = [
910: <list of local traffic selectors>
911: ]
912: remote-ts = [
913: <list of remote traffic selectors>
914: ]
915: }
916: }
917: }
918: }
919:
920: ### list-cert ###
921:
922: The _list-cert_ event is issued to stream loaded certificates during an active
923: _list-certs_ command.
924:
925: {
926: type = <certificate type, X509|X509_AC|X509_CRL|OCSP_RESPONSE|PUBKEY>
927: flag = <X.509 certificate flag, NONE|CA|AA|OCSP>
928: has_privkey = <set if a private key for the certificate is available>
929: data = <ASN1 encoded certificate data>
930: subject = <subject string if defined and certificate type is PUBKEY>
931: not-before = <time string if defined and certificate type is PUBKEY>
932: not-after = <time string if defined and certificate type is PUBKEY>
933: }
934:
935: ### list-authority ###
936:
937: The _list-authority_ event is issued to stream loaded certification authority
938: information during an active_list-authorities_ command.
939:
940: {
941: <certification authority name> = {
942: cacert = <subject distinguished name of CA certificate>
943: crl_uris = [
944: <CRL URI (http, ldap or file)>
945: ]
946: ocsp_uris = [
947: <OCSP URI (http)>
948: ]
949: cert_uri_base = <base URI for download of hash-and-URL certificates>
950: }
951: }
952:
953: ### ike-updown ###
954:
955: The _ike-updown_ event is issued when an IKE_SA is established or terminated.
956:
957: {
958: up = <set if up event>
959: <IKE_SA config name> = {
960: <same data as in the list-sas event, but without child-sas section>
961: }
962: }
963:
964: ### ike-rekey ###
965:
966: The _ike-rekey_ event is issued when an IKE_SA is rekeyed.
967:
968: {
969: <IKE_SA config name> = {
970: old = {
971: <same data as in the list-sas event, but without child-sas section>
972: }
973: new = {
974: <same data as in the list-sas event, but without child-sas section>
975: }
976: }
977: }
978:
1.1.1.2 ! misho 979: ### ike-update ###
! 980:
! 981: The _ike-update_ event is issued when the local or remote endpoint address of an
! 982: IKE_SA is about to change (at least one address/port is different).
! 983:
! 984: {
! 985: local-host = <new/current local IKE endpoint address>
! 986: local-port = <new/current local IKE endpoint port>
! 987: remote-host = <new/current remote IKE endpoint address>
! 988: remote-port = <new/current remote IKE endpoint port>
! 989: <IKE_SA config name> = {
! 990: <same data as in the list-sas event, but without child-sas section
! 991: and listing the old addresses/ports>
! 992: }
! 993: }
! 994:
1.1 misho 995: ### child-updown ###
996:
997: The _child-updown_ event is issued when a CHILD_SA is established or terminated.
998:
999: {
1000: up = <set if up event>
1001: <IKE_SA config name> = {
1002: <same data as in the list-sas event, but with only the affected
1003: CHILD_SA in the child-sas section>
1004: }
1005: }
1006:
1007: ### child-rekey ###
1008:
1009: The _child-rekey_ event is issued when a CHILD_SA is rekeyed.
1010:
1011: {
1012: <IKE_SA config name> = {
1013: <same data as in the list-sas event, but with the child-sas section
1014: as follows>
1015: child-sas = {
1016: <child-sa-name> = {
1017: old = {
1018: <same data as in the list-sas event>
1019: }
1020: new = {
1021: <same data as in the list-sas event>
1022: }
1023: }
1024: }
1025: }
1026: }
1027:
1028: # libvici C client library #
1029:
1030: libvici is the reference implementation of a C client library implementing
1031: the vici protocol. It builds upon libstrongswan, but provides a stable API
1032: to implement client applications in the C programming language. libvici uses
1033: the libstrongswan thread pool to deliver event messages asynchronously.
1034:
1035: ## Connecting to the daemon ##
1036:
1037: This example shows how to connect to the daemon using the default URI, and
1038: then perform proper cleanup:
1039:
1040: #include <stdio.h>
1041: #include <errno.h>
1042: #include <string.h>
1043:
1044: #include <libvici.h>
1045:
1046: int main(int argc, char *argv[])
1047: {
1048: vici_conn_t *conn;
1049: int ret = 0;
1050:
1051: vici_init();
1052: conn = vici_connect(NULL);
1053: if (conn)
1054: {
1055: /* do stuff */
1056: vici_disconnect(conn);
1057: }
1058: else
1059: {
1060: ret = errno;
1061: fprintf(stderr, "connecting failed: %s\n", strerror(errno));
1062: }
1063: vici_deinit();
1064: return ret;
1065: }
1066:
1067: ## A simple client request ##
1068:
1069: In the following example, a simple _version_ request is issued to the daemon
1070: and the result is printed:
1071:
1072: int get_version(vici_conn_t *conn)
1073: {
1074: vici_req_t *req;
1075: vici_res_t *res;
1076: int ret = 0;
1077:
1078: req = vici_begin("version");
1079: res = vici_submit(req, conn);
1080: if (res)
1081: {
1082: printf("%s %s (%s, %s, %s)\n",
1083: vici_find_str(res, "", "daemon"),
1084: vici_find_str(res, "", "version"),
1085: vici_find_str(res, "", "sysname"),
1086: vici_find_str(res, "", "release"),
1087: vici_find_str(res, "", "machine"));
1088: vici_free_res(res);
1089: }
1090: else
1091: {
1092: ret = errno;
1093: fprintf(stderr, "version request failed: %s\n", strerror(errno));
1094: }
1095: return ret;
1096: }
1097:
1098: ## A request with event streaming and callback parsing ##
1099:
1100: In this more advanced example, the _list-conns_ command is used to stream
1101: loaded connections with the _list-conn_ event. The event message is parsed
1102: with a simple callback to print the connection name:
1103:
1104: int conn_cb(void *null, vici_res_t *res, char *name)
1105: {
1106: printf("%s\n", name);
1107: return 0;
1108: }
1109:
1110: void list_cb(void *null, char *name, vici_res_t *res)
1111: {
1112: if (vici_parse_cb(res, conn_cb, NULL, NULL, NULL) != 0)
1113: {
1114: fprintf(stderr, "parsing failed: %s\n", strerror(errno));
1115: }
1116: }
1117:
1118: int list_conns(vici_conn_t *conn)
1119: {
1120: vici_req_t *req;
1121: vici_res_t *res;
1122: int ret = 0;
1123:
1124: if (vici_register(conn, "list-conn", list_cb, NULL) == 0)
1125: {
1126: req = vici_begin("list-conns");
1127: res = vici_submit(req, conn);
1128: if (res)
1129: {
1130: vici_free_res(res);
1131: }
1132: else
1133: {
1134: ret = errno;
1135: fprintf(stderr, "request failed: %s\n", strerror(errno));
1136: }
1137: vici_register(conn, "list-conn", NULL, NULL);
1138: }
1139: else
1140: {
1141: ret = errno;
1142: fprintf(stderr, "registration failed: %s\n", strerror(errno));
1143: }
1144: return ret;
1145: }
1146:
1147: ## API documentation ##
1148:
1149: More information about the libvici API is available in the _libvici.h_ header
1150: file or the generated Doxygen documentation.
1151:
1152: # vici ruby gem #
1153:
1154: The _vici ruby gem_ is a pure ruby implementation of the VICI protocol to
1155: implement client applications. It is provided in the _ruby_ subdirectory, and
1156: gets built and installed if strongSwan has been _./configure_'d with
1157: _--enable-vici_ and _--enable-ruby-gems_.
1158:
1159: The _Connection_ class from the _Vici_ module provides the high level interface,
1160: the underlying classes are usually not required to build ruby applications
1161: using VICI. The _Connection_ class provides methods for the supported VICI
1162: commands and an event listening mechanism.
1163:
1164: To represent the VICI message data tree, the gem converts the binary encoding
1165: to ruby data types. The _Connection_ class takes and returns ruby objects for
1166: the exchanged message data:
1167: * Sections get encoded as Hash, containing other sections as Hash, or
1168: * Key/Values, where the values are Strings as Hash values
1169: * Lists get encoded as Arrays with String values
1170: Non-String values that are not a Hash nor an Array get converted with .to_s
1171: during encoding.
1172:
1173: ## Connecting to the daemon ##
1174:
1175: To create a connection to the daemon, a socket can be passed to the
1176: _Connection_ constructor. If none is passed, a default Unix socket at
1177: _/var/run/charon.vici_ is used:
1178:
1179: require "vici"
1180: require "socket"
1181:
1182: v = Vici::Connection.new(UNIXSocket.new("/var/run/charon.vici"))
1183:
1184: ## A simple client request ##
1185:
1186: An example to print the daemon version information is as simple as:
1187:
1188: x = v.version
1189: puts "%s %s (%s, %s, %s)" % [
1190: x["daemon"], x["version"], x["sysname"], x["release"], x["machine"]
1191: ]
1192:
1193: ## A request with closure invocation ##
1194:
1195: The _Connection_ class takes care of event streaming by invoking a closure
1196: for each event. The following example lists all loaded connections using the
1197: _list-conns_ command and implicitly the _list-conn_ event:
1198:
1199: v.list_conns { |conn|
1200: conn.each { |key, value|
1201: puts key
1202: }
1203: }
1204:
1205: ## API documentation ##
1206:
1207: For more details about the ruby gem refer to the comments in the gem source
1208: code or the generated documentation.
1209:
1210: # vici Python egg #
1211:
1212: The _vici Python egg_ is a pure Python implementation of the VICI protocol to
1213: implement client applications. It is provided in the _python_ subdirectory, and
1214: gets built and installed if strongSwan has been _./configure_'d with
1215: _--enable-vici_ and _--enable-python-eggs_.
1216:
1217: The _vici_ module provides a _Session()_ constructor for a high level interface,
1218: the underlying classes are usually not required to build Python applications
1219: using VICI. The _Session_ class provides methods for the supported VICI
1220: commands.
1221:
1222: To represent the VICI message data tree, the library converts the binary
1223: encoding to Python data types. The _Session_ class takes and returns Python
1224: objects for the exchanged message data:
1225: * Sections get encoded as OrderedDict, containing other sections, or
1226: * Key/Values, where the values are strings as dictionary values
1227: * Lists get encoded as Python Lists with string values
1228: Values that do not conform to Python dict or list get converted to strings using
1229: str().
1230:
1231: ## Connecting to the daemon ##
1232:
1233: To create a connection to the daemon, a socket can be passed to the _Session_
1234: constructor. If none is passed, a default Unix socket at _/var/run/charon.vici_
1235: is used:
1236:
1237: import vici
1238: import socket
1239:
1240: s = socket.socket(socket.AF_UNIX)
1241: s.connect("/var/run/charon.vici")
1242: v = vici.Session(s)
1243:
1244: ## A simple client request ##
1245:
1246: An example to print the daemon version information is as simple as:
1247:
1248: ver = v.version()
1249:
1250: print "{daemon} {version} ({sysname}, {release}, {machine})".format(**ver)
1251:
1252: ## A request with response iteration ##
1253:
1254: The _Session_ class returns an iterable Python generator for streamed events to
1255: continuously stream objects to the caller. The following example lists all
1256: loaded connections using the _list-conns_ command and implicitly the _list-conn_
1257: event:
1258:
1259: for conn in v.list_conns():
1260: for key in conn:
1261: print key
1262:
1263: Please note that if the returned generator is not iterated completely, it must
1264: be closed using _close()_. This is implicitly done when breaking from a loop,
1265: but an explicit call may be required when directly iterating the generator with
1266: _next()_.
1267:
1268: ## Sorting in dictionaries ##
1269:
1270: In VICI, in some message trees the order of objects in dictionary matters. In
1271: contrast to ruby Hashes, Python dictionaries do not preserve order of added
1272: objects. It is therefore recommended to use OrderedDicts instead of the default
1273: dictionaries. Objects returned by the library use OrderedDicts.
1274:
1275: ## API documentation ##
1276:
1277: For more details about the Python egg refer to the comments in the Python source
1278: code.
1279:
1280: # Vici::Session Perl CPAN module #
1281:
1282: The _Vici::Session Perl CPAN module_ is a pure Perl implementation of the VICI
1283: protocol to implement client applications. It is provided in the _perl_
1284: subdirectory, and gets built and installed if strongSwan has been
1285: _./configure_'d with_--enable-vici_ and _--enable-perl-cpan_.
1286:
1287: The _Vici::Session_ module provides a _new()_ constructor for a high level
1288: interface, the underlying _Vici::Packet_ and _Vici::Transport_ classes are
1289: usually not required to build Perl applications using VICI. The _Vici::Session_
1290: class provides methods for the supported VICI commands. The auxiliary
1291: _Vici::Message_ class is used to encode configuration parameters sent to
1292: the daemon and decode data returned by the daemon.
1293:
1294: ## Connecting to the daemon ##
1295:
1296: use IO::Socket::UNIX;
1297: use Vici::Session;
1298: use Vici::Message;
1299:
1300: my $socket = IO::Socket::UNIX->new(
1301: Type => SOCK_STREAM,
1302: Peer => '/var/run/charon.vici',
1303: ) or die "Vici socket: $!";
1304:
1305: my $session = Vici::Session->new($socket);
1306:
1307: ## A simple client request ##
1308:
1309: An example to print the daemon version information is as simple as:
1310:
1311: my $version = $session->version()->hash();
1312:
1313: foreach my $key ('daemon', 'version', 'sysname', 'release', 'machine' ) {
1314: print $version->{$key}, " ";
1315: }
1316:
1317: The _Vici::Session_ methods are explained in the perl/Vici-Session/README.pod
1318: document.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libcharon / plugins / vici