ISC DHCP: OMAPI wire protocol

OMAPI: Object Management Application Programming Interface

This post briefly describes the OMAPI protocol for the Internet Systems Consortium DHCP server version 4.1-ESV-R11.

From the dhcpd man page:

The DHCP server provides the capability to modify some of its configuration while it is running, without stopping it, modifying its database files, and restarting it. This capability is currently provided using OMAPI - an API for manipulating remote objects. OMAPI clients connect to the server using TCP/IP, authenticate, and can then examine the server’s current status and make changes to it.

This post is not a tutorial. Prior experience of binary protocols is assumed.

OMAPI capabilities and limitations 🔗

OMAPI is not a complete configuration API. The following can be examined/modified via OMAPI: lease, host, failover-state and group.

In a failover system do NOT assume that changes are replicated between peers.

Note: the ISC Kea DHCP Server promises more comprehensive control using JSON messages over UNIX sockets and the capability to store state in relational databases (MySQL; PostgreSQL.)

OMAPI protocol 🔗

The OMAPI protocol from a client perspective:

RECV: Startup
SEND: Startup
SEND: Payload (unsigned authenticator payload)
RECV: Payload (unsigned authenticator payload)
SEND: Payload (signed request)
RECV: Payload (signed response)
              (repeat last two steps as applicable)

OMAPI data structures 🔗

Startup {
  u32            version = 0x64
  u32            hlength = 56
}

Payload {
  u32            authid
  u32            authlen
  u32            op
  u32            handle
  u32            id
  u32            rid
  NamedValue[]   msg_values
  u16            end_msg_values = 0
  NamedValue[]   obj_values
  u16            end_obj_values = 0
  u8[]           signature
}

NamedValue {
  u16            namelen
  u8[namelen]    name
  u32            valuelen
  u8[valuelen]   value
}

When valuelen=0xFFFF then value has a length of 0. This is a delete property command.

The encoding of text values is not clearly defined. It seems prudent to restrict them to visible ASCII values. Values can be of various types (e.g. 4-byte integer.)

These structures differ from the api+protocol document regarding the position of the authlen field. See OMAPI Documentation for further details on the purpose of the fields.

OMAPI security 🔗

OMAPI messages are not encrypted but are signed with a secret key.

The signature is a HMAC-MD5 hash of the following fields of the Payload structure:

  authlen
  op
  handle
  id
  rid
  msg_values
  end_msg_values
  obj_values
  end_obj_values

OMAPI Documentation 🔗

The dhcpd man page details the types of objects and properties that can be inspected/modified via OMAPI.

The doc/api+protocol document in the source bundle describes further details about the protocol. The source license:

# Copyright (c) 2004-2015 by Internet Systems Consortium, Inc. ("ISC")
# Copyright (c) 1995-2003 by Internet Software Consortium
#
# Permission to use, copy, modify, and distribute this software for any
# purpose with or without fee is hereby granted, provided that the above
# copyright notice and this permission notice appear in all copies.
#
# THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
# OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
#
#   Internet Systems Consortium, Inc.
#   950 Charter Street
#   Redwood City, CA 94063
#   
#   https://www.isc.org/

See the specific source files for any additional copyright or
license statements.

omshell (OMAPI Command Shell) in conjunction with an inspection tool like Wireshark is recommended for debugging.