Annotation of embedaddon/strongswan/src/libcharon/plugins/vici/README.md, revision 1.1
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: {
! 486: type = <private key type, rsa|ecdsa|bliss|any>
! 487: data = <PEM or DER encoded key data>
! 488: } => {
! 489: success = <yes or no>
! 490: errmsg = <error string on failure>
! 491: id = <hex-encoded SHA-1 key identifier of the public key on success>
! 492: }
! 493:
! 494: ### unload-key() ###
! 495:
! 496: Unload the private key with the given key identifier.
! 497:
! 498: {
! 499: id = <hex-encoded SHA-1 key identifier of the private key to unload>
! 500: } => {
! 501: success = <yes or no>
! 502: errmsg = <error string on failure>
! 503: }
! 504:
! 505: ### get-keys() ###
! 506:
! 507: Return a list of identifiers of private keys loaded exclusively over vici, not
! 508: including keys found in other backends.
! 509:
! 510: {} => {
! 511: keys = [
! 512: <list of hex-encoded SHA-1 key identifiers>
! 513: ]
! 514: }
! 515:
! 516: ### load-token() ###
! 517:
! 518: Load a private key located on a token into the daemon. Such keys may be listed
! 519: and unloaded using the _get-keys_ and _unload-key_ commands, respectively (based
! 520: on the key identifier derived from the public key).
! 521:
! 522: {
! 523: handle = <hex-encoded CKA_ID of the private key on token>
! 524: slot = <optional slot number>
! 525: module = <optional PKCS#11 module>
! 526: pin = <optional PIN to access the key, has to be provided via other
! 527: means if not given>
! 528: } => {
! 529: success = <yes or no>
! 530: errmsg = <error string on failure>
! 531: id = <hex-encoded SHA-1 key identifier of the public key on success>
! 532: }
! 533:
! 534: ### load-shared() ###
! 535:
! 536: Load a shared IKE PSK, EAP, XAuth or NTLM secret into the daemon.
! 537:
! 538: {
! 539: id = <optional unique identifier of this shared key>
! 540: type = <shared key type, IKE|EAP|XAUTH|NTLM>
! 541: data = <raw shared key data>
! 542: owners = [
! 543: <list of shared key owner identities>
! 544: ]
! 545: } => {
! 546: success = <yes or no>
! 547: errmsg = <error string on failure>
! 548: }
! 549:
! 550: ### unload-shared() ###
! 551:
! 552: Unload a previously loaded shared IKE PSK, EAP, XAuth or NTLM secret by its
! 553: unique identifier.
! 554:
! 555: {
! 556: id = <unique identifier of the shared key to unload>
! 557: } => {
! 558: success = <yes or no>
! 559: errmsg = <error string on failure>
! 560: }
! 561:
! 562: ### get-shared() ###
! 563:
! 564: Return a list of unique identifiers of shared keys loaded exclusively over vici,
! 565: not including keys found in other backends.
! 566:
! 567: {} => {
! 568: keys = [
! 569: <list of unique identifiers>
! 570: ]
! 571: }
! 572:
! 573: ### flush-certs() ###
! 574:
! 575: Flushes the certificate cache. The optional type argument allows to flush
! 576: only certificates of a given type, e.g. all cached CRLs.
! 577:
! 578: {
! 579: type = <certificate type to filter for, X509|X509_AC|X509_CRL|
! 580: OCSP_RESPONSE|PUBKEY or ANY>
! 581: } => {
! 582: success = <yes or no>
! 583: errmsg = <error string on failure>
! 584: }
! 585:
! 586: ### clear-creds() ###
! 587:
! 588: Clear all loaded certificate, private key and shared key credentials. This
! 589: affects only credentials loaded over vici, but additionally flushes the
! 590: credential cache.
! 591:
! 592: {} => {
! 593: success = <yes or no>
! 594: errmsg = <error string on failure>
! 595: }
! 596:
! 597: ### load-authority() ###
! 598:
! 599: Load a single certification authority definition into the daemon. An existing
! 600: authority with the same name gets replaced.
! 601:
! 602: {
! 603: <certification authority name> = {
! 604: # certification authority parameters
! 605: # refer to swanctl.conf(5) for details.
! 606: }
! 607: } => {
! 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:
! 979: ### child-updown ###
! 980:
! 981: The _child-updown_ event is issued when a CHILD_SA is established or terminated.
! 982:
! 983: {
! 984: up = <set if up event>
! 985: <IKE_SA config name> = {
! 986: <same data as in the list-sas event, but with only the affected
! 987: CHILD_SA in the child-sas section>
! 988: }
! 989: }
! 990:
! 991: ### child-rekey ###
! 992:
! 993: The _child-rekey_ event is issued when a CHILD_SA is rekeyed.
! 994:
! 995: {
! 996: <IKE_SA config name> = {
! 997: <same data as in the list-sas event, but with the child-sas section
! 998: as follows>
! 999: child-sas = {
! 1000: <child-sa-name> = {
! 1001: old = {
! 1002: <same data as in the list-sas event>
! 1003: }
! 1004: new = {
! 1005: <same data as in the list-sas event>
! 1006: }
! 1007: }
! 1008: }
! 1009: }
! 1010: }
! 1011:
! 1012: # libvici C client library #
! 1013:
! 1014: libvici is the reference implementation of a C client library implementing
! 1015: the vici protocol. It builds upon libstrongswan, but provides a stable API
! 1016: to implement client applications in the C programming language. libvici uses
! 1017: the libstrongswan thread pool to deliver event messages asynchronously.
! 1018:
! 1019: ## Connecting to the daemon ##
! 1020:
! 1021: This example shows how to connect to the daemon using the default URI, and
! 1022: then perform proper cleanup:
! 1023:
! 1024: #include <stdio.h>
! 1025: #include <errno.h>
! 1026: #include <string.h>
! 1027:
! 1028: #include <libvici.h>
! 1029:
! 1030: int main(int argc, char *argv[])
! 1031: {
! 1032: vici_conn_t *conn;
! 1033: int ret = 0;
! 1034:
! 1035: vici_init();
! 1036: conn = vici_connect(NULL);
! 1037: if (conn)
! 1038: {
! 1039: /* do stuff */
! 1040: vici_disconnect(conn);
! 1041: }
! 1042: else
! 1043: {
! 1044: ret = errno;
! 1045: fprintf(stderr, "connecting failed: %s\n", strerror(errno));
! 1046: }
! 1047: vici_deinit();
! 1048: return ret;
! 1049: }
! 1050:
! 1051: ## A simple client request ##
! 1052:
! 1053: In the following example, a simple _version_ request is issued to the daemon
! 1054: and the result is printed:
! 1055:
! 1056: int get_version(vici_conn_t *conn)
! 1057: {
! 1058: vici_req_t *req;
! 1059: vici_res_t *res;
! 1060: int ret = 0;
! 1061:
! 1062: req = vici_begin("version");
! 1063: res = vici_submit(req, conn);
! 1064: if (res)
! 1065: {
! 1066: printf("%s %s (%s, %s, %s)\n",
! 1067: vici_find_str(res, "", "daemon"),
! 1068: vici_find_str(res, "", "version"),
! 1069: vici_find_str(res, "", "sysname"),
! 1070: vici_find_str(res, "", "release"),
! 1071: vici_find_str(res, "", "machine"));
! 1072: vici_free_res(res);
! 1073: }
! 1074: else
! 1075: {
! 1076: ret = errno;
! 1077: fprintf(stderr, "version request failed: %s\n", strerror(errno));
! 1078: }
! 1079: return ret;
! 1080: }
! 1081:
! 1082: ## A request with event streaming and callback parsing ##
! 1083:
! 1084: In this more advanced example, the _list-conns_ command is used to stream
! 1085: loaded connections with the _list-conn_ event. The event message is parsed
! 1086: with a simple callback to print the connection name:
! 1087:
! 1088: int conn_cb(void *null, vici_res_t *res, char *name)
! 1089: {
! 1090: printf("%s\n", name);
! 1091: return 0;
! 1092: }
! 1093:
! 1094: void list_cb(void *null, char *name, vici_res_t *res)
! 1095: {
! 1096: if (vici_parse_cb(res, conn_cb, NULL, NULL, NULL) != 0)
! 1097: {
! 1098: fprintf(stderr, "parsing failed: %s\n", strerror(errno));
! 1099: }
! 1100: }
! 1101:
! 1102: int list_conns(vici_conn_t *conn)
! 1103: {
! 1104: vici_req_t *req;
! 1105: vici_res_t *res;
! 1106: int ret = 0;
! 1107:
! 1108: if (vici_register(conn, "list-conn", list_cb, NULL) == 0)
! 1109: {
! 1110: req = vici_begin("list-conns");
! 1111: res = vici_submit(req, conn);
! 1112: if (res)
! 1113: {
! 1114: vici_free_res(res);
! 1115: }
! 1116: else
! 1117: {
! 1118: ret = errno;
! 1119: fprintf(stderr, "request failed: %s\n", strerror(errno));
! 1120: }
! 1121: vici_register(conn, "list-conn", NULL, NULL);
! 1122: }
! 1123: else
! 1124: {
! 1125: ret = errno;
! 1126: fprintf(stderr, "registration failed: %s\n", strerror(errno));
! 1127: }
! 1128: return ret;
! 1129: }
! 1130:
! 1131: ## API documentation ##
! 1132:
! 1133: More information about the libvici API is available in the _libvici.h_ header
! 1134: file or the generated Doxygen documentation.
! 1135:
! 1136: # vici ruby gem #
! 1137:
! 1138: The _vici ruby gem_ is a pure ruby implementation of the VICI protocol to
! 1139: implement client applications. It is provided in the _ruby_ subdirectory, and
! 1140: gets built and installed if strongSwan has been _./configure_'d with
! 1141: _--enable-vici_ and _--enable-ruby-gems_.
! 1142:
! 1143: The _Connection_ class from the _Vici_ module provides the high level interface,
! 1144: the underlying classes are usually not required to build ruby applications
! 1145: using VICI. The _Connection_ class provides methods for the supported VICI
! 1146: commands and an event listening mechanism.
! 1147:
! 1148: To represent the VICI message data tree, the gem converts the binary encoding
! 1149: to ruby data types. The _Connection_ class takes and returns ruby objects for
! 1150: the exchanged message data:
! 1151: * Sections get encoded as Hash, containing other sections as Hash, or
! 1152: * Key/Values, where the values are Strings as Hash values
! 1153: * Lists get encoded as Arrays with String values
! 1154: Non-String values that are not a Hash nor an Array get converted with .to_s
! 1155: during encoding.
! 1156:
! 1157: ## Connecting to the daemon ##
! 1158:
! 1159: To create a connection to the daemon, a socket can be passed to the
! 1160: _Connection_ constructor. If none is passed, a default Unix socket at
! 1161: _/var/run/charon.vici_ is used:
! 1162:
! 1163: require "vici"
! 1164: require "socket"
! 1165:
! 1166: v = Vici::Connection.new(UNIXSocket.new("/var/run/charon.vici"))
! 1167:
! 1168: ## A simple client request ##
! 1169:
! 1170: An example to print the daemon version information is as simple as:
! 1171:
! 1172: x = v.version
! 1173: puts "%s %s (%s, %s, %s)" % [
! 1174: x["daemon"], x["version"], x["sysname"], x["release"], x["machine"]
! 1175: ]
! 1176:
! 1177: ## A request with closure invocation ##
! 1178:
! 1179: The _Connection_ class takes care of event streaming by invoking a closure
! 1180: for each event. The following example lists all loaded connections using the
! 1181: _list-conns_ command and implicitly the _list-conn_ event:
! 1182:
! 1183: v.list_conns { |conn|
! 1184: conn.each { |key, value|
! 1185: puts key
! 1186: }
! 1187: }
! 1188:
! 1189: ## API documentation ##
! 1190:
! 1191: For more details about the ruby gem refer to the comments in the gem source
! 1192: code or the generated documentation.
! 1193:
! 1194: # vici Python egg #
! 1195:
! 1196: The _vici Python egg_ is a pure Python implementation of the VICI protocol to
! 1197: implement client applications. It is provided in the _python_ subdirectory, and
! 1198: gets built and installed if strongSwan has been _./configure_'d with
! 1199: _--enable-vici_ and _--enable-python-eggs_.
! 1200:
! 1201: The _vici_ module provides a _Session()_ constructor for a high level interface,
! 1202: the underlying classes are usually not required to build Python applications
! 1203: using VICI. The _Session_ class provides methods for the supported VICI
! 1204: commands.
! 1205:
! 1206: To represent the VICI message data tree, the library converts the binary
! 1207: encoding to Python data types. The _Session_ class takes and returns Python
! 1208: objects for the exchanged message data:
! 1209: * Sections get encoded as OrderedDict, containing other sections, or
! 1210: * Key/Values, where the values are strings as dictionary values
! 1211: * Lists get encoded as Python Lists with string values
! 1212: Values that do not conform to Python dict or list get converted to strings using
! 1213: str().
! 1214:
! 1215: ## Connecting to the daemon ##
! 1216:
! 1217: To create a connection to the daemon, a socket can be passed to the _Session_
! 1218: constructor. If none is passed, a default Unix socket at _/var/run/charon.vici_
! 1219: is used:
! 1220:
! 1221: import vici
! 1222: import socket
! 1223:
! 1224: s = socket.socket(socket.AF_UNIX)
! 1225: s.connect("/var/run/charon.vici")
! 1226: v = vici.Session(s)
! 1227:
! 1228: ## A simple client request ##
! 1229:
! 1230: An example to print the daemon version information is as simple as:
! 1231:
! 1232: ver = v.version()
! 1233:
! 1234: print "{daemon} {version} ({sysname}, {release}, {machine})".format(**ver)
! 1235:
! 1236: ## A request with response iteration ##
! 1237:
! 1238: The _Session_ class returns an iterable Python generator for streamed events to
! 1239: continuously stream objects to the caller. The following example lists all
! 1240: loaded connections using the _list-conns_ command and implicitly the _list-conn_
! 1241: event:
! 1242:
! 1243: for conn in v.list_conns():
! 1244: for key in conn:
! 1245: print key
! 1246:
! 1247: Please note that if the returned generator is not iterated completely, it must
! 1248: be closed using _close()_. This is implicitly done when breaking from a loop,
! 1249: but an explicit call may be required when directly iterating the generator with
! 1250: _next()_.
! 1251:
! 1252: ## Sorting in dictionaries ##
! 1253:
! 1254: In VICI, in some message trees the order of objects in dictionary matters. In
! 1255: contrast to ruby Hashes, Python dictionaries do not preserve order of added
! 1256: objects. It is therefore recommended to use OrderedDicts instead of the default
! 1257: dictionaries. Objects returned by the library use OrderedDicts.
! 1258:
! 1259: ## API documentation ##
! 1260:
! 1261: For more details about the Python egg refer to the comments in the Python source
! 1262: code.
! 1263:
! 1264: # Vici::Session Perl CPAN module #
! 1265:
! 1266: The _Vici::Session Perl CPAN module_ is a pure Perl implementation of the VICI
! 1267: protocol to implement client applications. It is provided in the _perl_
! 1268: subdirectory, and gets built and installed if strongSwan has been
! 1269: _./configure_'d with_--enable-vici_ and _--enable-perl-cpan_.
! 1270:
! 1271: The _Vici::Session_ module provides a _new()_ constructor for a high level
! 1272: interface, the underlying _Vici::Packet_ and _Vici::Transport_ classes are
! 1273: usually not required to build Perl applications using VICI. The _Vici::Session_
! 1274: class provides methods for the supported VICI commands. The auxiliary
! 1275: _Vici::Message_ class is used to encode configuration parameters sent to
! 1276: the daemon and decode data returned by the daemon.
! 1277:
! 1278: ## Connecting to the daemon ##
! 1279:
! 1280: use IO::Socket::UNIX;
! 1281: use Vici::Session;
! 1282: use Vici::Message;
! 1283:
! 1284: my $socket = IO::Socket::UNIX->new(
! 1285: Type => SOCK_STREAM,
! 1286: Peer => '/var/run/charon.vici',
! 1287: ) or die "Vici socket: $!";
! 1288:
! 1289: my $session = Vici::Session->new($socket);
! 1290:
! 1291: ## A simple client request ##
! 1292:
! 1293: An example to print the daemon version information is as simple as:
! 1294:
! 1295: my $version = $session->version()->hash();
! 1296:
! 1297: foreach my $key ('daemon', 'version', 'sysname', 'release', 'machine' ) {
! 1298: print $version->{$key}, " ";
! 1299: }
! 1300:
! 1301: The _Vici::Session_ methods are explained in the perl/Vici-Session/README.pod
! 1302: document.
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