path: root/src/lib/dhcp/libdhcp++.dox

// 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.

*/