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