Adding upstream version 3.2.5+dfsg.upstream/3.2.5+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 277 insertions, 0 deletions

diff --git a/doc/antora/modules/concepts/nav.adoc b/doc/antora/modules/concepts/nav.adoc
new file mode 100644
index 0000000..493b956
--- /dev/null
+++ b/doc/antora/modules/concepts/nav.adoc
@@ -0,0 +1,6 @@
+* xref:index.adoc[Concepts]
+** General
+*** xref:aaa.adoc[AAA]
+** Modules
+*** LDAP
+**** xref:modules/ldap/authentication.adoc[Authentication]
diff --git a/doc/antora/modules/concepts/pages/aaa.adoc b/doc/antora/modules/concepts/pages/aaa.adoc
new file mode 100644
index 0000000..294305c
--- /dev/null
+++ b/doc/antora/modules/concepts/pages/aaa.adoc
@@ -0,0 +1,60 @@
+= AAA
+
+== Authorization, Authentication, and Accounting request handling
+
+There are a lot of questions about misconfigured FreeRADIUS servers
+because of misunderstanding of FreeRADIUS operations. This document
+explains how the server operates.
+
+Normally there are two steps in processing an authentication request
+coming from a NAS in FreeRADIUS: authorization and authentication.
+If we use FreeRADIUS as a proxy to re-send the request to another
+RADIUS server there will be additional steps.
+
+=== Authorization
+
+Authorization is the process of finding and returning information
+about what the user is allowed to do.  For example, finding out what
+kind of authentication methods they are allowed to run, and what VLAN
+the user should be placed into.
+
+Authorization modules generally "get data" from somewhere,
+e.g. `ldap`, `sql`, `files`, etc.
+
+The authentication method is usually determined when the server gets
+the users credentials from a database.  Once the credentials are
+available, the server can authenticate the user.
+
+=== Authentication
+
+Authentication is simply a process of comparing user’s credentials in
+request with the "known good" credentials retrieved from a
+database. Authentication usually deals with password
+encryption. The modules `pap`, `chap`, `mschap`, etc. do authentication.
+
+Some modules do both authentication and limited authorization. For
+example, the `mschap` module authenticates MS-CHAP credentials, but it
+may also be used as an authorization module, which verifies that
+request contains `MS-CHAP` related attribute.  If so, the module
+instructs the server to use `mschap` for authentication, too
+
+These dual modules are usually related to protocol-specific
+attributes, such as the `pap` module for the `User-Password`
+attribute, `chap` for `CHAP-Password`, `mschap` for `MS-CHAP-*`, etc.
+
+=== Request Processing
+
+When the server processes requests, it manages four
+xref:unlang:list.adoc[attribute lists]:
+
+`request`:: attributes taken from the received packet
+
+`reply`:: attributes which will be sent in the reply
+
+`control`:: attributes used to control how the server operates.  These are never sent in a packet
+
+`session-state`:: attributes which are saved and restroed across multiple request / reply exchanges.
+
+All of these lists are available to all modules.  All of these
+lists are available in xref:unlang:index.adoc[Unlang].
+
diff --git a/doc/antora/modules/concepts/pages/index.adoc b/doc/antora/modules/concepts/pages/index.adoc
new file mode 100644
index 0000000..f2bc25f
--- /dev/null
+++ b/doc/antora/modules/concepts/pages/index.adoc
@@ -0,0 +1,8 @@
+= Concepts
+
+This section documents concerning the protocols and modules used by the
+FreeRADIUS server.
+
+It intended to provide more theoretical information about particular subjects
+than would be appropriate to include inline in module configurations or as
+sidebars in howto guides.
diff --git a/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc b/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc
new file mode 100644
index 0000000..edc553e
--- /dev/null
+++ b/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc
@@ -0,0 +1,203 @@
+== Authenticating Users with LDAP
+
+Please be aware the FreeRADIUS is an AAA server, and LDAP
+is a _database_.  This separation of roles means that FreeRADIUS
+supports multiple kinds of authentication protocols such as `PAP`,
+`CHAP`, `MS-CHAP`, etc.  An LDAP database supports only one
+authentication method: "bind as user".  This authentication method is
+compatible only with PAP.
+
+Our recommendation is to use LDAP as a database.  FreeRADIUS should
+read the "known good" password from LDAP, and then use that
+information to authenticate the user.  It is almost always wrong to
+use the LDAP "bind as user" method for authenticating users.
+
+The only caveat to the above recommendation is Active Directory.  For
+"security" reasons, Active Directory will not return the "known good"
+password to FreeRADIUS over a standard LDAP query.  Therefore when
+Active Directory is used, the choices are:
+
+PAP::
+Use "bind as user"
+
+MS-CHAP::
+Use xref:raddb:mods-available/ntlm_auth.adoc[`ntlm`] or xref:raddb:mods-available/winbind.adoc[`winbind`].
+
+Due to the limitations of Active Directory, There are unfortunately no
+other possible choices.
+
+== LDAP Security Recommendations
+
+The credentials (username *and* password) for FreeRADIUS to use to
+connect to your LDAP server(s) should be secure.  We make the
+following recommendations for LDAP "best practices" security.
+
+* Create a dedicated account for use by FreeRADIUS
+
+* Ensure that this account does not have administrator access
+
+* Ensure that this account is read-only, and has no write permissions
+
+* Start by using 'simple authentication' instead of
+  https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer[SASL].
+  The SASL protocol should be attempted only after 'simple
+  authentication' has been verified to work.
+
+* Use TLS for connecting between FreeRADIUS and the LDAP server.  See
+  the `tls` sub-section of the default `ldap` module for instructions
+
+* When storing RADIUS user profiles (quotas, `Simultaneous-Use` flags,
+  access time restrictions, etc) in LDAP, the LDAP schema
+  `doc/schemas/ldap/openldap/freeradius-radius.schema` must first be imported
+  into the LDAP server.
+
+== Authentication method compatibility
+
+The LDAP module is compatible a few different kinds of authentication
+methods.  Note that we say _compatible_, and not _supports_.  LDAP
+servers are databases, and do not support authentication protocols
+such as CHAP, MS-CHAP, or EAP.
+
+PAP::
+The user supplies a `User-Password` (plaintext or EAP-TTLS/PAP)
++
+FreeRADIUS reads the "known good" password from LDAP, and compares
+that to what the user entered.
+
+Bind as user::
+The user supplies a `User-Password` (plaintext or EAP-TTLS/PAP)
++
+FreeRADIUS uses that password to "bind as the user" to LDAP, using the
+supplied `User-Name` and `User-Password.  If the bind is successfull,
+the user is authenticated.  Otherwise, authentication fails.
+
+CHAP::
+The user supplies a `CHAP` password attribute.
++
+FreeRADIUS reads the "known good" password from LDAP in cleartext, and
+compares that to what the user entered.
+
+MS-CHAP::
+The user supplies a `MS-CHAP` password attribute.  Either as
+MS-CHAPv2, or as PEAP/MSCHAPv2, or as EAP-TTLS/MS-CHAPv2.
++
+FreeRADIUS reads the "known good" password from LDAP in cleartext, or
+as an NT hash, and compares that to what the user entered.
+
+All of above authentication methods other than "bind as user" require
+that FreeRADIUS obtain the `userPassword` field from LDAP.  If that
+field is not returned to FreeRADIUS, then normal authentication is
+impossible.  Either FreeRADIUS has to be configured to use "bind as
+user" for authentication, or the LDAP database has to be updated to
+return the `userPassword` field to FreeRADIUS.  This change usually
+involves giving the FreeRADIUS "read-only" user permission to read the
+`userPassword` field.
+
+Again, the best method is to test authentication is with the
+xref:howto:modules/ldap/ldapsearch/index.adoc[ldapsearch] tool.
+These tests *must* be run prior to configuring FreeRADIUS.  We strongly
+recommend having the LDAP database return the `userPassword` field to
+FreeRADIUS, so that FreeRADIUS can authenticate the user.
+
+We also strongly recommend that the passwords be stored in LDAP as
+cleartext.  Otherwise, the only authentication methods that will work
+are PAP and EAP-TTLS/PAP.  The next section explains these issues in
+more detail.
+
+== Password Storage Methods
+
+If the `userPassword` field is returned from LDAP to FreeRADIUS, that
+information can be stored in a number of different formats:
+
+* the value can be cleartext
+* the value can be prepended with a string enclosed by braces, such as with `{crypt}` or `{ssha3}`.
+* the value can be have a suffix of `::`, in which case the password is generally a https://en.wikipedia.org/wiki/Base64[base64] encoded version of the real password
+
+TIP: Base64 values can be decoded via the command: `printf "%s"
+"VALUE" | base64 -d`
+
+FreeRADIUS is capable of understanding and parsing all of the above
+formats.  There is sufficient information in the password values to
+determine what format it is in (base64, binary, or text), and what
+password "encryption" mechanism has been used (crypt, MD5, SHA, SSHA2,
+SHA3, etc).  All that is necessary is that the
+xref:raddb:mods-available/ldap.adoc[ldap module] be configured to map
+the `userPassword` LDAP field to the `&control.Password.With-Header`
+attribute in FreeRADIUS.  FreeRADIUS will then "do the right thing" to
+authenticate the user.
+
+This mapping is done in the default module configuration.  There are
+no additional changes required for FreeRADIUS to correctly read and
+decode the `userPassword` field from LDAP.  Please see the
+xref:raddb:mods-available/pap.adoc[pap module] for a full list of
+supported password "encryption" formats.
+
+== Additional Considerations
+
+There are some major caveats with the above authentication methods.
+The first is that we *strongly recommend* against using "bind as
+user".  This process is slow, and causes unnecessary churn in the
+connections used to contact the LDAP server.  Further, the "bind as
+user" process works _only_ when a `User-Password attribute exists in
+the request.  If any other authentication type is used in the request,
+then the "bind as user" _will not work_.  There is no amount of
+"fixing" things or configuration changes which will make it work.
+
+The second caveat is that the `CHAP` authentication type works _only_
+when a "clear text" password is stored in the LDAP database.  The
+`CHAP` calclulations are designed around having access to the "clear
+text" password.  It is impossible to use any "encrypted" or "hashed"
+passwords with `CHAP`.
+
+The third caveat is that the `MS-CHAP` authentication type works
+_only_ when a "clear text" password or "NT hashed" passwords which are
+stored in the LDAP database.  The `MS-CHAP` calculations are designed
+around having access to "known good" passwords in those formats.  It
+is impossible to use any other kind of "encrypted" or "hashed"
+passwords with `MS-CHAP`.
+
+The final caveat is that when the LDAP database contains "encrypted"
+or "hashed" passwords, the _only_ authentication type which is
+compatible with those passwords is PAP.  i.e. when the `User-Password`
+is supplied to FreeRADIUS.
+
+For recommendations on password storage methods in LDAP, please see
+the LDAP
+https://openldap.org/doc/admin24/security.html#Password%20Storage[password
+storage] page.  Please note that the recommendations there are made
+for LDAP security, and pay no attention to the caveats described
+above.  When both RADIUS and LDAP are used together, then the
+requirements of _both_ systems must be met in order for them to work
+together.  In many cases, a naive approach to LDAP security will
+prevent RADIUS from working.
+
+The issue of a database storing passwords in clear-text has to be
+balanced against the users sending clear-text passwords in
+authentication protocols.  While those passwords are protected by TLS
+(EAP-TTLS) or by RADIUS (in it's own "encryption" mechanism), it is
+generally better to use a stronger authentication method than just
+PAP.
+
+In the end, there is no perfect solution to security requirements.
+The choice may be either to give up on using a particular
+authentication method, or to relax the security requirements on LDAP
+and on password storage.  The final decision as to which choice is
+best can only be made by a local administrator.
+
+== Integrating Novell eDirectory with FreeRADIUS
+
+You can integrate Novell eDirectoryTM 8.7.1 or later with FreeRADIUS
+1.0.2 onwards to allow wireless authentication for eDirectory users. By
+integrating eDirectory with FreeRADIUS, you can do the following:
+
+* Use universal password for RADIUS authentication. Universal password
+provides single login and authentication for eDirectory users.
+Therefore, the users need not have a separate password for RADIUS and
+eDirectory authentication.
+* Enforce eDirectory account policies for users. The existing eDirectory
+policies on the user accounts can still be applied even after
+integrating with RADIUS. Also, you can make use of the intruder lockout
+facility of eDirectory by logging the failed logins into eDirectory.
+
+For configuration information please refer to the Novell documentation
+https://www.netiq.com/documentation/edir_radius/