vici: Document the available vici command and event messages

1 files changed, 509 insertions, 1 deletions

diff --git a/src/libcharon/plugins/vici/README.md b/src/libcharon/plugins/vici/README.md
index 598be1fb6..2c3a4df36 100644
--- a/src/libcharon/plugins/vici/README.md
+++ b/src/libcharon/plugins/vici/README.md
@@ -103,7 +103,8 @@ the length field itself.
 
 The interpretation of any value is not defined by the message format; it can
 take arbitrary blobs. The application may specify types for specific keys, such
-as strings or integer representations.
+as strings or integer representations. The vici plugin currently uses
+non-null terminated strings as values only; numbers get encoded as strings.
 
 ### Sections ###
 
@@ -165,6 +166,513 @@ the following C array:
 		1,
 	};
 
+## Client-initiated commands ##
+
+Based on the packet layer, VICI implements commands requested by the client
+and responded to by the server using named _CMD_REQUEST_ and _CMD_RESPONSE_
+packets wrapping messages. The request message may contain command arguments,
+the response message the reply.
+
+Some commands use response streaming, that is, a request triggers a series of
+events to consecutively stream data to the client before the response message
+completes the stream. A client must register for the appropriate event to
+receive the stream, and unregister after the response has been received.
+
+The following client issued commands with the appropriate command input and
+output messages are currently defined:
+
+### version() ###
+
+Returns daemon and system specific version information.
+
+	{} => {
+		daemon = <IKE daemon name>
+		version = <strongSwan version>
+		sysname = <operating system name>
+		release = <operating system release>
+		machine = <hardware identifier>
+	}
+
+### stats() ###
+
+Returns IKE daemon statistics and load information.
+
+	{} => {
+		uptime = {
+			running = <relative uptime in human-readable form>
+			since = <absolute startup time>
+		}
+		workers = {
+			total = <total number of worker threads>
+			idle = <worker threads currently idle>
+			active = {
+				critical = <threads processing "critical" priority jobs>
+				high = <threads processing "high" priority jobs>
+				medium = <threads processing "medium" priority jobs>
+				low = <threads processing "low" priority jobs>
+			}
+		}
+		queues = {
+			critical = <jobs queued with "critical" priority>
+			high = <jobs queued with "high" priority>
+			medium = <jobs queued with "medium" priority>
+			low = <jobs queued with "low" priority>
+		}
+		scheduled = <number of jobs scheduled for timed execution>
+		ikesas = {
+			total = <total number of IKE_SAs active>
+			half-open = <number of IKE_SAs in half-open state>
+		}
+		plugins = [
+			<names of loaded plugins>
+		]
+		mem = { # available if built with leak-detective or on Windows
+			total = <total heap memory usage in bytes>
+			allocs = <total heap allocation blocks>
+			<heap-name>* = { # on Windows only
+				total = <heap memory usage in bytes by this heap>
+				allocs = <allocated blocks for this heap>
+			}
+		}
+		mallinfo = { # available with mallinfo() support
+			sbrk = <non-mmaped space available>
+			mmap = <mmaped space available>
+			used = <total number of bytes used>
+			free = <available but unused bytes>
+		}
+	}
+
+### reload-settings() ###
+
+Reloads _strongswan.conf_ settings and all plugins supporting configuration
+reload.
+
+	{} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### initiate() ###
+
+Initiates an SA while streaming _control-log_ events.
+
+	{
+		child = <CHILD_SA configuration name to initiate>
+		timeout = <timeout in seconds before returning>
+		loglevel = <loglevel to issue "control-log" events for>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure or timeout>
+	}
+
+### terminate() ###
+
+Terminates an SA while streaming _control-log_ events.
+
+	{
+		child = <terminate a CHILD_SA by configuration name>
+		ike = <terminate an IKE_SA by configuration name>
+		child_id = <terminate a CHILD_SA by its reqid>
+		ike_id = <terminate an IKE_SA by its unique id>
+		timeout = <timeout in seconds before returning>
+		loglevel = <loglevel to issue "control-log" events for>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure or timeout>
+	}
+
+### install() ###
+
+Install a trap, drop or bypass policy defined by a CHILD_SA config.
+
+	{
+		child = <CHILD_SA configuration name to install>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### uninstall() ###
+
+Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
+
+	{
+		child = <CHILD_SA configuration name to install>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### list-sas() ###
+
+Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
+events.
+
+	{
+		noblock = <use non-blocking mode if key is set>
+		ike = <filter listed IKE_SAs by its name>
+		ike_id = <filter listed IKE_SA by its unique id>
+	} => {
+		# completes after streaming list-sa events
+	}
+
+### list-policies() ###
+
+List currently installed trap, drop and bypass policies by streaming
+_list-policy_ events.
+
+	{
+		drop = <set to yes to list drop policies>
+		pass = <set to yes to list bypass policies>
+		trap = <set to yes to list trap policies>
+		child = <filter by CHILD_SA configuration name>
+	} => {
+		# completes after streaming list-sa events
+	}
+
+### list-conns() ###
+
+List currently loaded connections by streaming _list-conn_ events. This
+call includes all connections known by the daemon, not only those loaded
+over vici.
+
+	{
+		ike = <list connections matching a given configuration name only>
+	} => {
+		# completes after streaming list-conn events
+	}
+
+### get-conns() ###
+
+Return a list of connection names loaded exclusively over vici, not including
+connections found in other backends.
+
+	{} => {
+		conns = [
+			<list of connection names>
+		]
+	}
+
+### list-certs() ###
+
+List currently loaded certificates by streaming _list-cert_ events. This
+call includes all certificates known by the daemon, not only those loaded
+over vici.
+
+	{
+		type = <certificate type to filter for, or ANY>
+		subject = <set to list only certificates having subject>
+	} => {
+		# completes after streaming list-cert events
+	}
+
+### load-conn() ###
+
+Load a single connection definition into the daemon. An existing connection
+with the same name gets updated or replaced.
+
+	{
+		<IKE_SA config name> = {
+			# IKE configuration parameters with authentication and CHILD_SA
+			# subsections. Refer to swanctl.conf(5) for details.
+		} => {
+			success = <yes or no>
+			errmsg = <error string on failure>
+		}
+	}
+
+### unload-conn() ###
+
+Unload a previously loaded connection definition by name.
+
+	{
+		name = <IKE_SA config name>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### load-cert() ###
+
+Load a certificate into the daemon.
+
+	{
+		type = <certificate type, X509|X509CA|X509AA|X509CRL|X509AC>
+		data = <PEM or DER encoded certificate data>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### load-key() ###
+
+Load a private key into the daemon.
+
+	{
+		type = <private key type, RSA|ECDSA>
+		data = <PEM or DER encoded key data>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### load-shared() ###
+
+Load a shared IKE PSK, EAP or XAuth secret into the daemon.
+
+	{
+		type = <private key type, IKE|EAP|XAUTH>
+		data = <raw shared key data>
+		owners = [
+			<list of shared key owner identities>
+		]
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### clear-creds() ###
+
+Clear all loaded certificate, private key and shared key credentials. This
+affects only credentials loaded over vici, but additionally flushes the
+credential cache.
+
+	{} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### load-pool() ###
+
+Load an in-memory virtual IP and configuration attribute pool. Existing
+pools with the same name get updated, if possible.
+
+	{
+		<pool name> = {
+			addrs = <subnet of virtual IP pool addresses>
+			<attribute type>* = [
+				# attribute type is one of address, dns, nbns, dhcp, netmask,
+				# server, subnet, split_include, split_exclude or a numerical
+				# attribute type identifier.
+				<list of attributes for type>
+			]
+		}
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### unload-pool() ###
+
+Unload a previously loaded virtual IP and configuration attribute pool.
+Unloading fails for pools with leases currently online.
+
+	{
+		name = <virtual IP address pool to delete>
+	} => {
+		success = <yes or no>
+		errmsg = <error string on failure>
+	}
+
+### get-pools() ###
+
+List the currently loaded pools.
+
+	{} => {
+		<pool name>* = {
+			base = <virtual IP pool base address>
+			size = <total number of addresses in the pool>
+			online = <number of leases online>
+			offline = <number of leases offline>
+		}
+	}
+
+## Server-issued events ##
+
+Based on the packet layer, the vici plugin raises event messages using named
+EVENT packets wrapping messages. The message contains event details.
+
+### log ###
+
+The _log_ event is issued to registered clients for each debug log message.
+This event is not associated with a command.
+
+	{
+		group = <subsystem identifier for debug message>
+		level = <log level, 0-4>
+		thread = <numerical thread identifier issuing the log message>
+		ikesa-name = <name of IKE_SA, if log is associated with any>
+		ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
+		msg = <log message text>
+	}
+
+### control-log ###
+
+The _control-log_ event is issued for log events during active _initiate_ or
+_terminate_ commands. It is issued only to clients currently having such
+a command active.
+
+	{
+		group = <subsystem identifier for debug message>
+		level = <log level, 0-4>
+		ikesa-name = <name of IKE_SA, if log associated with any>
+		ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
+		msg = <log message text>
+	}
+
+### list-sa ###
+
+The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
+command.
+
+	{
+		<IKE_SA config name> = {
+			uniqueid = <IKE_SA unique identifier>
+			version = <IKE version, 1 or 2>
+			state = <IKE_SA state name>
+			local-host = <local IKE endpoint address>
+			local-id = <local IKE identity>
+			remote-host = <remote IKE endpoint address>
+			remote-id = <remote IKE identity>
+			remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
+			remote-eap-id = <remote EAP identity, if EAP-authenticated>
+			initiator = <yes, if initiator of IKE_SA>
+			initiator-spi = <hex encoded initiator SPI / cookie>
+			responder-spi = <hex encoded responder SPI / cookie>
+			encr-alg = <IKE encryption algorithm string>
+			encr-keysize = <key size for encr-alg, if applicable>
+			integ-alg = <IKE integrity algorithm string>
+			integ-keysize = <key size for encr-alg, if applicable>
+			prf-alg = <IKE pseudo random function string>
+			dh-group = <IKE Diffie-Hellman group string>
+			established = <seconds the IKE_SA has been established>
+			rekey-time = <seconds before IKE_SA gets rekeyed>
+			reauth-time = <seconds before IKE_SA gets re-authenticated>
+			tasks-queued = [
+				<list of currently queued tasks for execution>
+			]
+			tasks-active = [
+				<list of tasks currently initiating actively>
+			]
+			tasks-passive = [
+				<list of tasks currently handling passively>
+			]
+			child-sas = {
+				<child-sa-name>* = {
+					reqid = <reqid of CHILD_SA>
+					state = <state string of CHILD_SA>
+					mode = <IPsec mode, tunnel|transport|beet>
+					protocol = <IPsec protocol AH|ESP>
+					encap = <yes if using UDP encapsulation>
+					spi-in = <hex encoded inbound SPI>
+					spi-out = <hex encoded outbound SPI>
+					cpi-in = <hex encoded inbound CPI, if using compression>
+					cpi-out = <hex encoded outbound CPI, if using compression>
+					encr-alg = <ESP encryption algorithm name, if any>
+					encr-keysize = <ESP encryption key size, if applicable>
+					integ-alg = <ESP or AH integrity algorithm name, if any>
+					integ-keysize = <ESP or AH integrity key size, if applicable>
+					prf-alg = <CHILD_SA pseudo random function name>
+					dh-group = <CHILD_SA PFS rekeying DH group name, if any>
+					esn = <1 if using extended sequence numbers>
+					bytes-in = <number of input bytes processed>
+					packets-in = <number of input packets processed>
+					use-in = <seconds since last inbound packet, if any>
+					bytes-out = <number of output bytes processed>
+					packets-out = <number of output packets processed>
+					use-out = <seconds since last outbound packet, if any>
+					rekey-time = <seconds before CHILD_SA gets rekeyed>
+					life-time = <seconds before CHILD_SA expires>
+					install-time = <seconds the CHILD_SA has been installed>
+					local-ts = [
+						<list of local traffic selectors>
+					]
+					remote-ts = [
+						<list of remote traffic selectors>
+					]
+				}
+			}
+		}
+	}
+
+### list-policy ###
+
+The _list-policy_ event is issued to stream installed policies during an active
+_list-policies_ command.
+
+	{
+		<child-sa-config-name> = {
+			mode = <policy mode, tunnel|transport|pass|drop>
+			local-ts = [
+				<list of local traffic selectors>
+			]
+			remote-ts = [
+				<list of remote traffic selectors>
+			]
+		}
+	}
+
+### list-conn ###
+
+The _list-conn_ event is issued to stream loaded connection during an active
+_list-conns_ command.
+
+	{
+		<IKE_SA connection name> = {
+			local_addrs = [
+				<list of valid local IKE endpoint addresses>
+			]
+			remote_addrs = [
+				<list of valid remote IKE endpoint addresses>
+			]
+			version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
+
+			local*, remote* = { # multiple local and remote auth sections
+				class = <authentication type>
+				eap-type = <EAP type to authenticate if when using EAP>
+				eap-vendor = <EAP vendor for type, if any>
+				xauth = <xauth backend name>
+				revocation = <revocation policy>
+				id = <IKE identity>
+				aaa_id = <AAA authentication backend identity>
+				eap_id = <EAP identity for authentication>
+				xauth_id = <XAuth username for authentication>
+				groups = [
+					<group membership required to use connection>
+				]
+				certs = [
+					<certificates allowed for authentication>
+				]
+				cacerts = [
+					<CA certificates allowed for authentication>
+				]
+			}
+			children = {
+				<CHILD_SA config name>* = {
+					mode = <IPsec mode>
+					local-ts = [
+						<list of local traffic selectors>
+					]
+					remote-ts = [
+						<list of remote traffic selectors>
+					]
+				}
+			}
+		}
+	}
+
+### list-cert ###
+
+The _list-cert_ event is issued to stream loaded certificates during an active
+_list-certs_ command.
+
+	{
+		type = <certificate type>
+		has_privkey = <set if a private key for the certificate is available>
+		data = <ASN1 encoded certificate data>
+	}
+
+
 # libvici C client library #
 
 libvici is the reference implementation of a C client library implementing