DHCP Server API

The DHCP Server allows administrators and third parties to develop modules to be linked to the DHCP Server and be called at specific checkpoints throughout the processing of a DHCP or BOOTP message.

This API specifies the routines, their prototypes, and the desired function of each symbol to be exported by the user-defined module. Additionally, this document mentions the structures used by the DHCP server and any User-Defined Object and the symbols exported by the DHCP server as utilities to the API Programmer.

General

It is noted that security and performance degredation may be introduced by any User-Defined Object.

Because the DHCP server is run with root user authority, special care should be taken to ensure no security vulnerabilities are introduced by the User-Defined Object. This includes taking steps to protect against buffer overrun exploitations, and every possible security measure when writing to temporary files on the disk or executing system commands.

Also, as many of the routines that can be defined by the User Object are executed during the normal processing path of each DHCP client's message, care should be taken to not slow the possible response to the DHCP client.

Configuration

A User-Defined Object can be referenced and loaded by the DHCP server if specified in the configuration file with the "UserObject" configuration line or stanza. For example:

  UserObject myobject

or

  UserObject myobject
  {
         file /tmp/myobject.log;
  }

In both cases, the dynamically loadable shared object "myobject.dhcpo" will be loaded from the /usr/sbin directory. In the second case, the object's Initialize() routine will be passed a file pointer as it is the responsibility of the object to parse and handle its own configuration stanza.

Structures

dhcpmsg

  struct dhcpmsg
  {
         uint8_t        op;
         uint8_t        htype;
         uint8_t        hlen;
         uint8_t        hops;
         uint32_t       xid;
         uint16_t       secs;
         uint16_t       flags;
         uint32_t       ciaddr;
         uint32_t       yiaddr;
         uint32_t       siaddr;
         uint32_t       giaddr;
         uint8_t        chaddr[16];
         uint8_t        sname[64];
         uint8_t        file[128];
         uint8_t        options[1];
  };

dhcpmsg defines the structure and fields of the basic DHCP message. The options field is variable in length and every routine referencing a DHCP message will also specify the total length of the message.

dhcpoption

  struct dhcpoption
  {
         uint8_t        code;
         uint8_t        len;
         uint8_t        data[1];
  };

dhcpoption defines the framework of a DHCP option encoded in its type, length, data format.

dhcpclientid

struct dhcpclientid
  {
          uint8_t         type;
          uint8_t         len;
          uint8_t         id[64];
  };

dhcpclientid uniquely identifies a DHCP client. It either defines the DHCP Client Identifier Option or it is created from the hardware type, hardware length, and harware address of a DHCP or BOOTP message that does not contain a Client Identifier Option. Both the DHCP message option and client identifier references will always point to network byte-ordered data.

dhcplogseverity

enum dhcplogseverity
  {
          dhcplog_syserr = 1 ,
          dhcplog_objerr ,
          dhcplog_protocol ,
          dhcplog_warning ,
          dhcplog_event ,
          dhcplog_action ,
          dhcplog_info ,
          dhcplog_accounting ,
          dhcplog_stats ,
          dhcplog_trace
  };

The enumerated type dhcplogseverity is used to indicate to the DHCP server what log severity should be used when displaying a User-Defined Object's error message to the DHCP server's log file through the exported routine dhcpapi_logmessage(). The severity must be enabled for logging for the message to be displayed.

Routines

A few requirements exist to conform to this API. The User-Defined Object MUST:

1. provide the initialization routine, Initialize().
2. provide the shutdown routine, Shutdown().
3. provide at least one of the checkpoint functions defined in the API.
4. NEVER alter any data given through reference to the routine when the reference is a "const" pointer.

Required Routines

Initialize

int Initialize       ( FILE *fp,
                       caddr_t *hObjectInstance               ) ;

Shutdown

void Shutdown        ( caddr_t hObjectInstance                ) ;

Checkpoint Routines

Only one of the following routines must be implemented by the Extension Object.

messageReceived

int messageReceived  ( caddr_t hObjectInstance,
                       struct dhcpmessage **inMessage,
                       size_t *messageSize,
                       const struct in_addr *receivingIP,
                       const struct in_addr *destinationIP,
                       const struct in_addr *sourceIP         ) ;

addressOffered

void addressOffered  ( caddr_t hObjectInstance,
                       const struct dhcpclientid *cid,
                       const struct in_addr *addr,
                       const struct dhcpmessage *outMessage,
                       size_t messageSize                     ) ;

addressAssigned

void addressAssigned ( caddr_t hObjectInstance,
                       const struct dhcpclientid *cid,
                       const struct in_addr *addr,
                       const char *hostname,
                       const char *domain,
                       const struct dhcpmessage *outMessage,
                       size_t messageSize                     ) ;

address Released

void addressReleased ( caddr_t hObjectInstance,
                       const struct dhcpclientid *cid,
                       const struct in_addr *addr,
                       const char *hostname,
                       const char *domain                     ) ;

addressExpired

void addressExpired  ( caddr_t hObjectInstance,
                       const struct dhcpclientid *cid,
                       const struct in_addr *addr,
                       const char *hostname,
                       const char *domain                     ) ;

addressDeleted

void addressDeleted  ( caddr_t hObjectInstance,
                       const struct dhcpclientid *cid,
                       const struct in_addr *addr,
                       const char *hostname,
                       const char *domain                     ) ;

addressDeclined

void addressDeclined ( caddr_t hObjectInstance,
                       const struct dhcpclientid *cid,
                       const struct in_addr *addr,
                       const char *hostname,
                       const char *domain                     ) ;

Exported Routines

dhcpapi_logmessage

void dhcpapi_logmessage ( enum dhcplogseverity s,
                          char *format,
                          ...                                              ) ;