From ff3217db4bf9b3cdacb54c3e52a78d39a62802f1 Mon Sep 17 00:00:00 2001 From: Martin Willi Date: Tue, 11 Mar 2014 18:36:22 +0100 Subject: [PATCH] vici: Add low-level IPC protocol description --- src/libcharon/plugins/vici/Makefile.am | 3 + src/libcharon/plugins/vici/README.md | 176 +++++++++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 src/libcharon/plugins/vici/README.md diff --git a/src/libcharon/plugins/vici/Makefile.am b/src/libcharon/plugins/vici/Makefile.am index 2a99b1391..162827a73 100644 --- a/src/libcharon/plugins/vici/Makefile.am +++ b/src/libcharon/plugins/vici/Makefile.am @@ -29,6 +29,9 @@ libstrongswan_vici_la_SOURCES = \ libstrongswan_vici_la_LDFLAGS = -module -avoid-version +EXTRA_DIST = README.md + + lib_LTLIBRARIES = libvici.la libvici_la_SOURCES = \ diff --git a/src/libcharon/plugins/vici/README.md b/src/libcharon/plugins/vici/README.md new file mode 100644 index 000000000..ff5031e6e --- /dev/null +++ b/src/libcharon/plugins/vici/README.md @@ -0,0 +1,176 @@ +# 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. + +## Transport protocol ## + +To provide the service, the plugin opens a listening socket using a reliable, +stream based transport. charon relies on the different stream service +abstractions provided by libstrongswan, such as TCP and UNIX sockets. + +A client connects to this service to access functionality. It may send an +arbitrary number of packets over the connection before closing it. + +To exchange data, the transport protocol is segmented into byte sequences. +Each byte sequence is prefixed by a 16-bit length header in network order, +followed by the data. The maximum segment length is 65535 bytes, and the length +field contains the length of the data only, not including the length field +itself. + +The order of byte sequences must be strict, byte sequences must arrive in the +same order as sent. + +## Packet layer ## + +Within the byte sequences defined by the transport layer, both the client +and the server can exchange packets. The type of packet defines its structure +and purpose. The packet type is a 8-bit identifier, and is the first byte +in a transport layer byte sequence. The length of the packet is given by the +transport layer. + +While a packet type may define the format of the wrapped data freely, currently +all types either contain a name, a message or both. The following packet types +are currently defined: + +* _CMD_REQUEST = 0_: A named request message +* _CMD_RESPONSE = 1_: An unnamed response message for a request +* _CMD_UNKNOWN = 2_: An unnamed response if requested command is unknown +* _EVENT_REGISTER = 3_: A named event registration request +* _EVENT_UNREGISTER = 4_: A named event deregistration request +* _EVENT_CONFIRM = 5_: An unnamed response for successful event (de-)registration +* _EVENT_UNKNOWN = 6_: A unnamed response if event (de-)registration failed +* _EVENT = 7_: A named event message + +For packets having a named type, after the packet type an 8-bit length header +of the name follows, indicating the string length in bytes of the name tag, not +including the length field itself. The name is an ASCII string that is not +null-terminated. + +The rest of the packet forms the exchanged message, the length is determined +by the transport byte sequence length, subtracting the packet type and +the optional name tag in some messages. + +### Commands ### + +Commands are currently always requested by the client. The server replies with +a response, or with a CMD_UNKNOWN failure message to let the client know +that it does not have a handler for such a command. There is no sequence number +to associate responses to requests, so only one command can be active at +a time on a single connection. + +### Events ### + +To receive event messages, the client explicitly registers for events by name, +and also unregisters if it does not want to receive events of the named kind +anymore. The server confirms event registration using EVENT_CONFIRM, or +indicates that there is no such event source with EVENT_UNKNOWN. + +Events may get raised at any time while registered, even during an active +request command. This mechanism is used to feed continous data during a request, +for example. + +## Message format ## + +The defined packet types optionally wrap a message with additional data. +Messages are currently used in CMD_REQUEST/CMD_RESPONSE, and in EVENT packets. +A message uses a hierarchial tree of sections. Each section (or the implicit +root section) contains an arbitrary set of key/value pairs, lists and +sub-sections. The length of a message is not part of the message itself, but +the wrapping layer, usually calculated from the transport byte sequence length. + +The message encoding consists of a sequence of elements. Each element starts +with the element type, optionally followed by an element name and/or an element +value. Currently the following message element types are defined: + +* _SECTION_START = 0_: Begin a new section having a name +* _SECTION_END = 1_: End a previously started section +* _KEY_VALUE = 2_: Define a value for a named key in the current section +* _LIST_START = 3_: Begin a named list for list items +* _LIST_ITEM = 4_: Define an unnamed item value in the current list +* _LIST_END = 5_: End a previously started list + +Types are encoded as 8-bit values. Types having a name (SECTION_START, +KEY_VALUE and LIST_START) have an ASCII string following the type, which itself +uses an 8-bit length header. The string must not be null-terminated, the string +length does not include the length field itself. + +Types having a value (KEY_VALUE and LIST_ITEM) have a raw blob sequence, +prefixed with a 16-bit network order length. The blob follows the type or the +name tag if available, the length defined by the length field does not include +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. + +### Sections ### + +Sections may be opened in the implicit root section, or any previously section. +They can be nested to arbitrary levels. A SECTION_END marker always closes +the last opened section; SECTION_START and SECTION_END items must be balanced +in a valid message. + +### Key/Values ### + +Key/Value pair elements may appear in the implicit root section or any explicit +sub-section at any level. Key names must be unique in the current section, use +lists to define multiple values for a key. Key/values may not appear in lists, +use a sub-section instead. + +### Lists ### + +Lists may appear at the same locations as Key/Values, and may not be nested. +Only a single list may be opened at the same time, and all lists must be closed +in valid messages. After opening a list, only list items may appear before the +list closing element. Empty lists are allowed, list items may appear within +lists only. + +### Encoding example ### + +Consider the following structure using pseudo-markup for this example: + + key1 = value1 + section1 = { + sub-section = { + key2 = value2 + } + list1 = [ item1, item2 ] + } + +The example above reprensents a valid tree structure, that gets encoded as +the following C array: + + char msg[] = { + /* key1 = value1 */ + 2, 4,'k','e','y','1', 0,6,'v','a','l','u','e','1', + /* section1 */ + 0, 8,'s','e','c','t','i','o','n','1', + /* sub-section */ + 0, 11,'s','u','b','-','s','e','c','t','i','o','n', + /* key2 = value2 */ + 2, 4,'k','e','y','2', 0,6,'v','a','l','u','e','2', + /* sub-section end */ + 1, + /* list1 */ + 3, 5, 'l','i','s','t','1', + /* item1 */ + 4, 0,5,'i','t','e','m','1', + /* item2 */ + 4, 0,5,'i','t','e','m','2', + /* list1 end */ + 5, + /* section1 end */ + 1, + }; + +# libvici C client library # + +libvici is the reference implementation of a C client library implementing +the vici protocol. It builds upon libstrongswan, but provides a stable API +to implement client applications in the C programming language. libvici uses +the libstrongswan thread pool to deliver event messages asynchronously. + +More information about the libvici API is available in the libvici.h header +file.