.. _radius:

RADIUS
======

.. _radius-overview:

RADIUS Overview
---------------

This hook library allows Kea to interact with two types of RADIUS
services: access and accounting. The most common DHCP and RADIUS
integration is done on the DHCP relay-agent level: DHCP clients send
DHCP packets to DHCP relays; those relays contact the RADIUS server and
either send the packet to the DHCP server or drop it, depending on the
response. It does require DHCP relay hardware to support RADIUS
communication, though, and even if the relay has the necessary support, it is
often not flexible enough to send and receive additional RADIUS
attributes. There is a more appealing alternative: to extend the
DHCP server to talk to RADIUS directly. That is the goal of this library.

.. note::

   This library can only be loaded by the :iscman:`kea-dhcp4` or the
   :iscman:`kea-dhcp6` process.

The major feature of this hook library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server sends an
Access-Request to the RADIUS server and waits for a response. The server
then sends back either an Access-Accept with specific client attributes,
or an Access-Reject. There are two cases supported here: first, the
Access-Accept includes a Framed-IP-Address attribute (for DHCPv4) or a
Framed-IPv6-Address attribute/Delegated-IPv6-Prefix (for DHCPv6),
which are interpreted by Kea as instructions to assign the specified IPv4
or IPv6 address/IPv6 prefix. This effectively means RADIUS can act
as an address-reservation database.

The second supported case is the ability to assign clients to specific
pools based on a RADIUS response. In this case, the RADIUS server sends
back an Access-Accept with a Framed-Pool attribute.
For both DHCPv4 and DHCPv6, Kea interprets this attribute as a client class.
With the addition of the ability to limit access to pools to
specific classes (see :ref:`classification-pools`), RADIUS can be
used to force the client to be assigned a dynamic address or prefix from a
specific pool. Furthermore, the same mechanism can be used to control
what kind of options the client gets if there are DHCP options
specified for a particular class.

.. _radius-config:

RADIUS Hook Library Configuration
---------------------------------

The RADIUS hook is a library that must be loaded by either :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` servers. Unlike some other available hook libraries, this one
takes many parameters. For example, this configuration can be used:

.. parsed-literal::

    {
      "Dhcp4": {

        // Your regular DHCPv4 configuration parameters go here.

        "hooks-libraries": [
          {
            // Note that the RADIUS access service requires host-cache for
            // proper operation, so this library is loaded as well.
            "library": "libdhcp_host_cache.so"
          },
          {
            "library": "libdhcp_radius.so",
            "parameters": {

              // Specify where the dictionary is located.
              "dictionary": "/etc/kea/radius/dictionary",

              // Specify which address to use to communicate with RADIUS servers
              "bindaddr": "*"

              // More RADIUS parameters go here.
            }
          }
        ]
      }
    }

RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone.
However, we do have an example that showcases some of the more common
features; please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
sources.

The RADIUS hook library supports the following global configuration
flags:

-  ``bindaddr`` (default ``"*"``) - specifies the address to be used by the
   hook library in communication with the RADIUS servers. The ``"*"`` special
   value tells the kernel to choose the address at hook library load time.

-  ``canonical-mac-address`` (default ``false``) - specifies whether MAC
   addresses in attributes follow the canonical RADIUS format (lowercase
   pairs of hexadecimal digits separated by ``-``).

-  ``client-id-pop0`` (default ``false``) - is used with
   :ischooklib:`libdhcp_flex_id.so`; it removes the leading zero (or pair of zeroes
   in DHCPv6) type in the client ID (DUID in DHCPv6). See
   ``client-id-printable`` for any value implications when used in conjunction
   with it.

-  ``client-id-printable`` (default ``false``) - checks whether the
   ``client-id``/``duid`` content is printable and uses it as is instead of in
   hexadecimal. It implies that ``client-id-pop0`` and ``extract-duid`` as 0 and 255 are
   not printable.

-  ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the
   servers so those that have proved responsive so far are contacted
   first, and the servers that have proved unresponsive are left to try later. The
   deadtime value specifies the number of seconds after which a server is
   considered unresponsive. 0 disables the mechanism.

-  ``dictionary`` (default ``"/etc/kea/radius/dictionary"``) - is the
   attribute and value dictionary; note that it is a critical parameter.
   A dictionary is provided by Kea and is set by default.

-  ``extract-duid`` (default ``true``) - extracts the embedded DUID from an
   RFC 4361-compliant DHCPv4 client ID. See ``client-id-printable`` for any
   value implications when used in conjunction with it.

-  ``identifier-type4`` (default ``"client-id"``) - specifies the identifier
   type to build the User-Name attribute for DHCPv4; it should be the same as the
   host identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
   ``replace-client-id`` must be set to ``true`` and ``client-id`` must be used
   with ``client-id-pop0`` enabled.

-  ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to
   build the User-Name attribute for DHCPv6; it should be the same as the host
   identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
   ``replace-client-id`` must be set to ``true`` and ``duid`` must be used with
   ``client-id-pop0`` enabled.

-  ``nas-ports`` (default ``[]``), specifies the NAS port to use in place of
   a subnet ID (default behavior). It is an array of maps, each map having two
   elements at most: the mandatory NAS port value, and optionally, a selector
   consisting of either a subnet ID, a subnet prefix, or a shared-network name.
   If the selector is applied to the packet, the NAS port is used instead of the
   subnet ID. When the subnet ID is 0 or missing, the specified NAS port acts as
   a default. The substitution happens for all packets that did not match a
   selector.

-  ``realm`` (default ``""``) - is the default realm.

-  ``reselect-subnet-address`` (default ``false``) - enables subnet reselection
   according to the value of the Framed-IP-Address or, respectively,
   the Framed-IPv6-Address attribute from the RADIUS access response. With this
   flag enabled, if the IP address is not in the range of the currently selected
   subnet, but is in the range of another subnet that is selectable with regards to
   other criteria, the latter subnet is selected and used further in the lease
   assignment process.

-  ``reselect-subnet-pool`` (default ``false``) - enables subnet reselection
   according to the value of the Framed-Pool attribute from the RADIUS access
   response. With this flag enabled, if the currently selected subnet is not
   guarded by the client class represented by the attribute value, but there is
   another selectable subnet that is guarded by it, the latter subnet is
   selected and used further in the lease assignment process.
   This reselection is attempted first, and if successful, it prevents the
   function of ``reselect-subnet-address`` from coming into effect.

-  ``retries`` (default ``3``) - is the number of retries before trying the
   next server.

-  ``session-history`` (default ``""``) - is the name of the file providing
   persistent storage for accounting session history.

 - ``thread-pool-size`` (default ``0``) indicates the number of threads that
   are used for sending RADIUS requests and processing RADIUS responses for both
   access and accounting services before passing them to the core thread pool. A
   value of ``0`` instructs the RADIUS hook library to use the same number of
   threads used for core DHCP processing. This value is only relevant if the Kea
   core is configured as multi-threaded; a single-threaded Kea core results in
   single-threaded RADIUS processing.

-  ``timeout`` (default ``10``) - is the number of seconds during which a
   response is awaited.

Two services are supported:

-  ``access`` - the authorization service.

-  ``accounting`` - the accounting service.

At the service level, three sections can be configured:

-  Servers that define RADIUS services that the library is expected to
   contact. Each server may have the following items specified:

   -  ``name`` - specifies the IP address of the server. A domain name may be
      used and will be resolved at hook library load time.

   -  ``port`` - specifies the UDP port of the server. By default, it is 1812
      for access and 1813 for accounting.

   -  ``secret`` - authenticates messages.

   When no server is specified, the service is disabled.

-  Attributes which define additional information that the Kea server
   sends to a RADIUS server. The parameter must be identified either
   by a name or type. Its value can be specified in one of three
   possible ways: ``data`` (which defines a plain text value), ``raw`` (which
   defines the value in hex), or ``expr`` (which defines an expression
   that is evaluated for each incoming packet independently).

   -  ``name`` - is the name of the attribute.

   -  ``type`` - is the type of the attribute. Either the type or the name must be
      provided, and the attribute must be defined in the dictionary.

   -  ``data`` - is the first of three ways to specify the attribute content.
      It specifies the textual representation of the attribute content.

   -  ``raw`` - is the second of three ways to specify the attribute content.
      It specifies the content in hexadecimal.

   -  ``expr`` - is the last of the three ways to specify the attribute content.
      It specifies an evaluation expression on the DHCP query packet.

   -  ``vendor`` -  since Kea 3.1.2 is the vendor id of the attribute.
      It always contains a string with the vendor name or an integer literal.

    Attributes are supported only for the access service.

.. note::

   Vendor-Specific attribute can be specified in two ways: using a ``raw``
   value which must include the vendor and the vsa data, note that the ``data``
   value is no longer supported since Kea 3.1.2, and the ``expr`` value
   is evaluated to the content of the attribute. The second way was added
   by 3.1.2 and allows to specify a vendor attribute which is automatically
   embedded into a Vendor-Specific attribute.

- The ``peer-updates`` boolean flag (default ``true``) controls whether lease
  updates coming from an active High-Availability (HA) partner should result in
  an accounting request. This may be desirable to remove duplicates if HA
  partners are configured to send requests to the same RADIUS server. The flag is
  only supported by the accounting service. The lease synchronization process at
  the startup of an HA node does not trigger a RADIUS accounting request,
  regardless of the value of this flag.

- The ``max-pending-requests`` positive integer (default ``0``) limits the
  number of pending RADIUS requests. It is supported only by the access service.
  The value ``0`` means no limit; ``64`` is a recommended setting.

For example, to specify a single access server available on localhost
that uses ``"1234"`` as a secret, and tell Kea to send three additional
attributes (``User-Password``, ``Connect-Info``, and ``Configuration-Token``),
the following snippet could be used:

.. parsed-literal::

    {
      "parameters": {

        // Other RADIUS parameters here

        "access": {

          // This starts the list of access servers.
          "servers": [
            {
              // These are parameters for the first (and only) access server
              "name": "127.0.0.1",
              "port": 1812,
              "secret": "1234"
            }
          // Additional access servers could be specified here.
          ],

          // This defines a list of additional attributes Kea will send to each
          // access server in Access-Request.
          "attributes": [
            {
              // This attribute is identified by name (must be present in the
              // dictionary) and has static value (i.e. the same value will be
              // sent to every server for every packet).
              "name": "User-Password",
              "data": "mysecretpassword"
            },
            {
              // It is also possible to specify an attribute using its type,
              // rather than a name. 77 is Connect-Info. The value is specified
              // using hex. Again, this is a static value. It will be sent the
              // same for every packet and to every server.
              "type": 77,
              "raw": "65666a6a71"
            },
            {
               // This example shows how an expression can be used to send dynamic value.
               // The expression (see :ref:`classification-using-expressions`) may take any
               // value from the incoming packet or even its metadata e.g. the
               // interface it was received over from.
               "name": "Configuration-Token",
               "expr": "hexstring(pkt4.mac,':')"
            }
          ] // End of attributes
        }, // End of access

        // Accounting parameters.
        "accounting": {
          // This starts the list of accounting servers.
          "servers": [
            {
              // These are parameters for the first (and only) accounting server
              "name": "127.0.0.1",
              "port": 1813,
              "secret": "1234"
            }
            // Additional accounting servers could be specified here.
          ]
        }
      }
    }

Customization is sometimes required for certain attributes by devices belonging
to various vendors. This is a great way to leverage the expression evaluation
mechanism. For example, MAC addresses which might be used as a convenience
value for the ``User-Password`` attribute are most likely to appear in colon-hexadecimal
notation (``de:ad:be:ef:ca:fe``), but they might need to be expressed in
hyphen-hexadecimal notation (``de-ad-be-ef-ca-fe``). Here's how to specify that:

.. code-block:: json

   {
      "parameters": {
         "access": {
            "attributes": [
               {
                  "name": "User-Password",
                  "expr": "hexstring(pkt4.mac, '-')"
               }
            ]
         }
      }
   }

And here's how to specify period-separated hexadecimal notation (``dead.beef.cafe``), preferred by Cisco devices:

.. code-block:: json

   {
      "parameters": {
         "access": {
            "attributes": [
               {
                  "name": "User-Password",
                  "expr": "substring(hexstring(pkt4.mac, ''), 0, 4) + '.' + substring(hexstring(pkt4.mac, ''), 4, 4) + '.' + substring(hexstring(pkt4.mac, ''), 8, 4)"
               }
            ]
         }
      }
   }


For the access service of :ischooklib:`libdhcp_radius.so` to operate properly,
:ischooklib:`libdhcp_host_cache.so` must also be loaded. The reason for this
is somewhat complex. In a typical deployment, DHCP clients send
their packets via DHCP relay, which inserts certain Relay Agent
Information options, such as ``circuit-id`` or ``remote-id``. The values of
those options are then used by the Kea DHCP server to formulate the
necessary attributes in the Access-Request message sent to the RADIUS
server. However, once the DHCP client gets its address, it then renews
by sending packets directly to the DHCP server. The relays cannot
insert their RAI options at that point, and the DHCP server cannot send
the Access-Request queries to the RADIUS server by using just the
information from incoming packets. Kea needs to keep the information
received during the initial Discover/Offer exchanges and use it again
later when sending accounting messages.

This mechanism is implemented based on user context in host
reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for
details.) The host-cache mechanism allows the information retrieved by
RADIUS to be stored and used later instead of doing another authorization
round-trip to the RADIUS server. In other words, the host-cache mechanism
is mandatory for the access service. The Kea configuration is rejected if
:ischooklib:`libdhcp_host_cache.so` is not loaded alongside :ischooklib:`libdhcp_radius.so`.

.. note::

   Currently the RADIUS hook library is incompatible with the
   ``early-global-reservations-lookup`` global parameter, i.e.
   setting the parameter to ``true`` raises an error when the
   hook library is loaded.

.. note::

   Currently the RADIUS hook library is incompatible with the
   multi-subnet shared networks that have host reservations other
   than global. Loading the RADIUS hook library in a Kea DHCP server
   that has this configuration raises an error.

.. note::

    Currently the ``reselect-subnet-address`` and ``reselect-subnet-pool``
    parameters are incompatible with the hub-and-spoke configuration of the
    :ischooklib:`libdhcp_ha.so`. This hook library uses an originally
    selected subnet for choosing an HA relationship to process a packet.
    The subnet reselection may interfere with this choice. See the
    :ref:`ha-hub-and-spoke` for details.

.. _radius-server-example:

RADIUS Server Setup Example
---------------------------

The RADIUS hook library requires at least one RADIUS server to function. One
popular open source implementation is FreeRADIUS; here's how to
set it up to enable basic functionality in Kea.

1. Install FreeRADIUS through the package manager or from the tarballs available
   on [the freeradius.org download page](https://freeradius.org/releases/).

2. Establish the FreeRADIUS configuration directory. It's commonly
   ``/etc/freeradius``, but it may be ``/etc/raddb``.

3. Generate certificates. Go to ``/etc/freeradius/certs``.
   Run ``./bootstrap`` or ``make``.
   Wait until finished. It should take a few seconds.

4. Check that the server is able to start.
   Running with the ``-X`` flag is a good way to display potential errors.
   Run ``radiusd -X`` or ``freeradius -X``, whichever is available.
   It should display ``Ready to process requests`` on the final line.

5. If the Kea DHCP server and the RADIUS server are on different machines,
   edit ``/etc/freeradius/clients.conf`` with the proper address under
   ``ipadddr``. This file is also where the secret is set; it needs to match
   the one set in the hook library's configuration.

6. If RADIUS is used to authorize DHCP clients, each DHCP
   client needs to have an entry in the authorize file, which can be commonly
   found at:

   - ``/etc/raddb/mods-config/files/authorize``
   - ``/etc/freeradius/3.0/mods-config/files/authorize``
   - ``/etc/freeradius/users`` (for RADIUS 2.x series)

   The passwords for entries must match the passwords
   in the configuration of the RADIUS hook library under the
   ``User-Password`` attribute. Each entry can have zero or more
   attributes.

   In the following example, there are six entries with the password set to the
   client ID, which needs to be dynamically set in the hook library's
   configuration. Here's how the entries might look:

   ::

       01:00:0c:01:02:03:04    Cleartext-password := "00:0c:01:02:03:04"

       01:00:0c:01:02:03:05    Cleartext-password := "00:0c:01:02:03:05"
           Framed-IP-Address = "192.0.2.5"

       01:00:0c:01:02:03:06    Cleartext-password := "00:0c:01:02:03:06"
           Framed-IP-Address = "192.0.2.6",
           Framed-Pool = "classical"

       00:03:00:01:00:0c:01:02:03:07    Cleartext-password := "00:0c:01:02:03:07"

       00:03:00:01:00:0c:01:02:03:08    Cleartext-password := "00:0c:01:02:03:08"
           Framed-IPv6-Address = "2001:db8::8"

       00:03:00:01:00:0c:01:02:03:09    Cleartext-password := "00:0c:01:02:03:09"
           Framed-IPv6-Address = "2001:db8::9",
           Framed-Pool = "classroom"

7. Accounting does not need to be modified to work with Kea, but customizations are
   possible in the accounting file, which can commonly be found at:

   - ``/etc/radius-config/mods-config/files/accounting``
   - ``/etc/freeradius/3.0/mods-config/files/accounting``

.. _radius-lease-allocation:

RADIUS Workflows for Lease Allocation
-------------------------------------

The following diagrams show a high-level view of how RADIUS assists with the
lease allocation process in :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`.

.. figure:: ../uml/radius.*

Somewhat tangential to lease allocation, and not shown in the diagrams above,
is the ``command_processed`` callout, which sends Accounting-Request messages
when a lease command is received.

.. _radius-parked-packet-limit:

Parked-Packet Limit
~~~~~~~~~~~~~~~~~~~

Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.

The RADIUS hook library uses this mechanism. To allow for asynchronous
communication between Kea and the RADIUS server and concurrent processing of
DHCP packets by the Kea server, the DHCP request is parked, before the access
request is sent on the subnet select callout. When the access response becomes
available to the Kea DHCP server, the request is unparked, and the server
continues processing it.

.. _radius-differences:

Differences Between RADIUS Hook Libraries Prior To Kea 2.4.0 and As Of 2.6.0
----------------------------------------------------------------------------

The RADIUS hook library in 2.4.0 and prior versions relied on the FreeRADIUS
client library to function. Starting with 2.6.0 and onward, the RADIUS hook
library is standalone, with its own RADIUS client implementation and its own
RADIUS dictionary. There are differences:

.. list-table::
    :header-rows: 1

    * - Feature

      - Old

      - New

    * - Support for Attribute Data Types

      - string, ipaddr, ipv4prefix, integer, integer64, date, ifid, ipv6addr, ipv6prefix, tlv, binary, byte, ether, short, signed, octets

      - string (can simulate any other unsupported data type too), ipaddr, integer, date (interpreted as integer), ipv6addr, ipv6prefix

    * - Names of Standard Attributes

      - Taken from the FreeRADIUS dictionary.

      - Taken from the Kea RADIUS dictionary and the IANA registry. There is an aliasing mechanism built into the library that ensures backward compatibility, e.g. ``Password`` translates to the standard name of the attribute ``User-Password``.

    * - Resolution of RADIUS Server Domain Names

      - At run time.

      - At hook library load time.

    * - Automatic Deduction of Source Address for Reaching RADIUS Servers (configured with ``bindaddr: "*"``)

      - At run time.

      - At hook library load time.

    * - RADIUS Server Limit per Service

      - 8

      - Unlimited

    * - Support for Including Dictionaries Inside Dictionaries

      - Yes

      - since Kea 3.1.2

    * - Support for Vendor Attributes

      - Yes

      - since Kea 3.1.2

    * - Attribute Names and Attribute Values

      - Case-insensitive

      - Case-sensitive

    * - Integer Values

      - Do not require an attribute definition.

      - Must have an associated attribute definition in the dictionary.

    * - Attribute and Integer Value name spaces

      - flat name spaces allowing duplicates.

      - since Kea 3.1.2 different name spaces per vendor.

    * - Reply-Message Presence in the Kea Logs

      - Only as part of the aggregated list of attributes in ``RADIUS_AUTHENTICATION_ACCEPTED``, ``RADIUS_ACCESS_CACHE_INSERT``, ``RADIUS_ACCESS_CACHE_GET`` log messages.

      - Also has a dedicated ``RADIUS_REPLY_MESSAGE_ATTRIBUTE`` message per each Reply-Message attribute logged after a valid RADIUS reply is received.

    * - Behavior of Multiple Attributes of the Same Type (except Reply-Message)

      - Experimentally, only the **first** attribute on the wire from an Access-Accept message is considered.

      - Experimentally, only the **last** attribute on the wire from an Access-Accept message is considered.
