vici: Document NTLM secrets in README.md
[strongswan.git] / src / libcharon / plugins / vici / README.md
index 18a3ef7..49cce37 100644 (file)
@@ -1,8 +1,8 @@
 # The Versatile IKE Control Interface (VICI) protocol #
 
-The vici plugin implements the server side of an IPC protocol to configure,
-monitor and control the IKE daemon charon. It uses request/response and event
-messages to communicate over a reliable stream based transport.
+The vici _[ˈvitʃi]_ plugin implements the server side of an IPC protocol to
+configure, monitor and control the IKE daemon charon. It uses request/response
+and event messages to communicate over a reliable stream based transport.
 
 ## Transport protocol ##
 
@@ -258,7 +258,7 @@ Initiates an SA while streaming _control-log_ events.
 
        {
                child = <CHILD_SA configuration name to initiate>
-               ike = <optional IKE_SA configuraiton name to find child under>
+               ike = <optional IKE_SA configuration name to find child under>
                timeout = <timeout in ms before returning>
                init-limits = <whether limits may prevent initiating the CHILD_SA>
                loglevel = <loglevel to issue "control-log" events for>
@@ -283,12 +283,29 @@ Terminates an SA while streaming _control-log_ events.
                loglevel = <loglevel to issue "control-log" events for>
        } => {
                success = <yes or no>
+               matches = <number of matched SAs>
+               terminated = <number of terminated SAs>
                errmsg = <error string on failure or timeout>
        }
 
 The default timeout of 0 waits indefinitely for a result, and a timeout value
 of -1 returns a result immediately.
 
+### rekey() ###
+
+Initiate the rekeying of an SA.
+
+       {
+               child = <rekey a CHILD_SA by configuration name>
+               ike = <rekey an IKE_SA by configuration name>
+               child-id = <rekey a CHILD_SA by its reqid>
+               ike-id = <rekey an IKE_SA by its unique id>
+       } => {
+               success = <yes or no>
+               matches = <number of matched SAs>
+               errmsg = <error string on failure>
+       }
+
 ### redirect() ###
 
 Redirect a client-initiated IKE_SA to another gateway.  Only for IKEv2 and if
@@ -303,6 +320,7 @@ supported by the peer.
                                   wildcards>
        } => {
                success = <yes or no>
+               matches = <number of matched SAs>
                errmsg = <error string on failure>
        }
 
@@ -312,7 +330,7 @@ Install a trap, drop or bypass policy defined by a CHILD_SA config.
 
        {
                child = <CHILD_SA configuration name to install>
-               ike = <optional IKE_SA configuraiton name to find child under>
+               ike = <optional IKE_SA configuration name to find child under>
        } => {
                success = <yes or no>
                errmsg = <error string on failure>
@@ -324,6 +342,8 @@ Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
 
        {
                child = <CHILD_SA configuration name to install>
+               ike = <optional IKE_SA configuration name to find child under,
+                          if not given the first policy matching child is removed>
        } => {
                success = <yes or no>
                errmsg = <error string on failure>
@@ -352,6 +372,7 @@ _list-policy_ events.
                pass = <set to yes to list bypass policies>
                trap = <set to yes to list trap policies>
                child = <filter by CHILD_SA configuration name>
+               ike = <filter by IKE_SA configuration name>
        } => {
                # completes after streaming list-sa events
        }
@@ -459,19 +480,61 @@ Load a certificate into the daemon.
 Load a private key into the daemon.
 
        {
-               type = <private key type, RSA|ECDSA>
+               type = <private key type, rsa|ecdsa|bliss|any>
                data = <PEM or DER encoded key data>
        } => {
                success = <yes or no>
                errmsg = <error string on failure>
+               id = <hex-encoded SHA-1 key identifier of the public key on success>
+       }
+
+### unload-key() ###
+
+Unload the private key with the given key identifier.
+
+       {
+               id = <hex-encoded SHA-1 key identifier of the private key to unload>
+       } => {
+               success = <yes or no>
+               errmsg = <error string on failure>
+       }
+
+### get-keys() ###
+
+Return a list of identifiers of private keys loaded exclusively over vici, not
+including keys found in other backends.
+
+       {} => {
+               keys = [
+                       <list of hex-encoded SHA-1 key identifiers>
+               ]
+       }
+
+### load-token() ###
+
+Load a private key located on a token into the daemon.  Such keys may be listed
+and unloaded using the _get-keys_ and _unload-key_ commands, respectively (based
+on the key identifier derived from the public key).
+
+       {
+               handle = <hex-encoded CKA_ID of the private key on token>
+               slot = <optional slot number>
+               module = <optional PKCS#11 module>
+               pin = <optional PIN to access the key, has to be provided via other
+                          means if not given>
+       } => {
+               success = <yes or no>
+               errmsg = <error string on failure>
+               id = <hex-encoded SHA-1 key identifier of the public key on success>
        }
 
 ### load-shared() ###
 
-Load a shared IKE PSK, EAP or XAuth secret into the daemon.
+Load a shared IKE PSK, EAP, XAuth or NTLM secret into the daemon.
 
        {
-               type = <private key type, IKE|EAP|XAUTH>
+               id = <optional unique identifier of this shared key>
+               type = <shared key type, IKE|EAP|XAUTH|NTLM>
                data = <raw shared key data>
                owners = [
                        <list of shared key owner identities>
@@ -481,6 +544,29 @@ Load a shared IKE PSK, EAP or XAuth secret into the daemon.
                errmsg = <error string on failure>
        }
 
+### unload-shared() ###
+
+Unload a previously loaded shared IKE PSK, EAP, XAuth or NTLM secret by its
+unique identifier.
+
+       {
+               id = <unique identifier of the shared key to unload>
+       } => {
+               success = <yes or no>
+               errmsg = <error string on failure>
+       }
+
+### get-shared() ###
+
+Return a list of unique identifiers of shared keys loaded exclusively over vici,
+not including keys found in other backends.
+
+       {} => {
+               keys = [
+                       <list of unique identifiers>
+               ]
+       }
+
 ### flush-certs() ###
 
 Flushes the certificate cache. The optional type argument allows to flush
@@ -569,6 +655,7 @@ List the currently loaded pools.
 
        {
                leases = <set to yes to include leases>
+               name = <optional name of the pool to query>
        } => {
                <pool name>* = {
                        base = <virtual IP pool base address>
@@ -595,6 +682,35 @@ List currently loaded algorithms and their implementation.
                }
        }
 
+### get-counters() ###
+
+List global or connection-specific counters for several IKE events.
+
+       {
+               name = <optional connection name, omit for global counters>
+               all = <yes to get counters for all connections, name is ignored>
+       } => {
+               counters = {
+                       <name|empty for global counters> = {
+                               <pairs of counter name and 64-bit counter value>
+                       }
+               }
+               success = <yes or no>
+               errmsg = <error string on failure>
+       }
+
+### reset-counters() ###
+
+Reset global or connection-specific IKE event counters.
+
+       {
+               name = <optional connection name, omit for global counters>
+               all = <yes to reset counters for all connections, name is ignored>
+       } => {
+               success = <yes or no>
+               errmsg = <error string on failure>
+       }
+
 ## Server-issued events ##
 
 Based on the packet layer, the vici plugin raises event messages using named
@@ -678,7 +794,8 @@ command.
                                <list of tasks currently handling passively>
                        ]
                        child-sas = {
-                               <child-sa-name>* = {
+                               <unique child-sa-name>* = {
+                                       name = <name of the CHILD_SA>
                                        uniqueid = <unique CHILD_SA identifier>
                                        reqid = <reqid of CHILD_SA>
                                        state = <state string of CHILD_SA>
@@ -689,6 +806,10 @@ command.
                                        spi-out = <hex encoded outbound SPI>
                                        cpi-in = <hex encoded inbound CPI, if using compression>
                                        cpi-out = <hex encoded outbound CPI, if using compression>
+                                       mark-in = <hex encoded inbound Netfilter mark value>
+                                       mark-mask-in = <hex encoded inbound Netfilter mark mask>
+                                       mark-out = <hex encoded outbound Netfilter mark value>
+                                       mark-mask-out = <hex encoded outbound Netfilter mark mask>
                                        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>
@@ -722,7 +843,9 @@ The _list-policy_ event is issued to stream installed policies during an active
 _list-policies_ command.
 
        {
-               <child-sa-config-name> = {
+               <ike-sa-config-name/child-sa-config-name> = {
+                       child = <CHILD_SA configuration name>
+                       ike = <IKE_SA configuration name or namespace, if available>
                        mode = <policy mode, tunnel|transport|pass|drop>
                        local-ts = [
                                <list of local traffic selectors>