vici: Document NTLM secrets in README.md
[strongswan.git] / src / libcharon / plugins / vici / README.md
index b9531d8..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,8 @@ Initiates an SA while streaming _control-log_ events.
 
        {
                child = <CHILD_SA configuration name to initiate>
-               timeout = <timeout in seconds before returning>
+               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>
        } => {
@@ -266,6 +267,9 @@ Initiates an SA while streaming _control-log_ events.
                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.
+
 ### terminate() ###
 
 Terminates an SA while streaming _control-log_ events.
@@ -273,21 +277,60 @@ 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>
+               child-id = <terminate a CHILD_SA by its reqid>
+               ike-id = <terminate an IKE_SA by its unique id>
+               timeout = <timeout in ms before returning>
                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
+supported by the peer.
+
+       {
+               ike = <redirect an IKE_SA by configuration name>
+               ike-id = <redirect an IKE_SA by its unique id>
+               peer-ip = <redirect an IKE_SA with matching peer IP, may also be a
+                                  subnet in CIDR notation or an IP range>
+               peer-id = <redirect an IKE_SA with matching peer identity, may contain
+                                  wildcards>
+       } => {
+               success = <yes or no>
+               matches = <number of matched SAs>
+               errmsg = <error string on failure>
+       }
+
 ### install() ###
 
 Install 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>
        } => {
                success = <yes or no>
                errmsg = <error string on failure>
@@ -299,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>
@@ -312,7 +357,7 @@ 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>
+               ike-id = <filter listed IKE_SA by its unique id>
        } => {
                # completes after streaming list-sa events
        }
@@ -327,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
        }
@@ -361,7 +407,9 @@ call includes all certificates known by the daemon, not only those loaded
 over vici.
 
        {
-               type = <certificate type to filter for, or ANY>
+               type = <certificate type to filter for, X509|X509_AC|X509_CRL|
+                                                                                               OCSP_RESPONSE|PUBKEY  or ANY>
+               flag = <X.509 certificate flag to filter for, NONE|CA|AA|OCSP or ANY>
                subject = <set to list only certificates having subject>
        } => {
                # completes after streaming list-cert events
@@ -419,7 +467,8 @@ Unload a previously loaded connection definition by name.
 Load a certificate into the daemon.
 
        {
-               type = <certificate type, X509|X509CA|X509AA|X509CRL|X509AC>
+               type = <certificate type, X509|X509_AC|X509_CRL>
+               flag = <X.509 certificate flag, NONE|CA|AA|OCSP>
                data = <PEM or DER encoded certificate data>
        } => {
                success = <yes or no>
@@ -431,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>
@@ -453,6 +544,42 @@ 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
+only certificates of a given type, e.g. all cached CRLs.
+
+       {
+               type = <certificate type to filter for, X509|X509_AC|X509_CRL|
+                                                                                               OCSP_RESPONSE|PUBKEY or ANY>
+       } => {
+               success = <yes or no>
+               errmsg = <error string on failure>
+       }
+
 ### clear-creds() ###
 
 Clear all loaded certificate, private key and shared key credentials. This
@@ -528,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>
@@ -544,6 +672,45 @@ List the currently loaded pools.
                }
        }
 
+### get-algorithms() ###
+
+List currently loaded algorithms and their implementation.
+
+       {} => {
+               <algorithm type> = {
+                       <algorithm> = <plugin providing the 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
@@ -588,8 +755,10 @@ command.
                        version = <IKE version, 1 or 2>
                        state = <IKE_SA state name>
                        local-host = <local IKE endpoint address>
+                       local-port = <local IKE endpoint port>
                        local-id = <local IKE identity>
                        remote-host = <remote IKE endpoint address>
+                       remote-port = <remote IKE endpoint port>
                        remote-id = <remote IKE identity>
                        remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
                        remote-eap-id = <remote EAP identity, if EAP-authenticated>
@@ -625,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>
@@ -636,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>
@@ -669,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>
@@ -694,6 +870,8 @@ _list-conns_ command.
                                <list of valid remote IKE endpoint addresses>
                        ]
                        version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
+                       reauth_time = <IKE_SA reauthentication interval in seconds>
+                       rekey_time = <IKE_SA rekeying interval in seconds>
 
                        local*, remote* = { # multiple local and remote auth sections
                                class = <authentication type>
@@ -718,6 +896,9 @@ _list-conns_ command.
                        children = {
                                <CHILD_SA config name>* = {
                                        mode = <IPsec mode>
+                                       rekey_time = <CHILD_SA rekeying interval in seconds>
+                                       rekey_bytes = <CHILD_SA rekeying interval in bytes>
+                                       rekey_packets = <CHILD_SA rekeying interval in packets>
                                        local-ts = [
                                                <list of local traffic selectors>
                                        ]
@@ -735,9 +916,13 @@ The _list-cert_ event is issued to stream loaded certificates during an active
 _list-certs_ command.
 
        {
-               type = <certificate type>
+               type = <certificate type, X509|X509_AC|X509_CRL|OCSP_RESPONSE|PUBKEY>
+               flag = <X.509 certificate flag, NONE|CA|AA|OCSP>
                has_privkey = <set if a private key for the certificate is available>
                data = <ASN1 encoded certificate data>
+               subject = <subject string if defined and certificate type is PUBKEY>
+               not-before = <time string if defined and certificate type is PUBKEY>
+               not-after  = <time string if defined and certificate type is PUBKEY>
        }
 
 ### list-authority ###
@@ -763,7 +948,7 @@ information during an active_list-authorities_ command.
 The _ike-updown_ event is issued when an IKE_SA is established or terminated.
 
        {
-               up = <yes or no>
+               up = <set if up event>
                <IKE_SA config name> = {
                        <same data as in the list-sas event, but without child-sas section>
                }
@@ -789,7 +974,7 @@ The _ike-rekey_ event is issued when an IKE_SA is rekeyed.
 The _child-updown_ event is issued when a CHILD_SA is established or terminated.
 
        {
-               up = <yes or no>
+               up = <set if up event>
                <IKE_SA config name> = {
                        <same data as in the list-sas event, but with only the affected
                         CHILD_SA in the child-sas section>
@@ -1068,3 +1253,43 @@ dictionaries. Objects returned by the library use OrderedDicts.
 
 For more details about the Python egg refer to the comments in the Python source
 code.
+
+# Vici::Session Perl CPAN module #
+
+The _Vici::Session Perl CPAN module_ is a pure Perl implementation of the VICI
+protocol to implement client applications. It is provided in the _perl_
+subdirectory, and gets built and installed if strongSwan has been
+ _./configure_'d with_--enable-vici_ and _--enable-perl-cpan_.
+
+The _Vici::Session_ module provides a _new()_ constructor for a high level
+interface, the underlying _Vici::Packet_ and _Vici::Transport_ classes are
+usually not required to build Perl applications using VICI. The _Vici::Session_
+class provides methods for the supported VICI commands. The auxiliare
+ _Vici::Message_ class is used to encode configuration parameters sent to
+the daemon and decode data returned by the daemon.
+
+## Connecting to the daemon ##
+
+       use IO::Socket::UNIX;
+       use Vici::Session;
+       use Vici::Message;
+
+       my $socket = IO::Socket::UNIX->new(
+                       Type => SOCK_STREAM,
+                       Peer => '/var/run/charon.vici',
+       ) or die "Vici socket: $!";
+
+       my $session = Vici::Session->new($socket);
+
+## A simple client request ##
+
+An example to print the daemon version information is as simple as:
+
+       my $version = $session->version()->hash();
+
+       foreach my $key ('daemon', 'version', 'sysname', 'release', 'machine' ) {
+               print $version->{$key}, " ";
+       }
+
+The _Vici::Session_ methods are explained in the perl/Vici-Session/README.pod
+document.