api+protocol revision 1.1 1 1.1 christos This file documents the protocol that the ISC DHCP server and ISC
2 1.1 christos Object Management clients (clients that use the ISC Object Management
3 1.1 christos API) speak between one another.
4 1.1 christos
5 1.1 christos Protocol:
6 1.1 christos
7 1.1 christos All multi-byte numbers are represented in network byte order.
8 1.1 christos
9 1.1 christos On startup, each side sends a status message indicating what version
10 1.1 christos of the protocol they are speaking. The status message looks like
11 1.1 christos this:
12 1.1 christos
13 1.1 christos +---------+---------+
14 1.1 christos | version | hlength |
15 1.1 christos +---------+---------+
16 1.1 christos
17 1.1 christos version - a 32-bit fixed-point number with the decimal point between
18 1.1 christos the third and second decimal digits from the left,
19 1.1 christos representing the version of the protocol. The current
20 1.1 christos protocol version is 1.00. If the field were considered as
21 1.1 christos a 32-bit integer, this would correspond to a value of 100
22 1.1 christos decimal, or 0x64.
23 1.1 christos
24 1.1 christos hlength - a 32-bit integer representing the length of the fixed-length
25 1.1 christos header in subsequent messages. This is normally 56, but
26 1.1 christos can be changed to a value larger than 56 by either side
27 1.1 christos without upgrading the revision number.
28 1.1 christos
29 1.1 christos
30 1.1 christos The startup message is not authenticated. Either side may reject the
31 1.1 christos other side's startup message as invalid by simply closing the
32 1.1 christos connection. The only fixed part of the startup message is the
33 1.1 christos version number - future versions may delete hlength, or add further
34 1.1 christos startup information.
35 1.1 christos
36 1.1 christos Following the startup message, all messages have the same format.
37 1.1 christos Currently, the format includes a fixed-length header (the length in
38 1.1 christos hlength, above)
39 1.1 christos
40 1.1 christos +--------+----+--------+----+-----+---------+------------+------------+-----+
41 1.1 christos | authid | op | handle | id | rid | authlen | msg values | obj values | sig |
42 1.1 christos +--------+----+--------+----+-----+---------+------------+------------+-----+
43 1.1 christos
44 1.1 christos The fixed-length header consists of:
45 1.1 christos
46 1.1 christos authid = a 32-bit authenticator handle.
47 1.1 christos For an original message (one not in response to some other
48 1.1 christos message), this will be chosen by the originator. For a
49 1.1 christos message in response to another message, the authenticator for
50 1.1 christos that message is used, except if the response is an error
51 1.1 christos message indicating that the authenticator used was unknown,
52 1.1 christos in which case the null authenticator is used. Messages that
53 1.1 christos are generated as the result of a notify registration use the
54 1.1 christos authenticator used in the original notify registration.
55 1.1 christos The authenticator itself is generated by having one side of
56 1.1 christos the connection send an object of type "authenticator" to the
57 1.1 christos other side with values that indicate what kind of
58 1.1 christos authentication mechanism to use and what key to use. The two
59 1.1 christos most likely things here are a Kerberos V principal name or the
60 1.1 christos name of a shared secret that can be used to calculate an MD5
61 1.1 christos hash. The mechanism for doing this has yet to be finalized.
62 1.1 christos If authid is zero, the message is not authenticated.
63 1.1 christos
64 1.1 christos op = 32-bit opcode, one of:
65 1.1 christos open = 1
66 1.1 christos refresh = 2
67 1.1 christos update = 3
68 1.1 christos notify = 4
69 1.1 christos error = 5
70 1.1 christos delete = 6
71 1.1 christos handle = 32-bit object handle
72 1.1 christos A handle on the object being opened, created, refreshed or
73 1.1 christos updated. If no handle is yet available (e.g., with open and
74 1.1 christos new), then the value zero is sent.
75 1.1 christos id = 32-bit transaction id of the message - a monotonically increasing
76 1.1 christos number that starts with some randomly chosen number at the
77 1.1 christos beginning of the life of the connection. The value should never
78 1.1 christos be zero.
79 1.1 christos rid = 32-bit transaction ID of the message to which this message is a
80 1.1 christos response, or zero if this message is not in response to a
81 1.1 christos message from the other side.
82 1.1 christos
83 1.1 christos authlen = a 32-bit number representing the length of the authenticator
84 1.1 christos
85 1.1 christos msg values = a series of name+value pairs, specific to this message.
86 1.1 christos Each name+value pair starts with a 16-bit name length,
87 1.1 christos followed by that many bytes of name, followed by a 32-bit
88 1.1 christos value length, followed by that many bytes of value. If the
89 1.1 christos length is zero, this is a value of the blank string. If the
90 1.1 christos length is all ones (2^32-1), then there is no value - for an
91 1.1 christos update, this means the value for this name and the name
92 1.1 christos itself should be deleted from the object, which may or may
93 1.1 christos not be possible. The list of name/value pairs ends with a
94 1.1 christos zero-length name, which is not followed by a value
95 1.1 christos length/value pair.
96 1.1 christos
97 1.1 christos obj values = a series of name+value pairs, as above, specific to the
98 1.1 christos object being created, updated or refreshed.
99 1.1 christos
100 1.1 christos signature = authlen bytes of data signing the message. The signature
101 1.1 christos algorithm is a property of the authenticator handle.
102 1.1 christos
103 1.1 christos Message types:
104 1.1 christos
105 1.1 christos 1: open
106 1.1 christos relevant input values:
107 1.1 christos object-type = the name of the type of object
108 1.1 christos open:create = boolean - create the object if it doesn't yet exist
109 1.1 christos open:exclusive = boolean - don't open the object if it does exist
110 1.1 christos open:update = boolean - update the object with included values
111 1.1 christos if it matches.
112 1.1 christos the handle should always be the null handle
113 1.1 christos
114 1.1 christos The input value must also contain key information for the type of
115 1.1 christos object being searched that uniquely identifies an object, or search
116 1.1 christos information that matches only one object. Each object has a key
117 1.1 christos specification (a key is something that uniquely identifies an
118 1.1 christos object), so see the key specification for that object to see
119 1.1 christos what to send here. An open message with the create flag set must
120 1.1 christos specify a key, and not merely matching criteria. Some objects may
121 1.1 christos allow more than one key, and it may be that the union of those keys
122 1.1 christos is required to uniquely identify the object, or it may be that any
123 1.1 christos one such key will uniquely identify the object. The documentation
124 1.1 christos for the type of object will specify this.
125 1.1 christos
126 1.1 christos An open message will result in an immediate response message whose
127 1.1 christos opcode will either be "error" or "update". The error message may
128 1.1 christos include an error:reason value containing a text string explaining
129 1.1 christos the error, and will always include an error:code value which will
130 1.1 christos be the numeric error code for what went wrong. Possible error
131 1.1 christos codes are:
132 1.1 christos
133 1.1 christos not found - no such object exists
134 1.1 christos already exists - object already exists, and exclusive flag was
135 1.1 christos set.
136 1.1 christos not unique - more than one object matching the specification
137 1.1 christos exists.
138 1.1 christos permission denied - the authenticator ID specified does not
139 1.1 christos have authorization to access this object,
140 1.1 christos or if the update flag was specified, to
141 1.1 christos update the object.
142 1.1 christos
143 1.1 christos If the response is an update message, the update message will
144 1.1 christos include the object handle and all of the name/value pairs
145 1.1 christos associated with that object.
146 1.1 christos
147 1.1 christos 2: refresh
148 1.1 christos
149 1.1 christos no input values except the handle need be specified. The null
150 1.1 christos handle may not be specified. If the handle is valid, and the
151 1.1 christos authenticator ID specified has permission to examine the object,
152 1.1 christos then an update message will be sent for that object. Otherwise,
153 1.1 christos one of the following errors will be sent:
154 1.1 christos
155 1.1 christos invalid handle - the handle does not refer to a known object
156 1.1 christos permisson denied - the handle refers to an object that the
157 1.1 christos requestor does not have permission to
158 1.1 christos examine.
159 1.1 christos
160 1.1 christos 3: update
161 1.1 christos
162 1.1 christos Requests that the contents of the specified object be updated with
163 1.1 christos the values included. Values that are not specified are not
164 1.1 christos updated. The response will be either an error message or an
165 1.1 christos update-ok message. If rid is nonzero, no response will be
166 1.1 christos generated, even if there was an error. Possible errors include:
167 1.1 christos
168 1.1 christos invalid handle - no such object was found
169 1.1 christos permission denied - the handle refers to an object that the
170 1.1 christos requestor does not have permission to
171 1.1 christos modify.
172 1.1 christos not confirmed - the update could not be committed due to some
173 1.1 christos kind of resource problem, for example
174 1.1 christos insufficient memory or a disk failure.
175 1.1 christos
176 1.1 christos 4: notify
177 1.1 christos
178 1.1 christos Requests that whenever the object with the specified handle is
179 1.1 christos modified, an update be sent. If there is something wrong with the
180 1.1 christos request, an error message will be returned immediately.
181 1.1 christos Otherwise, whenever a change is made to the object, an update
182 1.1 christos message will be sent containing whatever changes were made (or
183 1.1 christos possibly all the values associated with the object, depending on
184 1.1 christos the implementation). Possible errors:
185 1.1 christos
186 1.1 christos invalid handle
187 1.1 christos permission denied - the handle refers to an object that the
188 1.1 christos requestor does not have permission to
189 1.1 christos examine.
190 1.1 christos not supported - the object implementation does not support
191 1.1 christos notifications
192 1.1 christos
193 1.1 christos 5: status
194 1.1 christos
195 1.1 christos Sends a status code in response to a message. Always sent in
196 1.1 christos response to a message sent by the other side. There should never
197 1.1 christos be a response to this message.
198 1.1 christos
199 1.1 christos 6: delete
200 1.1 christos
201 1.1 christos Deletes the specified object. Response will be either request-ok,
202 1.1 christos or error. Possible errors include:
203 1.1 christos
204 1.1 christos invalid handle - no such object was found
205 1.1 christos permission denied - the handle refers to an object that the
206 1.1 christos requestor does not have permission to
207 1.1 christos modify.
208 1.1 christos not confirmed - the deletion could not be committed due to
209 1.1 christos some kind of resource problem, for example
210 1.1 christos insufficient memory or a disk failure.
211 1.1 christos
212 1.1 christos 7: notify-cancel
213 1.1 christos
214 1.1 christos Like notify, but requests that an existing notification be cancelled.
215 1.1 christos
216 1.1 christos 8: notify-cancelled
217 1.1 christos
218 1.1 christos Indicates that because of a local change, a notification that had
219 1.1 christos been registered can no longer be performed. This could be as a
220 1.1 christos result of the permissions on a object changing, or an object being
221 1.1 christos deleted. There should never be a response to this message.
222 1.1 christos
223 1.1 christos internals:
224 1.1 christos
225 1.1 christos Both client and server use same protocol and infrastructure. There
226 1.1 christos are many object types, each of which is stored in a registry.
227 1.1 christos Objects whose type is not recognized can either be handled by the
228 1.1 christos generic object type, which is registered with the type "*". If no
229 1.1 christos generic object type is registered, then objects with unknown types are
230 1.1 christos simply not supported. On the client, there are probably no special
231 1.1 christos object handlers (although this is by no means forbidden). On the
232 1.1 christos server, probably everything is a special object.
233 1.1 christos
234 1.1 christos Each object type has the following methods:
235 1.1 christos
236 1.1 christos
237 1.1 christos
238 1.1 christos
239 1.1 christos dhcpctl_status dhcpctl_connect (dhcpctl_handle *connection,
240 1.1 christos char *server_name, int port,
241 1.1 christos dhcpctl_handle *authinfo)
242 1.1 christos synchronous
243 1.1 christos returns nonzero status code if it didn't connect, zero otherwise
244 1.1 christos stores connection handle through connection, which can be used
245 1.1 christos for subsequent access to the specified server.
246 1.1 christos server_name is the name of the server, and port is the TCP
247 1.1 christos port on which it is listening.
248 1.1 christos authinfo is the handle to an object containing authentication
249 1.1 christos information.
250 1.1 christos
251 1.1 christos dhcpctl_status dhcpctl_open_object (dhcpctl_handle h,
252 1.1 christos dhcpctl_handle connection,
253 1.1 christos int flags)
254 1.1 christos asynchronous - just queues the request
255 1.1 christos returns nonzero status code if open couldn't be queued
256 1.1 christos returns zero if open was queued
257 1.1 christos h is a handle to an object created by dhcpctl_new_object
258 1.1 christos connection is a connection to a DHCP server
259 1.1 christos flags include:
260 1.1 christos DHCPCTL_CREATE - if the object doesn't exist, create it
261 1.1 christos DHCPCTL_UPDATE - update the object on the server using the
262 1.1 christos attached parameters
263 1.1 christos DHCPCTL_EXCL - error if the object exists and DHCPCTL_CREATE
264 1.1 christos was also specified
265 1.1 christos
266 1.1 christos dhcpctl_status dhcpctl_new_object (dhcpctl_handle *h,
267 1.1 christos dhcpctl_handle connection,
268 1.1 christos char *object_type)
269 1.1 christos synchronous - creates a local handle for a host entry.
270 1.1 christos returns nonzero status code if the local host entry couldn't
271 1.1 christos be created
272 1.1 christos stores handle to host through h if successful, and returns zero.
273 1.1 christos object_type is a pointer to a NUL-terminated string containing
274 1.1 christos the ascii name of the type of object being accessed - e.g., "host"
275 1.1 christos
276 1.1 christos dhcpctl_status dhcpctl_set_callback (dhcpctl_handle h, void *data,
277 1.1 christos void (*callback) (dhcpctl_handle,
278 1.1 christos dhcpctl_status, void *))
279 1.1 christos synchronous, with asynchronous aftereffect
280 1.1 christos handle is some object upon which some kind of process has been
281 1.1 christos started - e.g., an open, an update or a refresh.
282 1.1 christos data is an anonymous pointer containing some information that
283 1.1 christos the callback will use to figure out what event completed.
284 1.1 christos return value of 0 means callback was successfully set, a nonzero
285 1.1 christos status code is returned otherwise.
286 1.1 christos Upon completion of whatever task is in process, the callback
287 1.1 christos will be passed the handle to the object, a status code
288 1.1 christos indicating what happened, and the anonymous pointer passed to
289 1.1 christos
290 1.1 christos dhcpctl_status dhcpctl_wait_for_completion (dhcpctl_handle h,
291 1.1 christos dhcpctl_status *s)
292 1.1 christos synchronous
293 1.1 christos returns zero if the callback completes, a nonzero status if
294 1.1 christos there was some problem relating to the wait operation. The
295 1.1 christos status of the queued request will be stored through s, and
296 1.1 christos will also be either zero for success or nonzero for some kind
297 1.1 christos of failure. Never returns until completion or until the
298 1.1 christos connection to the server is lost. This performs the same
299 1.1 christos function as dhcpctl_set_callback and the subsequent callback,
300 1.1 christos for programs that want to do inline execution instead of using
301 1.1 christos callbacks.
302 1.1 christos
303 1.1 christos dhcpctl_status dhcpctl_get_value (data_string *result,
304 1.1 christos dhcpctl_handle h, char *value_name)
305 1.1 christos synchronous
306 1.1 christos returns zero if the call succeeded, a nonzero status code if
307 1.1 christos it didn't.
308 1.1 christos result is the address of an empty data string (initialized
309 1.1 christos with bzero or cleared with data_string_forget). On
310 1.1 christos successful completion, the addressed data string will contain
311 1.1 christos the value that was fetched.
312 1.1 christos dhcpctl_handle refers to some dhcpctl item
313 1.1 christos value_name refers to some value related to that item - e.g.,
314 1.1 christos for a handle associated with a completed host lookup, value
315 1.1 christos could be one of "hardware-address", "dhcp-client-identifier",
316 1.1 christos "known" or "client-hostname".
317 1.1 christos
318 1.1 christos dhcpctl_status dhcpctl_get_boolean (int *result,
319 1.1 christos dhcpctl_handle h, char *value_name)
320 1.1 christos like dhcpctl_get_value, but more convenient for boolean
321 1.1 christos values, since no data_string needs to be dealt with.
322 1.1 christos
323 1.1 christos dhcpctl_status dhcpctl_set_value (dhcpctl_handle h, data_string value,
324 1.1 christos char *value_name)
325 1.1 christos Sets a value on an object referred to by a dhcpctl_handle.
326 1.1 christos The opposite of dhcpctl_get_value. Does not update the
327 1.1 christos server - just sets the value on the handle.
328 1.1 christos
329 1.1 christos dhcpctl_status dhcpctl_set_string_value (dhcpctl_handle h, char *value,
330 1.1 christos char *value_name)
331 1.1 christos Sets a NUL-terminated ASCII value on an object referred to by
332 1.1 christos a dhcpctl_handle. like dhcpctl_set_value, but saves the
333 1.1 christos trouble of creating a data_string for a NUL-terminated string.
334 1.1 christos Does not update the server - just sets the value on the handle.
335 1.1 christos
336 1.1 christos dhcpctl_status dhcpctl_set_boolean (dhcpctl_handle h, int value,
337 1.1 christos char *value_name)
338 1.1 christos Sets a boolean value on an object - like dhcpctl_set_value,
339 1.1 christos only more convenient for booleans.
340 1.1 christos
341 1.1 christos dhcpctl_status dhcpctl_object_update (dhcpctl_handle h)
342 1.1 christos Queues an update on the object referenced by the handle (there
343 1.1 christos can't be any other work in progress on the handle). An
344 1.1 christos update means local parameters will be sent to the server.
345 1.1 christos
346 1.1 christos dhcpctl_status dhcpctl_object_refresh (dhcpctl_handle h)
347 1.1 christos Queues an update on the object referenced by the handle (there
348 1.1 christos can't be any other work in progress on the handle). An
349 1.1 christos update means local parameters will be sent to the server.
350 1.1 christos
351 1.1 christos dhcpctl_status dhcpctl_object_delete (dhcpctl_handle h)
352 1.1 christos Queues a delete of the object referenced by the handle (there
353 1.1 christos can't be any other work in progress on the handle). A
354 1.1 christos delete means that the object will be permanently deleted on
355 1.1 christos the remote end, assuming the remote end supports object
356 1.1 christos persistence.
357 1.1 christos
358 1.1 christos So a sample program that would update a host declaration would look
359 1.1 christos something like this:
360 1.1 christos
361 1.1 christos /* Create a local object into which to store authentication
362 1.1 christos information. */
363 1.1 christos if ((status = dhcpctl_new_object (&auth, dhcpctl_null_handle,
364 1.1 christos "authentication-information")))
365 1.1 christos dhcpctl_error ("Can't create authentication information: %m");
366 1.1 christos
367 1.1 christos /* Set up the authenticator with an algorithm type, user name and
368 1.1 christos password. */
369 1.1 christos if ((status = dhcpctl_set_string_value (&auth, "mellon", "username")))
370 1.1 christos dhcpctl_error ("Can't set username: %m", status);
371 1.1 christos if ((status = dhcpctl_set_string_value (&auth, "three blind mice",
372 1.1 christos "password")))
373 1.1 christos dhcpctl_error ("Can't set password: %m", status);
374 1.1 christos if ((status = dhcpctl_set_string_value (&auth, "md5-hash",
375 1.1 christos "algorithm")))
376 1.1 christos dhcpctl_error ("Can't set authentication algorithm: %m.",
377 1.1 christos status);
378 1.1 christos
379 1.1 christos /* Connect to the server. */
380 1.1 christos if ((status = dhcpctl_connect (&c, "dhcp.server.com", 612, &auth)))
381 1.1 christos
382 1.1 christos dhcpctl_error ("Can't connect to dhcp.server.com: %m",
383 1.1 christos status);
384 1.1 christos
385 1.1 christos /* Create a host object. */
386 1.1 christos if ((status = dhcpctl_new_object (&hp, c, "host")))
387 1.1 christos dhcpctl_error ("Host create failed: %m", status);
388 1.1 christos
389 1.1 christos /* Create a data_string to contain the host's client
390 1.1 christos identifier, and set it. */
391 1.1 christos if ((status =
392 1.1 christos data_string_create_from_hex (&client_id,
393 1.1 christos "1:08:00:2b:34:1a:c3")))
394 1.1 christos dhcpctl_error ("Can't create client identifier: %m");
395 1.1 christos if ((status = dhcpctl_set_value (hp, client_id,
396 1.1 christos "dhcp-client-identifier")))
397 1.1 christos dhcpctl_error ("Host client identifier set failed.");
398 1.1 christos /* Set the known flag to 1. */
399 1.1 christos if ((status = dhcpctl_set_boolean (hp, 1, "known")))
400 1.1 christos dhcpctl_error ("Host known set failed.");
401 1.1 christos
402 1.1 christos /* Open an existing host object that matches the client identifier,
403 1.1 christos and update it from the local context, or if no host entry
404 1.1 christos yet exists matching the identifier, create one and
405 1.1 christos initialize it. */
406 1.1 christos if ((status = dhcpctl_open_object (&hp, c,
407 1.1 christos DHCPCTL_CREATE | DHCPCTL_UPDATE)))
408 1.1 christos dhcpctl_error ("Can't open host: %m", status);
409 1.1 christos
410 1.1 christos /* Wait for the process to complete, check status. */
411 1.1 christos if ((status = dhcpctl_wait_for_completion (hp, &wait_status)))
412 1.1 christos dhcpctl_error ("Host create/lookup wait failed: %m", status);
413 1.1 christos if (waitstatus)
414 1.1 christos dhcpctl_error ("Host create/lookup failed: %m", status);
415 1.1 christos
416 1.1 christos The API is a bit complicated, for a couple of reasons. I want to
417 1.1 christos make it general, so that there aren't a bazillion functions to call,
418 1.1 christos one for each data type. I want it to be thread-safe, which is why
419 1.1 christos each function returns a status and the error printer requires a status
420 1.1 christos code for input. I want it to be possible to make it asynchronous, so
421 1.1 christos that it can work in tandem with, for example, an X toolkit. If
422 1.1 christos you're just writing a simple update cgi program, you probably won't
423 1.1 christos want to bother to use the asynchronous callbacks, and indeed the above
424 1.1 christos example doesn't.
425 1.1 christos
426 1.1 christos I glossed over data strings above - basically, they're objects with a
427 1.1 christos pointer to a reference-counted buffer structure, an offset into that
428 1.1 christos buffer, and a length. These are used within the DHCP server, so you
429 1.1 christos can get an idea of how they work - basically, they're a convenient and
430 1.1 christos efficient way to store a string with a length such that substrings can
431 1.1 christos easily be taken and such that more than one user at a time can have a
432 1.1 christos pointer to the string.
433 1.1 christos
434 1.1 christos I will also probably add locking primitives, so that you can get the
435 1.1 christos value of something and be sure that some other updator process won't
436 1.1 christos modify it while you have the lock.
437