vici: Fix message encoding type values in documentation
[strongswan.git] / src / libcharon / plugins / vici / README.md
1 # The Versatile IKE Control Interface (VICI) protocol #
2
3 The vici plugin implements the server side of an IPC protocol to configure,
4 monitor and control the IKE daemon charon. It uses request/response and event
5 messages to communicate over a reliable stream based transport.
6
7 ## Transport protocol ##
8
9 To provide the service, the plugin opens a listening socket using a reliable,
10 stream based transport. charon relies on the different stream service
11 abstractions provided by libstrongswan, such as TCP and UNIX sockets.
12
13 A client connects to this service to access functionality. It may send an
14 arbitrary number of packets over the connection before closing it.
15
16 To exchange data, the transport protocol is segmented into byte sequences.
17 Each byte sequence is prefixed by a 32-bit length header in network order,
18 followed by the data. The maximum segment length is currently limited to 512KB
19 of data, and the length field contains the length of the data only, not
20 including the length field itself.
21
22 The order of byte sequences must be strict, byte sequences must arrive in the
23 same order as sent.
24
25 ## Packet layer ##
26
27 Within the byte sequences defined by the transport layer, both the client
28 and the server can exchange packets. The type of packet defines its structure
29 and purpose. The packet type is a 8-bit identifier, and is the first byte
30 in a transport layer byte sequence. The length of the packet is given by the
31 transport layer.
32
33 While a packet type may define the format of the wrapped data freely, currently
34 all types either contain a name, a message or both. The following packet types
35 are currently defined:
36
37 * _CMD_REQUEST = 0_: A named request message
38 * _CMD_RESPONSE = 1_: An unnamed response message for a request
39 * _CMD_UNKNOWN = 2_: An unnamed response if requested command is unknown
40 * _EVENT_REGISTER = 3_: A named event registration request
41 * _EVENT_UNREGISTER = 4_: A named event deregistration request
42 * _EVENT_CONFIRM = 5_: An unnamed response for successful event (de-)registration
43 * _EVENT_UNKNOWN = 6_: A unnamed response if event (de-)registration failed
44 * _EVENT = 7_: A named event message
45
46 For packets having a named type, after the packet type an 8-bit length header
47 of the name follows, indicating the string length in bytes of the name tag, not
48 including the length field itself. The name is an ASCII string that is not
49 null-terminated.
50
51 The rest of the packet forms the exchanged message, the length is determined
52 by the transport byte sequence length, subtracting the packet type and
53 the optional name tag in some messages.
54
55 ### Commands ###
56
57 Commands are currently always requested by the client. The server replies with
58 a response, or with a CMD_UNKNOWN failure message to let the client know
59 that it does not have a handler for such a command. There is no sequence number
60 to associate responses to requests, so only one command can be active at
61 a time on a single connection.
62
63 ### Events ###
64
65 To receive event messages, the client explicitly registers for events by name,
66 and also unregisters if it does not want to receive events of the named kind
67 anymore. The server confirms event registration using EVENT_CONFIRM, or
68 indicates that there is no such event source with EVENT_UNKNOWN.
69
70 Events may get raised at any time while registered, even during an active
71 request command. This mechanism is used to feed continuous data during a request,
72 for example.
73
74 ## Message format ##
75
76 The defined packet types optionally wrap a message with additional data.
77 Messages are currently used in CMD_REQUEST/CMD_RESPONSE, and in EVENT packets.
78 A message uses a hierarchial tree of sections. Each section (or the implicit
79 root section) contains an arbitrary set of key/value pairs, lists and
80 sub-sections. The length of a message is not part of the message itself, but
81 the wrapping layer, usually calculated from the transport byte sequence length.
82
83 The message encoding consists of a sequence of elements. Each element starts
84 with the element type, optionally followed by an element name and/or an element
85 value. Currently the following message element types are defined:
86
87 * _SECTION_START = 1_: Begin a new section having a name
88 * _SECTION_END = 2_: End a previously started section
89 * _KEY_VALUE = 3_: Define a value for a named key in the current section
90 * _LIST_START = 4_: Begin a named list for list items
91 * _LIST_ITEM = 5_: Define an unnamed item value in the current list
92 * _LIST_END = 6_: End a previously started list
93
94 Types are encoded as 8-bit values. Types having a name (SECTION_START,
95 KEY_VALUE and LIST_START) have an ASCII string following the type, which itself
96 uses an 8-bit length header. The string must not be null-terminated, the string
97 length does not include the length field itself.
98
99 Types having a value (KEY_VALUE and LIST_ITEM) have a raw blob sequence,
100 prefixed with a 16-bit network order length. The blob follows the type or the
101 name tag if available, the length defined by the length field does not include
102 the length field itself.
103
104 The interpretation of any value is not defined by the message format; it can
105 take arbitrary blobs. The application may specify types for specific keys, such
106 as strings or integer representations.
107
108 ### Sections ###
109
110 Sections may be opened in the implicit root section, or any previously section.
111 They can be nested to arbitrary levels. A SECTION_END marker always closes
112 the last opened section; SECTION_START and SECTION_END items must be balanced
113 in a valid message.
114
115 ### Key/Values ###
116
117 Key/Value pair elements may appear in the implicit root section or any explicit
118 sub-section at any level. Key names must be unique in the current section, use
119 lists to define multiple values for a key. Key/values may not appear in lists,
120 use a sub-section instead.
121
122 ### Lists ###
123
124 Lists may appear at the same locations as Key/Values, and may not be nested.
125 Only a single list may be opened at the same time, and all lists must be closed
126 in valid messages. After opening a list, only list items may appear before the
127 list closing element. Empty lists are allowed, list items may appear within
128 lists only.
129
130 ### Encoding example ###
131
132 Consider the following structure using pseudo-markup for this example:
133
134         key1 = value1
135         section1 = {
136                 sub-section = {
137                         key2 = value2
138                 }
139                 list1 = [ item1, item2 ]
140         }
141
142 The example above reprensents a valid tree structure, that gets encoded as
143 the following C array:
144
145         char msg[] = {
146                 /* key1 = value1 */
147                 2, 4,'k','e','y','1', 0,6,'v','a','l','u','e','1',
148                 /* section1 */
149                 0, 8,'s','e','c','t','i','o','n','1',
150                 /* sub-section */
151                 0, 11,'s','u','b','-','s','e','c','t','i','o','n',
152                 /* key2 = value2 */
153                 2, 4,'k','e','y','2', 0,6,'v','a','l','u','e','2',
154                 /* sub-section end */
155                 1,
156                 /* list1 */
157                 3, 5, 'l','i','s','t','1',
158                 /* item1 */
159                 4, 0,5,'i','t','e','m','1',
160                 /* item2 */
161                 4, 0,5,'i','t','e','m','2',
162                 /* list1 end */
163                 5,
164                 /* section1 end */
165                 1,
166         };
167
168 # libvici C client library #
169
170 libvici is the reference implementation of a C client library implementing
171 the vici protocol. It builds upon libstrongswan, but provides a stable API
172 to implement client applications in the C programming language. libvici uses
173 the libstrongswan thread pool to deliver event messages asynchronously.
174
175 More information about the libvici API is available in the libvici.h header
176 file.