mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-31 06:25:31 +00:00
Code Issues Releases Wiki Activity

Ted Lemon's OMAPI design doc from the DHCP tree

Browse Source
This commit is contained in:
David Lawrence
1999-10-31 23:32:43 +00:00
parent 90d3a7800b
commit 4cd4e5a7e2
1 changed files with 436 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

436
doc/design/omapi Normal file
View File

@@ -0,0 +1,436 @@
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
result of the permissions on a object changing, or an object being
deleted. There should never be a response to this message.
internals:
Both client and server use same protocol and infrastructure. There
are many object types, each of which is stored in a registry.
Objects whose type is not recognized can either be handled by the
generic object type, which is registered with the type "*". If no
generic object type is registered, then objects with unknown types are
simply not supported. On the client, there are probably no special
object handlers (although this is by no means forbidden). On the
server, probably everything is a special object.
Each object type has the following methods:
dhcpctl_status dhcpctl_connect (dhcpctl_handle *connection,
char *server_name, int port,
dhcpctl_handle *authinfo)
synchronous
returns nonzero status code if it didn't connect, zero otherwise
stores connection handle through connection, which can be used
for subsequent access to the specified server.
server_name is the name of the server, and port is the TCP
port on which it is listening.
authinfo is the handle to an object containing authentication
information.
dhcpctl_status dhcpctl_open_object (dhcpctl_handle h,
dhcpctl_handle connection,
int flags)
asynchronous - just queues the request
returns nonzero status code if open couldn't be queued
returns zero if open was queued
h is a handle to an object created by dhcpctl_new_object
connection is a connection to a DHCP server
flags include:
DHCPCTL_CREATE - if the object doesn't exist, create it
DHCPCTL_UPDATE - update the object on the server using the
attached parameters
DHCPCTL_EXCL - error if the object exists and DHCPCTL_CREATE
was also specified
dhcpctl_status dhcpctl_new_object (dhcpctl_handle *h,
dhcpctl_handle connection,
char *object_type)
synchronous - creates a local handle for a host entry.
returns nonzero status code if the local host entry couldn't
be created
stores handle to host through h if successful, and returns zero.
object_type is a pointer to a NUL-terminated string containing
the ascii name of the type of object being accessed - e.g., "host"
dhcpctl_status dhcpctl_set_callback (dhcpctl_handle h, void *data,
void (*callback) (dhcpctl_handle,
dhcpctl_status, void *))
synchronous, with asynchronous aftereffect
handle is some object upon which some kind of process has been
started - e.g., an open, an update or a refresh.
data is an anonymous pointer containing some information that
the callback will use to figure out what event completed.
return value of 0 means callback was successfully set, a nonzero
status code is returned otherwise.
Upon completion of whatever task is in process, the callback
will be passed the handle to the object, a status code
indicating what happened, and the anonymous pointer passed to
dhcpctl_status dhcpctl_wait_for_completion (dhcpctl_handle h,
dhcpctl_status *s)
synchronous
returns zero if the callback completes, a nonzero status if
there was some problem relating to the wait operation. The
status of the queued request will be stored through s, and
will also be either zero for success or nonzero for some kind
of failure. Never returns until completion or until the
connection to the server is lost. This performs the same
function as dhcpctl_set_callback and the subsequent callback,
for programs that want to do inline execution instead of using
callbacks.
dhcpctl_status dhcpctl_get_value (data_string *result,
dhcpctl_handle h, char *value_name)
synchronous
returns zero if the call succeeded, a nonzero status code if
it didn't.
result is the address of an empty data string (initialized
with bzero or cleared with data_string_forget). On
successful completion, the addressed data string will contain
the value that was fetched.
dhcpctl_handle refers to some dhcpctl item
value_name refers to some value related to that item - e.g.,
for a handle associated with a completed host lookup, value
could be one of "hardware-address", "dhcp-client-identifier",
"known" or "client-hostname".
dhcpctl_status dhcpctl_get_boolean (int *result,
dhcpctl_handle h, char *value_name)
like dhcpctl_get_value, but more convenient for boolean
values, since no data_string needs to be dealt with.
dhcpctl_status dhcpctl_set_value (dhcpctl_handle h, data_string value,
char *value_name)
Sets a value on an object referred to by a dhcpctl_handle.
The opposite of dhcpctl_get_value. Does not update the
server - just sets the value on the handle.
dhcpctl_status dhcpctl_set_string_value (dhcpctl_handle h, char *value,
char *value_name)
Sets a NUL-terminated ASCII value on an object referred to by
a dhcpctl_handle. like dhcpctl_set_value, but saves the
trouble of creating a data_string for a NUL-terminated string.
Does not update the server - just sets the value on the handle.
dhcpctl_status dhcpctl_set_boolean (dhcpctl_handle h, int value,
char *value_name)
Sets a boolean value on an object - like dhcpctl_set_value,
only more convenient for booleans.
dhcpctl_status dhcpctl_object_update (dhcpctl_handle h)
Queues an update on the object referenced by the handle (there
can't be any other work in progress on the handle). An
update means local parameters will be sent to the server.
dhcpctl_status dhcpctl_object_refresh (dhcpctl_handle h)
Queues an update on the object referenced by the handle (there
can't be any other work in progress on the handle). An
update means local parameters will be sent to the server.
dhcpctl_status dhcpctl_object_delete (dhcpctl_handle h)
Queues a delete of the object referenced by the handle (there
can't be any other work in progress on the handle). A
delete means that the object will be permanently deleted on
the remote end, assuming the remote end supports object
persistence.
So a sample program that would update a host declaration would look
something like this:
/* Create a local object into which to store authentication
information. */
if ((status = dhcpctl_new_object (&auth, dhcpctl_null_handle,
"authentication-information")))
dhcpctl_error ("Can't create authentication information: %m");
/* Set up the authenticator with an algorithm type, user name and
password. */
if ((status = dhcpctl_set_string_value (&auth, "mellon", "username")))
dhcpctl_error ("Can't set username: %m", status);
if ((status = dhcpctl_set_string_value (&auth, "three blind mice",
"password")))
dhcpctl_error ("Can't set password: %m", status);
if ((status = dhcpctl_set_string_value (&auth, "md5-hash",
"algorithm")))
dhcpctl_error ("Can't set authentication algorithm: %m.",
status);
/* Connect to the server. */
if ((status = dhcpctl_connect (&c, "dhcp.server.com", 612, &auth)))
dhcpctl_error ("Can't connect to dhcp.server.com: %m",
status);
/* Create a host object. */
if ((status = dhcpctl_new_object (&hp, c, "host")))
dhcpctl_error ("Host create failed: %m", status);
/* Create a data_string to contain the host's client
identifier, and set it. */
if ((status =
data_string_create_from_hex (&client_id,
"1:08:00:2b:34:1a:c3")))
dhcpctl_error ("Can't create client identifier: %m");
if ((status = dhcpctl_set_value (hp, client_id,
"dhcp-client-identifier")))
dhcpctl_error ("Host client identifier set failed.");
/* Set the known flag to 1. */
if ((status = dhcpctl_set_boolean (hp, 1, "known")))
dhcpctl_error ("Host known set failed.");
/* Open an existing host object that matches the client identifier,
and update it from the local context, or if no host entry
yet exists matching the identifier, create one and
initialize it. */
if ((status = dhcpctl_open_object (&hp, c,
DHCPCTL_CREATE | DHCPCTL_UPDATE)))
dhcpctl_error ("Can't open host: %m", status);
/* Wait for the process to complete, check status. */
if ((status = dhcpctl_wait_for_completion (hp, &wait_status)))
dhcpctl_error ("Host create/lookup wait failed: %m", status);
if (waitstatus)
dhcpctl_error ("Host create/lookup failed: %m", status);
The API is a bit complicated, for a couple of reasons. I want to
make it general, so that there aren't a bazillion functions to call,
one for each data type. I want it to be thread-safe, which is why
each function returns a status and the error printer requires a status
code for input. I want it to be possible to make it asynchronous, so
that it can work in tandem with, for example, an X toolkit. If
you're just writing a simple update cgi program, you probably won't
want to bother to use the asynchronous callbacks, and indeed the above
example doesn't.
I glossed over data strings above - basically, they're objects with a
pointer to a reference-counted buffer structure, an offset into that
buffer, and a length. These are used within the DHCP server, so you
can get an idea of how they work - basically, they're a convenient and
efficient way to store a string with a length such that substrings can
easily be taken and such that more than one user at a time can have a
pointer to the string.
I will also probably add locking primitives, so that you can get the
value of something and be sure that some other updator process won't
modify it while you have the lock.