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