Merge branch 'FreeRADIUS:master' into master

Author: adamel

doc/antora/modules/ROOT/nav.adoc

@@ -5,12 +5,13 @@
 *** xref:debugging/processing.adoc[Processing Packets]
 *** xref:gethelp.adoc[Getting Help]
 ** xref:bestpractices.adoc[Best Practices]
+*** xref:trouble-shooting/eap_certificates.adoc[EAP Certificates]
 ** xref:faq.adoc[Frequently Asked Question (FAQ)]
 ** xref:trouble-shooting/index.adoc[Troubleshooting]
 *** xref:trouble-shooting/user.adoc[User Management]
 *** xref:trouble-shooting/server.adoc[Server Configuration]
 *** xref:trouble-shooting/client.adoc[Client Configuration]
-*** xref:trouble-shooting/connect_nas.adoc[Connectivity-NAS]
+*** xref:trouble-shooting/connect_nas.adoc[Connectivity]
 *** xref:trouble-shooting/datastore.adoc[Datastores]
 
 

doc/antora/modules/ROOT/pages/directories.adoc

@@ -1,6 +1,6 @@
 = Directories
 
-The directories in the server source are laid out ad follows:
+The directories in the server source are laid out as follows:
 
 == Documentation
 

doc/antora/modules/ROOT/pages/trouble-shooting/connect_nas.adoc

@@ -0,0 +1,200 @@
+= EAP Certificates
+
+EAP servers performing TLS-based authentication methods will have one or more
+certificates configured. There are two distinct purposes for these certificates:
+
+  * Server certificates are presented to connecting devices for them to validate their trust of the server.
+  * Trusted CA certificates are used to validate trust of certificates presented by end devices.
+
+FreeRADIUS uses OpenSSL to handle SSL operations. Some of its behavior depends on the version of the OpenSSL libraries it uses and how the global system configuration for OpenSSL is set up.  
+
+When upgrading the operating system and OpenSSL libraries it's crucial to understand any version-specific differences relevant to the functionality of the RADIUS service. Some default behaviours that may change include:
+
+  * The accepted list of protocols, ciphers and key sizes.
+  * The method by which chains are built when validating certificates.
+  * Required properties of certificates in a chain for an end entity certificate to be verified.
+  * The TLS record format that is generated or accepted for on the wire transmission.
+
+== Server certificates
+
+Any RADIUS server performing xref:reference:raddb/mods-available/eap.adoc[TLS-based EAP] must have a server certificate and associated key. This certificate can be signed by a public CA which the end devices already trust, or it can be signed by a self-signed CA managed by the organization. If using a self-signed CA, configure the supplicant to trust the self-signed CA for EAP server authentication purposes. This is often done with a managed security policy.
+
+It’s also possible that a supplicant is instructed to trust an “anchor” certificate in a chain of certificates. The server certificate in this chain has been signed by an intermediate CA certificate, which may have been signed by another CA certificate, and so on, up to a self-signed root CA certificate.
+
+The trust anchor configured on the end device may not be the root CA, in which case this is referred to as validating a "partial chain" as shown below.
+
+         Root CA
+            |
+    Intermediate CA A  <- Supplicant instructed to trust this "anchor"
+            |
+    Intermediate CA B
+            |
+       Server Cert
+
+The simplest set up for the server certificate for FreeRADIUS is to put all certificates into the `certificate file`.  Put the server certificate and any intermediate certificates needed to reach the certificate trusted by the end device. This file must start with the server certificate and work its way up the chain.
+
+While the certificate file can include the certificate trusted by the supplicant, this may cause larger packet exchanges between FreeRADIUS and the end device. Some supplicants may also fail to trust the server if this certificate is included. Therefore, it’s recommended to stop the certificate file at the certificate in the chain that’s immediately before the one configured as a trust anchor.
+
+In the example above, this means the server certificate file should contain:
+
+  * Server Cert
+  * Intermediate CA B
+
+=== Extended Key Use Extension
+
+In order to satisfy the requirements of certain supplicants, server
+certificates must contain the following Extended Key Use extension:
+
+  * Server Authentication - OID 1.3.6.1.5.5.7.3.1
+
+It's strongly recommended to include the following EKU extension in any client certificates generated for EAP-TLS.  (or EAP-PEAP /EAP-TTLS methods in which the client certificate is to be validated):
+
+  * Client Authentication - OID 1.3.6.1.5.5.7.3.2
+
+In addition:
+
+  * Some supplicants (notably Windows) refuse to accept wildcard certificates, so these should be avoided for maximum compatibility.
+  * Some supplicants (notably ChromeOS) reject Extended Validation (EV) certificates.
+  * Apple supplicants will not accept leaf certificates whose validity period is greater than 397 days.
+  * Some supplicants (notable MacOS) require that the certificate include a critical BasicConstraint `CA:FALSE`.
+  * Some supplicants store and check the certificate Subject CN. Others use the Subject Alternate Name. Therefore the same (case-sensitive) server name in the form of an FQDN (not necessarily matching the server's hostname) should be used as *both* the CN and as a SAN.
+
+When replacing certificates, ensure that the replacement certificates match any explict requirements that are configured on the supplicants of all end devices.
+
+For example, specific names (or domain suffixes) expected in the CN and/or
+Subject Alternative Names may be part of requirements that have been pinned in
+the network's 802.1X profile via an explicit managed security policy.
+
+Furthermore, the CN and/or SAN names from certificates presented during previous network connections may have been automatically saved. This action results in an implicit requirement for future certificates. Changing these “learned” properties cause an authentication failure or the user is prompted to manually accept any new certificate with previously unknown properties.
+
+When replacing a server certificate, make sure you have enough time to update the end devices’ policies. This way, the end devices trust the new server certificates before the old ones expire or are replaced.
+
+== Trusted CA certificates
+
+When using “mutual TLS", FreeRADIUS needs to know which CAs to trust to authenticate the end device.  The end devices present certificates to the server like EAP-TLS.
+
+The easiest way to manage this is to put any CAs that must be trusted in a single file (named `ca_file`). Alternatively, the trusted certificates can be placed in a directory (named `ca_dir`).
+
+CAs used for signing end device certificates should NOT be public CAs. Trusting public CAs usually means that an end device presenting any certificate signed by that same CA is trusted. If client authentication uses a public CA, the acceptable client certificates must be resticted (using the `check_cert_cn` option or the `check-eap-tls` virtual server).
+
+However, a self-signed CA used only for EAP authentication, whose private key is known only to the organization, doesn’t have this problem.
+
+
+== Using FreeRADIUS's provided scripts to create certificates
+
+If a CA is not already in use for signing certificates then FreeRADIUS
+ships with scripts which can create a CA, server certificates, and client
+certificates.
+
+See xref:reference:raddb/certs/index.adoc[Certificates] in the Configuration Files section on how to generate certificates and the corresponding `raddb/certs/Makefile` for more details.
+
+== Loading certificates onto the RADIUS servers
+
+Certificates to be loaded onto the RADIUS servers must be copied into
+`raddb/certs` directory.  Use file names which help to identify
+what the certificates are.
+
+The freeradius certificates required at a minimum are:
+
+* ca.pem: `raddb/certs/ca.pem`
+* server.pem: `raddb/certs/server.pem`
+* server.key: `raddb/certs/server.key`
+
+If additional certificates are needed for different EAP methods (e.g. EAP-PEAP
+using one server certificate and EAP-TLS using another) then generate and add the required certificates into this directory.
+
+== Certificates in the FreeRADIUS EAP Configuration
+
+Certificate settings for EAP are found in the eap module configuration
+located in the `raddb/mods-enabled/eap` directory.
+
+If a common set of certificates is used by all EAP methods then it will
+be set in a `tls-config` section called `tls-common`. This section is referenced
+within each EAP method that's enabled.
+
+This section contains at least the following:
+
+    tls-config tls-common {
+    #    private_key_password = whatever
+        private_key_file = ${certdir}/server.key
+        certificate_file = ${certidir}/server.pem
+        auto_chain = no
+        ca_file = ${cadir}/ca.pem
+    #    ca_dir = ${cadir}/trusted
+        tls_min_version = "1.1"
+        tls_max_version = "1.2"
+    }
+
+If applicable, the `private_key_password` item must be un-commented and set to the password used when generating the private key,
+
+The `certificate_file` and `private_key_file` items refer to files that contain
+the server certificate (followed by intermediate CAs up to but not including
+the CA trusted by supplicants) and the private key corresponding to the server
+certificate, respectively.
+
+By setting the `auto_chain` item to `no` the certificate chain will be
+presented to the end device as it is in the server certificate file.  With
+`auto_chain` set to `yes` OpenSSL automatically creates a chain. The chain is based on the certificates in `ca_file` and `ca_dir`. OpenSSL's automatic chain building behaviour differs greatly between versions and may result in a chain that may not reflect what the supplicant expects.
+
+The `ca_file` item refers to a file that contains CA certificates
+which FreeRADIUS trusts when checking client certificates.
+
+The `ca_dir` item refers to a directory containing CA certificates which
+FreeRADIUS trusts when checking client certificates. Additionally, any Certificate Revocation Lists (CR) are included. After modifying this directory the `c_rehash` command must be run.
+
+[NOTE]
+====
+The set of certificates present in `ca_file` determines the list of
+Distingished Names trusted by the server which are sent to an end device when a
+client certificate is requested. For example during EAP-TLS authentication, or
+during PEAP or EAP-TTLS when mutual authentication is requested. This
+**not** true for trusted certificates within the `ca_path` directory.
+====
+
+Many supplicants won't send a client certificate unless its issuer is in the list of trusted certificates sent by the server. Also, the client's issuer may be in the configured client certificate chain. Also. The supplicant won't send a certificate if the list of trusted certificates is empty. This means no ca_file is configured with trusted certificates placed in the ca_dir.
+
+Many supplicants won't send a client certificate unless its issuer (or one of the configured client certificate chain issuers) is in the list of trusted certificates sent by the server. Also, the supplicant won't send a certificate if the list of trusted certificates is empty. This means no ca_file is configured with trusted certificates placed in the ca_dir.
+
+The `tls_min_version` and `tls_max_version` items control which TLS versions
+are acceptable.
+
+In order to allow supplicants to connect using TLS versions 1.0 or
+1.1 the option `cipher_list` within the `tls-config` may need to be set as
+follows
+```
+    tls-config tls-common {
+        ...
+        cipher_list = "DEFAULT@SECLEVEL=1"
+        ...
+    }
+```
+This situation arises if the server's system default for `SECLEVEL` is higher.
+
+For strong security we recommend setting `tls_min_version` to `1.2` or `1.3`.However this setting might prevent end devices on older operating systems from connecting.
+
+
+=== Different certificates for different EAP methods
+
+If different certificates are required for different EAP methods then create
+additional `tls-config` sections with distinct names. Reference the
+corresponding `tls-config` section in the configuration section for each EAP
+method
+
+Example 'tls-config' section
+```
+
+    tls-config eap-peap-tls-config {
+        ...
+        private_key_file = ${certdir}/server-peap.key
+        certificate_file = ${certdir}/server-peap.pem
+        ...
+    }
+
+    peap {
+       ...
+       tls = eap-peap-tls-config
+       ...
+    }
+```
+
+Add the new certificate and key to the servers.

doc/antora/modules/ROOT/pages/trouble-shooting/eap_certificates.adoc

@@ -56,6 +56,15 @@
 **** xref:modules/sqlippool/populating.adoc[Generating IPs]
 **** xref:modules/sqlippool/insert.adoc[Inserting IPs into SQL]
 
+** xref:datastores/index.adoc[Setting up Datastores]
+*** xref:datastores/ad/index.adoc[Active Directory]
+**** xref:datastores/ad/samba.adoc[Using Samba]
+**** xref:datastores/ad/ntlm_mschap.adoc[Configuring ntlm]
+**** xref:datastores/ad/winbind.adoc[Installing Winbind]
+*** xref:datastores/ldap.adoc[LDAP]
+*** xref:datastores/redis.adoc[Redis]
+*** xref:datastores/sql.adoc[SQL]
+
 ** xref:protocols/index.adoc[Protocols]
 *** xref:protocols/dhcp/index.adoc[DHCP]
 **** xref:protocols/dhcp/prepare.adoc[Preparation]
@@ -78,10 +87,15 @@
 *** xref:vendors/cisco.adoc[Cisco]
 *** xref:vendors/proxim.adoc[ProxIM]
 
-** Optimization
+** xref:monitoring/optimize.adoc[Optimization]
 *** xref:monitoring/index.adoc[Monitoring]
+**** xref:monitoring/logging_examples.adoc[Log Examples]
 **** xref:monitoring/statistics.adoc[Server Statistics]
 *** xref:tuning/performance-testing.adoc[Performance Testing]
+*** xref:monitoring/tools/index.adoc[Tools]
+**** xref:monitoring/tools/radclient_tool.adoc[Radclient]
+**** xref:monitoring/tools/radsniff_tool.adoc[Radsniff]
+**** xref:monitoring/tools/radmin_tool.adoc[Radmin]
 *** xref:tuning/tuning_guide.adoc[Tuning Guide]
 
 

doc/antora/modules/howto/nav.adoc

@@ -0,0 +1,103 @@
+= Active Directory (AD)
+
+Microsoft Active Directory (AD) is a directory service that stores and manages user accounts, credentials, and other network resources within a domain. The AD server receives and processes access requests from the FreeRADIUS server. AD provides a centralized location for managing authentications and access by:
+
+The services manage network activities by:
+
+* authenticating users by verifying their identity and credentials, and
+* authorizating resource use by applying policies to restrict access to data.
+
+== What is it?
+
+When FreeRADIUS is integrated with Active Directory, the AD server functions as an “authentication oracle.” FreeRADIUS doesn’t store user credentials internally, but instead, passes these credentials to AD for verification.
+
+For MS-CHAP based authentications, FreeRADIUS uses tools such as Samba, including winbind and the `ntlm_auth` helper program to communicate with the AD server. 
+
+=== FreeRADIUS Active Directory Authentication Process
+
+The authentication process flow of steps to authenticate a user is as follows:
+
+. FreeRADIUS receives a set user credentials requesting access to a network resource or service, and forwards this information to the Active Directory service via Samba.
+. AD verifies the submitted user's credentials such as name and password, against the stored credentials in the datastore.
+. AD determines the access level for the verified user and passes the authorization result back to FreeRADIUS via Samba.
+. FreeRADIUS grants access to the user according to the information received from AD i.e. user's rights and permissions to access a network resource.
+
+
+== How to connect
+
+For the following example, the FreeRADIUS server is installed and operational with basic authentication working (pap/chap). The FreeRADIUS server must also have Samba installed to be able to join the domain (or samba realm).
+
+*Join the FreeRADIUS server to AD with `net ads join` command:*
+
+`sudo /opt/samba4.x/bin/net ads join -U Administrator`
+
+Enter the administrator password at the prompt.
+
+*Add the following line to the [global] section of the `smb.conf` file:*
+
+`ntlm auth = mschapv2-and-ntlmv2-only`
+
+This setting allows for MS-CHAPv2 authentications against the AD using the ntlm authorization process.
+
+*Configure Freeradius to use mschapv2 with ntlmv1 disabled globally by setting this in /mods-available/mschap:*
+
+
+```
+mschap {
+
+.....
+
+ntlm_auth = "/path/to/ntlm_auth --allow-mschapv2 --request-nt-key
+--username=%{mschap:User-Name} --domain=WINDOWSDOMAIN
+--challenge=%{%{mschap:Challenge}:-00}
+--nt-response=%{%{mschap:NT-Response}:-00}"
+```
+
+This configuration works without modification to Freeradius.
+
+OR use winbind
+
+```
+winbind_username = "%{mschap:User-Name}"
+winbind_domain = "%{mschap:NT-Domain}"}
+.....
+```
+
+
+This configuration requires Freeradius to be built with winbind auth. For example, on linux-based systems, you rebuild the packages and add the winbind libraries to the ./configure path. See xref:datastores/ad/winbind.adoc[Installing winbind] for more details.
+
+=== Testing
+
+If everything works successfully, you'll see an entry in the AD Domain Controller's audit log similar to the snippit below:
+
+
+```
+{"timestamp": "some-date0", "type": "Authentication", "Authentication":
+{"version": {"major": 1, "minor": 0}, "status": "NT_STATUS_OK",
+"localAddress": "ipv4:xxx.xxx.xxx.xxx", "remoteAddress":
+"ipv4:xxx.xxx.xxx.xxx:58046", "serviceDescription": "SamLogon",
+"authDescription": "network", "clientDomain": "WINDOWSDOMAIN",
+"clientAccount": "some-user", "workstation": "\\\\SOME-HOST",
+"becameAccount": "some-user", "becameDomain": "WINDOWSDOMAIN",
+"becameSid": "SOME-SID", "mappedAccount": "some-user", "mappedDomain":
+"WINDOWSDOMAIN", "netlogonComputer": "SOME-HOST",
+"netlogonTrustAccount": "SOME-HOST$", "netlogonNegotiateFlags":
+"0x610FFFFF", "netlogonSecureChannelType": 2, "netlogonTrustAccountSid":
+"somesid, *"passwordType": "MSCHAPv2"*}}
+```
+
+Without the "--allow-mschapv2" setting, you would see "passwordType":"NTLMv1"
+
+== Why use Active Directory?
+
+When FreeRADIUS is integrated with Active Directory, only authorized users gain access to network resources, enhancing the overall security of your network. Active Directory functions as a centralized datastore for user accounts and security policies, simplifying user management and access rights across the network. By integrating with AD, FreeRADIUS can leverage the exisiting infrastructure and be scaled up for larger systems.
+
+== xref:datastores/ad/samba.adoc[Using Samba]
+
+FreeRADIUS uses Samba to integrate with Active Directory for authentication.  For authorization such as group membership, FreeRADIUS can query Active Directory over LDAP.
+
+For the next steps, see the following:
+
+* xref:datastores/ad/samba.adoc[Using Samba]
+* xref:datastores/ad/ntlm_mschap.adoc[Configuring ntlm]
+* xref:datastores/ad/winbind.adoc[Installing winbind]