Annotation of embedaddon/dhcp/doc/api+protocol, revision 1.1
1.1 ! misho 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to api+protocol CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / doc