mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-01 06:25:34 +00:00
Code Issues Releases Wiki Activity

[#1587] Rewrapped and fixed many typos

Browse Source
This commit is contained in:
Tomek Mrugalski
2021-04-22 20:10:13 +02:00
committed by Thomas Markwalder
parent 293379bf25
commit ce5f1dbd38
1 changed files with 109 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

207
doc/sphinx/arm/security.rst
View File

@@ -173,50 +173,48 @@ have an impact on deployment security.
Access permissions and root access Access permissions and root access
---------------------------------- ----------------------------------
Kea uses the DHCPv4 and DHCPv6 protocols, which assume the server will open privileged Kea uses the DHCPv4 and DHCPv6 protocols, which assume the server will open privileged UDP port 67
UDP port 67 (DHCPv4) or 547 (DHCPv6). Under normal circumstances that requires (DHCPv4) or 547 (DHCPv6). Under normal circumstances that requires root access. However, with the
root access. However, with the use of the capabilities mechanism on Linux systems, use of the capabilities mechanism on Linux systems, Kea can run from an unprivileged account. See
Kea can run from an unprivileged account. See :ref:`non-root` for details. :ref:`non-root` Section for details.
CA (Control Agent) can accept incoming http or https connections. The default port is 8000, CA (Control Agent) can accept incoming HTTP or HTTPS connections. The default port is 8000, which
which doesn't require privileged access. doesn't require privileged access.
Kea Administrative access Kea Administrative access
------------------------- -------------------------
The three primary Kea daemons (`kea-dhcp4`, `kea-dhcp6` and `kea-dhcp-ddns`) all support The three primary Kea daemons (`kea-dhcp4`, `kea-dhcp6` and `kea-dhcp-ddns`) all support a control
a control channel, which is implemented as a UNIX socket. The control channel is disabled channel, which is implemented as a UNIX socket. The control channel is disabled by default, but most
by default, but most configuration examples have it enabled as it's a very popular feature. configuration examples have it enabled as it's a very popular feature. It opens a UNIX socket. To
It opens a UNIX socket. To read from or write to this socket, generally root access is read from or write to this socket, generally root access is required, although if Kea is configured
required, although if Kea is configured to run as non-root, the owner of the process can to run as non-root, the owner of the process can write to it. Access can be controlled using normal
write to it. Access can be controlled using normal file access control on POSIX systems file access control on POSIX systems (owner, group, others, read/write).
(owner, group, others, read/write).
Kea configuration is controlled by a JSON file on the Kea server. This file can be viewed Kea configuration is controlled by a JSON file on the Kea server. This file can be viewed or edited
or edited by anyone with file permissions (permissions controlled by the operating system). by anyone with file permissions (permissions controlled by the operating system). Note that
Note that passwords are stored in clear text in the configuration file, so anyone with access passwords are stored in clear text in the configuration file, so anyone with access to read the
to read the configuration file can find this information. As a practical matter, anyone with configuration file can find this information. As a practical matter, anyone with permission to edit
permission to edit the configuration file has control over Kea. the configuration file has control over Kea.
Database connections Database connections
-------------------- --------------------
Kea can optionally use an external MySQL, PostgreSQL or Cassandra database to store configuration, Kea can optionally use an external MySQL, PostgreSQL or Cassandra database to store configuration,
host reservations, leases or for forensic logging. The use of databases is a popular feature, but host reservations, leases or for forensic logging. The use of databases is a popular feature, but it
it is optional. It's also possible to store data in a flat file on disk. is optional. It's also possible to store data in a flat file on disk.
When using a database, Kea will store and use credentials in the form of username, password, host, When using a database, Kea will store and use credentials in the form of username, password, host,
port and database name in order to authenticate with the database. **These are stored in clear text port and database name in order to authenticate with the database. **These are stored in clear text
in the configuration file.** in the configuration file.**
Depending on the database configuration, it's also possible to check if the system user matches Depending on the database configuration, it's also possible to check if the system user matches the
the database username. Consult MySQL or PostgreSQL manuals for details. database username. Consult MySQL or PostgreSQL manuals for details.
Kea does not support SSL/TLS connection to databases yet. There is a community contributed patch Kea does not support SSL/TLS connection to databases yet. There is a community contributed patch
available for [SSL support for MySQL](https://github.com/isc-projects/kea/pull/15) and available for `SSL support for MySQL <https://github.com/isc-projects/kea/pull/15>`_ and `SSL support
[SSL support for Cassandra](https://github.com/isc-projects/kea/pull/118). for Cassandra <https://github.com/isc-projects/kea/pull/118>`_. If the communication channel to the
If the communication channel to the database is a concern, the database can be run locally on the database is a concern, the database can be run locally on the Kea server.
Kea server.
Kea Logging Kea Logging
----------- -----------
@@ -244,10 +242,11 @@ The primary use cases for the cryptographic libraries are:
- random number generation (but not for usage requiring a crypto grade generator). - random number generation (but not for usage requiring a crypto grade generator).
For OpenSSL and Botan, only low level crypto interface is used (e.g. libcrypto). Kea does not link For OpenSSL and Botan, only low level crypto interface is used (e.g. libcrypto). Kea does not link
with libssl. Some dependencies, for instance database client libraries, can also depend on a crypto library. with libssl. Some dependencies, for instance database client libraries, can also depend on a crypto
library.
One way to limit exposure for potential OpenSSL or Botan vulnerabilities is to not use the DDNS. One way to limit exposure for potential OpenSSL or Botan vulnerabilities is to not use the DDNS. The
The libraries would still be necessary to build and run Kea, but the code would never be used, so any libraries would still be necessary to build and run Kea, but the code would never be used, so any
potential bugs in the libraries would never had a chance to be exploited. potential bugs in the libraries would never had a chance to be exploited.
TSIG signatures TSIG signatures
@@ -262,122 +261,134 @@ Kea supports the following algorithms when signing DNS Updates with TSIG signatu
- HMAC-SHA384 - HMAC-SHA384
- HMAC-SHA512 - HMAC-SHA512
See :ref:`d2-tsig-key-list-config` for an up to date list. See :ref:`d2-tsig-key-list-config` Section for an up to date list.
Kea uses SHA256 to calculate DHCID records. This is irrelevant from the cryptography perspective, Kea uses SHA256 to calculate DHCID records. This is irrelevant from the cryptography perspective, as
as the DHCID record is only used to generate unique identifiers for two devices that may have been the DHCID record is only used to generate unique identifiers for two devices that may have been
assigned the same IP address at different times. assigned the same IP address at different times.
Raw socket support Raw socket support
------------------ ------------------
In principle, Kea DHCPv4 uses raw sockets to receive traffic from clients. The difficulty is with receiving In principle, Kea DHCPv4 uses raw sockets to receive traffic from clients. The difficulty is with
packets from devices that don't have an IPv4 address yet. When dealing with direct traffic (where both client receiving packets from devices that don't have an IPv4 address yet. When dealing with direct traffic
and server are connected to the same link, not separated by relays), the kernel normally drops the packet as (where both client and server are connected to the same link, not separated by relays), the kernel
the source IP address is 0.0.0.0. Therefore Kea needs to open raw sockets to be able to receive this traffic. normally drops the packet as the source IP address is 0.0.0.0. Therefore Kea needs to open raw
sockets to be able to receive this traffic.
However, this is not necessary if all the traffic is coming via relays, which is often the case in many networks. However, this is not necessary if all the traffic is coming via relays, which is often the case in
In that case normal UDP sockets can be used instead. There is a `dhcp-socket-type` parameter that controls that many networks. In that case normal UDP sockets can be used instead. There is a `dhcp-socket-type`
behavior. parameter that controls that behavior.
The default is to permit raw socket usage, as it is most versatile. The default is to permit raw socket usage, as it is most versatile.
When using raw sockets, Kea is able to receive raw layer 2 packet, bypassing most firewalls (including iptables). When using raw sockets, Kea is able to receive raw layer 2 packet, bypassing most firewalls
This effectively means that when raw sockets are used, the iptables can't be used to block DHCP traffic. This is (including iptables). This effectively means that when raw sockets are used, the iptables can't be
a design choice of the Linux kernel. used to block DHCP traffic. This is a design choice of the Linux kernel.
Kea can be switched to use UDP sockets. This will work when only relayed traffic (via relays) is received. It Kea can be switched to use UDP sockets. This will work when only relayed traffic (via relays) is
will not work for directly connected devices. While Kea is running with UDP sockets, iptables are working properly. received. It will not work for directly connected devices. While Kea is running with UDP sockets,
iptables are working properly.
Remote Administrative Access Remote Administrative Access
---------------------------- ----------------------------
Kea's Control Agent (CA) exposes a REST API over HTTP or HTTPS (HTTP over TLS). The CA is an optional feature that Kea's Control Agent (CA) exposes a REST API over HTTP or HTTPS (HTTP over TLS). The CA is an
is disabled by default, but it is very popular. When enabled, it listens on loopback address (127.0.0.1 or ::1) by optional feature that is disabled by default, but it is very popular. When enabled, it listens on
default, unless configured otherwise. See :ref:`tls` section about protecting the TLS traffic. Limiting the incoming loopback address (127.0.0.1 or ::1) by default, unless configured otherwise. See :ref:`tls` Section
connections with a firewall, such as iptables, is generally a good idea. about protecting the TLS traffic. Limiting the incoming connections with a firewall, such as
iptables, is generally a good idea.
Note that in HA (High Availability) deployments, DHCP partners connect to each other using CA connection. Note that in HA (High Availability) deployments, DHCP partners connect to each other using CA
connection.
Authentication for REST API Authentication for REST API
--------------------------- ---------------------------
Kea 1.9.0 added support for basic HTTP authentication [RFC7617](https://tools.ietf.org/html/rfc7617) to control Kea 1.9.0 added support for basic HTTP authentication `RFC 7617 <https://tools.ietf.org/html/rfc7617>`_
access for incoming REST commands over HTTP. The credentials (username, password) are stored in a local Kea to control access for incoming REST commands over HTTP. The credentials (username, password) are
configuration file on disk. The username is logged with the API command so it is possible to determine which stored in a local Kea configuration file on disk. The username is logged with the API command so it
authenticated user performed each command. The basic HTTP authentication is weak on its own as there are known is possible to determine which authenticated user performed each command. The basic HTTP
dictionary attacks, but those attacks require man-in-the-middle to get access to the HTTP traffic. That can be authentication is weak on its own as there are known dictionary attacks, but those attacks require
eliminated by using basic HTTP authentication only over TLS. In fact, if possible, using client cerificates for man-in-the-middle to get access to the HTTP traffic. That can be eliminated by using basic HTTP
TLS is better than using basic HTTP authentication. authentication only over TLS. In fact, if possible, using client certificates for TLS is better than
using basic HTTP authentication.
Kea 1.9.2 introduced a new `auth` hook point. With this new hook point it is now possible to develop an external Kea 1.9.2 introduced a new ``auth`` hook point. With this new hook point, it is possible to develop an external
hook library to extend the access controls, integrate with another authentication authority or add role-based hook library to extend the access controls, integrate with another authentication authority, or add role-based
access control to the Control Agent. access control to the Control Agent.
Kea processes Kea processes
============= =============
The following sections discuss various aspects of Kea as project and how the team handles vulnerabilities, testing The following sections discuss various aspects of Kea as a project and how the team handles
and other related aspects. vulnerabilities, testing, and other related aspects.
Vulnerability Handling Vulnerability Handling
---------------------- ----------------------
ISC is an experienced and active participant in the industry standard vulnerability disclosure process and ISC is an experienced and active participant in the industry standard vulnerability disclosure
maintains accurate documentation on our process and vulnerabilities in ISC software. Any critical vulnerabilities process and maintains accurate documentation on our process and vulnerabilities in ISC software.
(those that score >5.0 on CVSSv3) are publicly disclosed and documented and reported to Mitre/CERT. Any critical vulnerabilities (those that score >5.0 on CVSSv3) are publicly disclosed and documented
and reported to Mitre/CERT.
In case of a security vulnerability in Kea, ISC will notify support customers ahead of the public disclosure, and In case of a security vulnerability in Kea, ISC will notify support customers ahead of the public
will provide a patch and/or updated installer package that remediates the vulnerability. disclosure, and will provide a patch and/or updated installer package that remediates the
vulnerability.
When security update is published, both source code and the native (DEB, RPM and APK) packages are published on the When security update is published, both source code and the native (DEB, RPM and APK) packages are
same day. This helps taking leverage of the native Linux mechanisms (such as Debian's and Ubuntu's apt or RedHat's dnf) published on the same day. This helps taking leverage of the native Linux mechanisms (such as
to update quickly. Debian's and Ubuntu's apt or RedHat's dnf) to update quickly.
Code quality and testing Code quality and testing
------------------------ ------------------------
Kea undergoes extensive tests during its development. The following is an excerpt from all the processes that are used Kea undergoes extensive tests during its development. The following is an excerpt from all the
to ensure adequate code quality: processes that are used to ensure adequate code quality:
- Each line of code goes through a formal review before it is accepted. The review process is documented and available - Each line of code goes through a formal review before it is accepted. The review process is
publicly. documented and available publicly.
- Roughly 50% of the source code is dedicated to unit tests. As of Dec. 2020, there are over 6000 unit tests and the number - Roughly 50% of the source code is dedicated to unit tests. As of Dec. 2020, there are over 6000
is growing with most completed tickets. There is a requirement that every new piece of code has to come with unit tests unit tests and the number is growing with most completed tickets. There is a requirement that
before it is accepted. every new piece of code has to come with unit tests before it is accepted.
- There are around 1500 system tests available that test Kea. Those simulate correct and invalid situations, covering - There are around 1500 system tests available that test Kea. Those simulate correct and invalid
network packets (mostly DHCP, but also DNS, HTTP, HTTPS and others), command-line usage, API calls, database interactions, situations, covering network packets (mostly DHCP, but also DNS, HTTP, HTTPS and others),
scripts and more. command-line usage, API calls, database interactions, scripts and more.
- There are performance tests with over 80 scenarios that test Kea overall performance and resiliency to various levels - There are performance tests with over 80 scenarios that test Kea overall performance and
of traffic, measuring various metrics (latency, leases per seconds, packets per seconds, CPU usage, memory utilization and resiliency to various levels of traffic, measuring various metrics (latency, leases per seconds,
others). packets per seconds, CPU usage, memory utilization and others).
- Kea uses CI (Continuous Integration). This means that great majority of tests (all unit and system tests, and in some cases - Kea uses CI (Continuous Integration). This means that great majority of tests (all unit and system
also performance tests) are run for every commit. Many lighter tests are ran on branches, before the code is even accepted. tests, and in some cases also performance tests) are run for every commit. Many lighter tests are
- Negative testing. Many unit and system tests check for negative scenarios, such as incomplete, broken, truncated packets, ran on branches, before the code is even accepted.
API commands, configuration files, incorrect sequences (such as sending packets in invalid order) and more. - Negative testing. Many unit and system tests check for negative scenarios, such as incomplete,
- Kea team uses many tools that perform automatic code quality checks, such as danger or our own internal sanity checkers. broken, truncated packets, API commands, configuration files, incorrect sequences (such as sending
- Kea team uses static code analyzers: Coverity Scan, shellcheck, danger. packets in invalid order) and more.
- Kea team uses many tools that perform automatic code quality checks, such as danger or our own
internal sanity checkers. - Kea team uses static code analyzers: Coverity Scan, shellcheck, danger.
- Kea team uses dynamic code analyzers: Valgrind, Thread Sanitizer (TSAN). - Kea team uses dynamic code analyzers: Valgrind, Thread Sanitizer (TSAN).
Fuzz testing Fuzz testing
------------ ------------
Kea team has a process for running fuzz testing, using [AFL](https://github.com/google/AFL). There are two modes which are run. Kea team has a process for running fuzz testing, using `AFL <https://github.com/google/AFL>`_. There
First fuzzes incoming packets, effectively throwing millions of mostly broken packets at Kea per day. The second mode are two modes which are run. First fuzzes incoming packets, effectively throwing millions of mostly
fuzzes configuration structures and forces Kea to attempt to load them. Those two modes are being run continuously since broken packets at Kea per day. The second mode fuzzes configuration structures and forces Kea to
around 2018. The input seeds (the data being used to generate or "fuzz" other input) are changed every once in a while. attempt to load them. Those two modes are being run continuously since around 2018. The input seeds
(the data being used to generate or "fuzz" other input) are changed every once in a while.
Release integrity Release integrity
----------------- -----------------
Software releases are signed with PGP, and distributed via the ISC web site, which is itself DNSSEC-signed, so you can be Software releases are signed with PGP, and distributed via the ISC web site, which is itself
confident the software has not been tampered with. DNSSEC-signed, so you can be confident the software has not been tampered with.
Bus Factor Bus Factor
---------- ----------
According to [coreinfrastructure](https://bestpractices.coreinfrastructure.org/), a "bus factor" or a "truck factor" is the According to `Core Infrastructure project <https://bestpractices.coreinfrastructure.org/>`_, a "bus
minimum number of project members that have to suddenly disappear from a project ("hit by a bus") before the project stalls due factor" or a "truck factor" is the minimum number of project members that have to suddenly disappear
to lack of knowledgeable or competent personnel. It's hard to estimate precisely, but the bus factor for Kea is somewhere around from a project ("hit by a bus") before the project stalls due to lack of knowledgeable or competent
5. As of 2021, there are 6 core developers and 2 QA engineers, with many more additional persons getting involved frequently personnel. It's hard to estimate precisely, but the bus factor for Kea is somewhere around 5. As of
(product manager, support team, IT, etc). The team is dispersed around the US and Europe. 2021, there are 6 core developers and 2 QA engineers, with many more additional persons getting
involved frequently (product manager, support team, IT, etc). The team is dispersed around the US
and Europe.