// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC") // // This Source Code Form is subject to the terms of the Mozilla Public // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. /** @page libdhcp libkea-dhcp++ - Low Level DHCP Library @section libdhcpIntro Libdhcp++ Library Introduction libdhcp++ is an all-purpose DHCP-manipulation library, written in C++. It offers packet parsing and assembly, DHCPv4 and DHCPv6 options parsing and assembly, interface detection (currently on Linux, FreeBSD, NetBSD, OpenBSD, Max OS X, and Solaris 11) and socket operations. It is a generic purpose library that can be used by server, client, relay, performance tools and other DHCP-related tools. For server specific library, see \ref libdhcpsrv. Please do not add any server-specific code to libdhcp++ and use \ref libdhcpsrv instead. The following classes for packet manipulation are implemented: - isc::dhcp::Pkt4 - represents a DHCPv4 packet. - isc::dhcp::Pkt6 - represents a DHCPv6 packet. - isc::dhcp::Pkt4o6 - represents a DHCPv4-over-DHCPv6 packet. The following pointer types are defined: \c Pkt4Ptr, \c Pkt6Ptr and Pkt4o6Ptr. They are smart pointers using the \c boost::shared_ptr type. There are no const versions of packet types defined, as we assume that hooks can modify any aspect of the packet at almost any stage of processing. Both packet types use a collection of \ref isc::dhcp::Option objects to represent DHCPv4 and DHCPv6 options. The base class @c Option can be used to represent generic option that contains collection of bytes. Depending on whether the option is instantiated as a DHCPv4 or DHCPv6 option, it will adjust its header (DHCPv4 options use 1 octet for type and 1 octet for length, while DHCPv6 options use 2 bytes for each). There are many specialized classes that are intended to handle options having specific formats: - isc::dhcp::Option4AddrLst -- DHCPv4 option, contains one or more IPv4 addresses; - isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses; - isc::dhcp::Option4ClientFqdn -- DHCPv4 Client FQDN option; - isc::dhcp::Option6ClientFqdn -- DHCPv6 Client FQDN option; - isc::dhcp::Option6IAAddr -- DHCPv6 option, represents an IAADDR option (an option that contains IPv6 address with extra parameters); - isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents an IAPREFIX option (an option that contains IPv6 prefix in prefix delegation); - isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions. - isc::dhcp::Option6StatusCode -- DHCPv6 option, carries a status code to the client; - isc::dhcp::OptionCustom -- Represents an option having many different formats, where data fields can be accessed in a convenient way; - isc::dhcp::OptionInt -- DHCPv4 or DHCPv6 option, carries a single numeric value; - isc::dhcp::OptionString -- DHCPv4 or DHCPv6 option, carries a text value; - isc::dhcp::OptionVendor -- DHCPv4 or DHCPv6 option, carries Vendor Specific Information; - isc::dhcp::OptionVendorClass -- DHCPv4 or DHCPv6 option, contains vendor class information. Various options can store sub-options (i.e. options that are stored within an option rather than in a message directly). This functionality is commonly used in DHCPv6, but is rarely used in DHCPv4. \ref isc::dhcp::Option::addOption(), \ref isc::dhcp::Option::delOption(), \ref isc::dhcp::Option::getOption() can be used to add, remove and retrieve sub-options from within an option. @section libdhcpDhcp4o6 DHCPv4-over-DHCPv6 support The DHCPv4-over-DHCPv6 packet class (\c Pkt4o6) is derived from the DHCPv4 packet class (\c Pkt4) with: - un extra member pointing to the encapsulating DHCPv6 packet, accessible by \ref isc::dhcp::Pkt4o6::getPkt6() - a specialized isc::dhcp::Pkt::pack() method which builds the wire-format data of the whole DHCPv6-over-DHCPv4 packet. To avoid the extra overhead of dynamic casts the isc::dhcp::Pkt4::isDhcp4o6() virtual method returns true for \c Pkt4o6 instances and false for others. @section libdhcpRelay Relay v6 support in Pkt6 DHCPv6 clients that are not connected to the same link as DHCPv6 servers need relays to reach the server. Each relay receives a message on a client facing interface, encapsulates it into RELAY_MSG option and sends as RELAY_FORW message towards the server (or the next relay, which is closer to the server). This procedure can be repeated up to 32 times. Kea is able to support up to 32 relays. Each traversed relay may add certain options. The most obvious example is interface-id option, but there may be other options as well. Each relay may add such an option, regardless of whether other relays added it before. Thanks to encapsulation, those options are separated and it is possible to differentiate which relay inserted specific instance of an option. Interface-id is used to identify a subnet (or interface) the original message came from and is used for that purpose on two occasions. First, the server uses the interface-id included by the first relay (the one closest to the client) to select appropriate subnet for a given request. Server includes that interface-id in its copy, when sending data back to the client. This will be used by the relay to choose proper interface when forwarding response towards the client. The Pkt6 class has a public \c Pkt6::relay_info_ field, which is of type \c Pkt6::RelayInfo. This is a simple structure that represents the information in each RELAY_FORW or RELAY_REPL message. It is important to understand the order in which the data appear here. Consider the following network: \verbatim client-------relay1-----relay2-----relay3----server \endverbatim Client will transmit SOLICIT message. Relay1 will forward it as RELAY_FORW with SOLICIT in it. Relay2 forward it as RELAY_FORW with RELAY_FORW with SOLICIT in it. Finally the third relay will add yet another RELAY_FORW around it. The server will parse the packet and create \c Pkt6 object for it. Its relay_info_ will have 3 elements. Packet parsing is done in reverse order, compare to the order the packet traversed in the network. The first element (relay_info_[0]) will represent relay3 information (the "last" relay or in other words the one closest to the server). The second element will represent relay2. The third element (relay_info_[2]) will represent the first relay (relay1) or in other words the one closest to the client. Packets sent by the server must maintain the same encapsulation order. This is easy to do - just copy data from client's message object into server's response object. See @ref isc::dhcp::Pkt6::RelayInfo for details. @section libdhcpIfaceMgr Interface Manager Interface Manager (or IfaceMgr) is an abstraction layer for low-level network operations. In particular, it provides information about existing network interfaces See @ref isc::dhcp::Iface class and @ref isc::dhcp::IfaceMgr::detectIfaces() and @ref isc::dhcp::IfaceMgr::getIface(). Generic parts of the code are contained in the @ref isc::dhcp::IfaceMgr class in src/lib/dhcp/iface_mgr.cc file. OS-specific code is located in separate files, e.g. iface_mgr_linux.cc, iface_mgr_bsd. The separation should be maintained when developing additional code. Other useful methods are dedicated to transmission (\ref isc::dhcp::IfaceMgr::send(), 2 overloads) and reception (\ref isc::dhcp::IfaceMgr::receive4() and \ref isc::dhcp::IfaceMgr::receive6()). Note that \c receive4() and \c receive6() methods may return NULL, e.g. when timeout is reached or if the DHCP daemon receives a signal. @section libdhcpPktFilter Switchable Packet Filter objects used by Interface Manager The well known problem of DHCPv4 implementation is that it must be able to provision devices which don't have an IPv4 address yet (the IPv4 address is one of the configuration parameters provided by DHCP server to a client). One way to communicate with such a device is to send server's response to a broadcast address. An obvious drawback of this approach is that the server's response will be received and processed by all clients in the particular network. Therefore, the preferred approach is that the server unicasts its response to a new address being assigned for the client. This client will identify itself as a target of this message by checking chaddr and/or Client Identifier value. At the same time, the other clients in the network will not receive the unicast message. The major problem that arises with this approach is that the client without an IP address doesn't respond to ARP messages. As a result, server's response will not be sent over IP/UDP socket because the system kernel will fail to resolve client's link-layer address. Kea supports the use of raw sockets to create a complete Data-link/IP/UDP/DHCPv4 stack. By creating each layer of the outgoing packet, the Kea logic has full control over the frame contents and it may bypass the use of ARP to inject the link layer address into the frame. The low level operations on raw sockets are implemented within the "packet filtering" classes derived from @c isc::dhcp::PktFilter. The implementation of these classes is specific to the operating system. On Linux the @c isc::dhcp::PktFilterLPF is used. On BSD systems the @c isc::dhcp::PktFilterBPF is used. The raw sockets are bound to a specific interface, not to the IP address/UDP port. Therefore, the system kernel doesn't have means to verify that Kea is listening to the DHCP traffic on the specific address and port. This has two major implications: - It is possible to run another DHCPv4 sever instance which will bind socket to the same address and port. - An attempt to send a unicast message to the DHCPv4 server will result in ICMP "Port Unreachable" message being sent by the kernel (which is unaware that the DHCPv4 service is actually running). In order to overcome these issues, the packet filtering classes open a regular IP/UDP socket which coexists with the raw socket. The socket is referred to as "fallback socket" in the Kea code. All packets received through this socket are discarded. @section libdhcpPktFilter6 Switchable Packet Filters for DHCPv6 The DHCPv6 implementation doesn't suffer from the problems described in \ref libdhcpPktFilter. Therefore, the socket creation and methods used to send and receive DHCPv6 messages are common for all OSes. However, there is still a need to customize the operations on the sockets to reliably unit test the \ref isc::dhcp::IfaceMgr logic. The \ref isc::dhcp::IfaceMgr::openSockets6 function examines configuration of detected interfaces for their availability to listen DHCPv6 traffic. For all running interfaces (except local loopback) it will try to open a socket and bind it to the link-local or global unicast address. The socket will not be opened on the interface which is down or for which it was explicitly specified that it should not be used to listen to DHCPv6 messages. There is a substantial amount of logic in this function that has to be unit tested for various interface configurations, e.g.: - multiple interfaces with link-local addresses only - multiple interfaces, some of them having global unicast addresses, - multiple interfaces, some of them disabled - no interfaces The \ref isc::dhcp::IfaceMgr::openSockets6 function attempts to open sockets on detected interfaces. At the same time, the number of interfaces, and their configuration is specific to OS where the tests are being run. So the test doesn't have any means to configure interfaces for the test case being run. Moreover, a unit test should not change the configuration of the system. For example, a change to the configuration of the interface which is used to access the machine running a test, may effectively break the access to this machine. In order to overcome the problem described above, the unit tests use fake interfaces which can be freely added, configured and removed from the \ref isc::dhcp::IfaceMgr. Obviously, it is not possible to open a socket on a fake interface, nor use it to send or receive IP packets. To mimic socket operations on fake interfaces it is required that the functions which open sockets, send messages and receive messages have to be customizable. This is achieved by implementation of replaceable packet filter objects which derive from the \ref isc::dhcp::PktFilter6 class. The default implementation of this class is \ref isc::dhcp::PktFilterInet6 which creates a regular datagram IPv6/UDPv6 socket. The unit tests use a stub implementation isc::dhcp::test::PktFilter6Stub which contains no-op functions. Use \ref isc::dhcp::IfaceMgr::setPacketFilter function to set the custom packet filter object to be used by Interface Manager. @section libdhcpErrorLogging Logging non-fatal errors in IfaceMgr The libdhcp++ is a common library, meant to be used by various components, such as DHCP servers, relays and clients. It is also used by a perfdhcp benchmarking application. It provides a basic capabilities for these applications to perform operations on DHCP messages such as encoding or decoding them. It also provides capabilities to perform low level operations on sockets. Since libdhcp++ is a common library, its dependency on other BINDX modules should be minimal. In particular, errors occurring in the libdhcp++ are reported using exceptions, not a BINDX logger. This works well in most cases, but there are some cases in which it is undesired for a function to throw an exception in case of non-fatal error. The typical case, when exception should not be thrown, is when the \ref isc::dhcp::IfaceMgr::openSockets4 or \ref isc::dhcp::IfaceMgr::openSockets6 fails to open a socket on one of the interfaces. This should not preclude the function from attempting to open sockets on other interfaces, which would be the case if exception was thrown. In such cases the IfaceMgr makes use of error handler callback function which may be installed by a caller. This function must implement the isc::dhcp::IfaceMgrErrorMsgCallback. Note that it is allowed to pass a NULL value instead, which would result falling back to a default behavior and exception will be thrown. If non-NULL value is provided, the \ref isc::dhcp::IfaceMgr will call error handler function and pass an error string as an argument. The handler function may use its logging mechanism to log this error message. In particular, the DHCP server will use BINDX logger to log the error message. @section libdhcpMTConsiderations Multi-Threading Consideration for DHCP library By default APIs provided by the DHCP library are not thread safe. For instance packets or options are not thread safe. Exception are: - external sockets are thread safe (the container used to manage external socket is thread safe so one can for instance delete an external socket at any time). - interface lookup cache is Kea thread safe (i.e. thread safe when the multi-threading mode is true). - interface send method is thread safe (mainly because it does not change any internal state). - packet queue ring is thread safe. */