summaryrefslogtreecommitdiff
path: root/src/libcharon/plugins/vici/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'src/libcharon/plugins/vici/README.md')
-rw-r--r--src/libcharon/plugins/vici/README.md109
1 files changed, 101 insertions, 8 deletions
diff --git a/src/libcharon/plugins/vici/README.md b/src/libcharon/plugins/vici/README.md
index 18a3ef7b5..9bda949d0 100644
--- a/src/libcharon/plugins/vici/README.md
+++ b/src/libcharon/plugins/vici/README.md
@@ -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
}
@@ -466,12 +487,53 @@ Load a private key into the daemon.
errmsg = <error string on failure>
}
+### 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.
{
- type = <private key type, IKE|EAP|XAUTH>
+ id = <optional unique identifier of this shared key>
+ type = <shared key type, IKE|EAP|XAUTH>
data = <raw shared key data>
owners = [
<list of shared key owner identities>
@@ -481,6 +543,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 or XAuth 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 +654,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>
@@ -678,7 +764,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 +776,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 +813,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>
generated by cgit v1.2.3 (git 2.39.1) at 2025-02-01 08:21:18 +0000