api+protocol

DHCP服务器源码

This file documents the protocol that the ISC DHCP server and ISC
Object Management clients (clients that use the ISC Object Management
API) speak between one another.

Protocol:

All multi-byte numbers are represented in network byte order.

On startup, each side sends a status message indicating what version
of the protocol they are speaking.   The status message looks like
this:

+---------+---------+
| version | hlength |
+---------+---------+

version - a 32-bit fixed-point number with the decimal point between
	  the third and second decimal digits from the left,
	  representing the version of the protocol.   The current
	  protocol version is 1.00.   If the field were considered as
	  a 32-bit integer, this would correspond to a value of 100
	  decimal, or 0x64.

hlength - a 32-bit integer representing the length of the fixed-length
	  header in subsequent messages.   This is normally 56, but
	  can be changed to a value larger than 56 by either side
	  without upgrading the revision number.


The startup message is not authenticated.   Either side may reject the
other side's startup message as invalid by simply closing the
connection.   The only fixed part of the startup message is the
version number - future versions may delete hlength, or add further
startup information.

Following the startup message, all messages have the same format.
Currently, the format includes a fixed-length header (the length in
hlength, above)

+--------+----+--------+----+-----+---------+------------+------------+-----+
| authid | op | handle | id | rid | authlen | msg values | obj values | sig |
+--------+----+--------+----+-----+---------+------------+------------+-----+

The fixed-length header consists of:

authid = a 32-bit authenticator handle.
	For an original message (one not in response to some other
	message), this will be chosen by the originator.   For a
	message in response to another message, the authenticator for
	that message is used, except if the response is an error
	message indicating that the authenticator used was unknown,
	in which case the null authenticator is used.   Messages that
	are generated as the result of a notify registration use the
	authenticator used in the original notify registration.
	The authenticator itself is generated by having one side of
	the connection send an object of type "authenticator" to the
	other side with values that indicate what kind of
	authentication mechanism to use and what key to use.   The two
	most likely things here are a Kerberos V principal name or the
	name of a shared secret that can be used to calculate an MD5
	hash.   The mechanism for doing this has yet to be finalized.
	If authid is zero, the message is not authenticated.

op = 32-bit opcode, one of:
	open = 1
	refresh = 2
	update = 3
	notify = 4
	error = 5
	delete = 6
handle = 32-bit object handle
	A handle on the object being opened, created, refreshed or
	updated.   If no handle is yet available (e.g., with open and
	new), then the value zero is sent.
id = 32-bit transaction id of the message - a monotonically increasing
     number that starts with some randomly chosen number at the
     beginning of the life of the connection.   The value should never
     be zero.
rid = 32-bit transaction ID of the message to which this message is a
      response, or zero if this message is not in response to a
      message from the other side.

authlen = a 32-bit number representing the length of the authenticator

msg values = a series of name+value pairs, specific to this message.
	 Each name+value pair starts with a 16-bit name length,
	 followed by that many bytes of name, followed by a 32-bit
	 value length, followed by that many bytes of value.   If the
	 length is zero, this is a value of the blank string.   If the
	 length is all ones (2^32-1), then there is no value - for an
	 update, this means the value for this name and the name
	 itself should be deleted from the object, which may or may
	 not be possible.   The list of name/value pairs ends with a
	 zero-length name, which is not followed by a value
	 length/value pair.

obj values = a series of name+value pairs, as above, specific to the
	object being created, updated or refreshed.

signature = authlen bytes of data signing the message.   The signature
	    algorithm is a property of the authenticator handle.

Message types:

1: open
   relevant input values:
	object-type = the name of the type of object
	open:create = boolean - create the object if it doesn't yet exist
	open:exclusive = boolean - don't open the object if it does exist
	open:update = boolean - update the object with included values
		      if it matches.
	the handle should always be the null handle

   The input value must also contain key information for the type of
   object being searched that uniquely identifies an object, or search
   information that matches only one object.  Each object has a key
   specification (a key is something that uniquely identifies an
   object), so see the key specification for that object to see
   what to send here.   An open message with the create flag set must
   specify a key, and not merely matching criteria.   Some objects may
   allow more than one key, and it may be that the union of those keys
   is required to uniquely identify the object, or it may be that any
   one such key will uniquely identify the object.   The documentation
   for the type of object will specify this.

   An open message will result in an immediate response message whose
   opcode will either be "error" or "update".   The error message may
   include an error:reason value containing a text string explaining
   the error, and will always include an error:code value which will
   be the numeric error code for what went wrong.   Possible error
   codes are:

	not found - no such object exists
	already exists - object already exists, and exclusive flag was
			 set.
	not unique - more than one object matching the specification
		     exists.
	permission denied - the authenticator ID specified does not
			    have authorization to access this object,
			    or if the update flag was specified, to
			    update the object.

   If the response is an update message, the update message will
   include the object handle and all of the name/value pairs
   associated with that object.

2: refresh

   no input values except the handle need be specified.   The null
   handle may not be specified.   If the handle is valid, and the
   authenticator ID specified has permission to examine the object,
   then an update message will be sent for that object.   Otherwise,
   one of the following errors will be sent:

	invalid handle - the handle does not refer to a known object
	permisson denied - the handle refers to an object that the
			   requestor does not have permission to
			   examine. 

3: update

   Requests that the contents of the specified object be updated with
   the values included.   Values that are not specified are not
   updated.   The response will be either an error message or an
   update-ok message.   If rid is nonzero, no response will be
   generated, even if there was an error.   Possible errors include:

	invalid handle - no such object was found
	permission denied - the handle refers to an object that the
			    requestor does not have permission to
			    modify.
	not confirmed - the update could not be committed due to some
			kind of resource problem, for example
			insufficient memory or a disk failure.

4: notify

   Requests that whenever the object with the specified handle is
   modified, an update be sent.   If there is something wrong with the
   request, an error message will be returned immediately.
   Otherwise, whenever a change is made to the object, an update
   message will be sent containing whatever changes were made (or
   possibly all the values associated with the object, depending on
   the implementation).   Possible errors:

	invalid handle
	permission denied - the handle refers to an object that the
			    requestor does not have permission to
			    examine.
	not supported - the object implementation does not support
			notifications

5: status

   Sends a status code in response to a message.  Always sent in
   response to a message sent by the other side.  There should never
   be a response to this message.

6: delete

   Deletes the specified object.   Response will be either request-ok,
   or error.   Possible errors include:

	invalid handle - no such object was found
	permission denied - the handle refers to an object that the
			    requestor does not have permission to
			    modify.
	not confirmed - the deletion could not be committed due to
			some kind of resource problem, for example
			insufficient memory or a disk failure.

7: notify-cancel

   Like notify, but requests that an existing notification be cancelled.

8: notify-cancelled

   Indicates that because of a local change, a notification that had
   been registered can no longer be performed.   This could be as a