workbench/network/stacks/AROSTCP/dhcp/doc/api+protocol

   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.