Chapter 17. Setting up an 802.1x network authentication service for LAN clients by using hostapd with FreeRADIUS backend

Procedure

1. Create the bridge interface:

   # nmcli connection add type bridge con-name br0 ifname br0

2. Assign the Ethernet interfaces to the bridge:

   # nmcli connection add type ethernet slave-type bridge con-name br0-port1 ifname enp1s0 master br0
   # nmcli connection add type ethernet slave-type bridge con-name br0-port2 ifname enp7s0 master br0
   # nmcli connection add type ethernet slave-type bridge con-name br0-port3 ifname enp8s0 master br0
   # nmcli connection add type ethernet slave-type bridge con-name br0-port4 ifname enp9s0 master br0

3. Enable the bridge to forward extensible authentication protocol over LAN (EAPOL) packets:

   # nmcli connection modify br0 group-forward-mask 8

4. Configure the connection to automatically activate the ports:

   # nmcli connection modify br0 connection.autoconnect-slaves 1

5. Activate the connection:

   # nmcli connection up br0

Verification

1. Display the link status of Ethernet devices that are ports of a specific bridge:

   # ip link show master br0
   3: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel master br0 state UP mode DEFAULT group default qlen 1000
       link/ether 52:54:00:62:61:0e brd ff:ff:ff:ff:ff:ff
   ...

2. Verify if forwarding of EAPOL packets is enabled on the br0 device:

   # cat /sys/class/net/br0/bridge/group_fwd_mask
   0x8

   If the command returns 0x8, forwarding is enabled.

Procedure

1. Change into the /etc/raddb/certs/ directory:

   # cd /etc/raddb/certs/

2. Optional: Customize the CA configuration in the /etc/raddb/certs/ca.cnf file:

   ...
   [ req ]
   default_bits            = 2048
   input_password          = ca_password
   output_password         = ca_password
   ...
   [certificate_authority]
   countryName             = US
   stateOrProvinceName     = North Carolina
   localityName            = Raleigh
   organizationName        = Example Inc.
   emailAddress            = admin@example.org
   commonName              = "Example Certificate Authority"
   ...

3. Optional: Customize the server configuration in the /etc/raddb/certs/server.cnf file::

   ...
   [ CA_default ]
   default_days            = 730
   ...
   [ req ]
   distinguished_name      = server
   default_bits            = 2048
   input_password          = key_password
   output_password         = key_password
   ...
   [server]
   countryName             = US
   stateOrProvinceName     = North Carolina
   localityName            = Raleigh
   organizationName        = Example Inc.
   emailAddress            = admin@example.org
   commonName              = "Example Server Certificate"
   ...

4. Optional: Customize the client configuration in the /etc/raddb/certs/client.cnf file::

   ...
   [ CA_default ]
   default_days            = 365
   ...
   [ req ]
   distinguished_name      = client
   default_bits            = 2048
   input_password          = password_on_private_key
   output_password         = password_on_private_key
   ...
   [client]
   countryName             = US
   stateOrProvinceName     = North Carolina
   localityName            = Raleigh
   organizationName        = Example Inc.
   emailAddress            = user@example.org
   commonName              = user@example.org
   ...

5. Create the certificates:

   # make all

6. Change the group on the /etc/raddb/certs/server.pem file to radiusd:

   # chgrp radiusd /etc/raddb/certs/server.pem

Procedure

1. If the /etc/raddb/certs/dh with Diffie-Hellman (DH) parameters does not exist, create one. For example, to create a DH file with a 2048 bits prime, enter:

   # openssl dhparam -out /etc/raddb/certs/dh 2048

   For security reasons, do not use a DH file with less than a 2048 bits prime. Depending on the number of bits, the creation of the file can take several minutes.

2. Set secure permissions on the TLS private key, server certificate, CA certificate, and the file with DH parameters:

   # chmod 640 /etc/raddb/certs/server.key /etc/raddb/certs/server.pem /etc/raddb/certs/ca.pem /etc/raddb/certs/dh
   # chown root:radiusd /etc/raddb/certs/server.key /etc/raddb/certs/server.pem /etc/raddb/certs/ca.pem /etc/raddb/certs/dh

3. Edit the /etc/raddb/mods-available/eap file:

   1. Set the password of the private key in the private_key_password parameter:

      eap {
          ...
          tls-config tls-common {
              ...
              private_key_password = key_password
              ...
          }
      }

   2. Depending on your environment, set the default_eap_type parameter in the eap directive to your primary EAP type you use:

      eap {
          ...
          default_eap_type = ttls
          ...
      }

      For a secure environment, use only ttls, tls, or peap.

   3. Comment out the md5 directives to disable the insecure EAP-MD5 authentication method:

      eap {
          ...
          # md5 {
          # }
          ...
      }

      Note that, in the default configuration file, other insecure EAP authentication methods are commented out by default.

4. Edit the /etc/raddb/sites-available/default file, and comment out all authentication methods other than eap:

   authenticate {
       ...
       # Auth-Type PAP {
       #     pap
       # }
   
       # Auth-Type CHAP {
       #     chap
       # }
   
       # Auth-Type MS-CHAP {
       #     mschap
       # }
   
       # mschap
   
       # digest
       ...
   }

   This leaves only EAP enabled and disables plain-text authentication methods.

5. Edit the /etc/raddb/clients.conf file:

   1. Set a secure password in the localhost and localhost_ipv6 client directives:

      client localhost {
          ipaddr = 127.0.0.1
          ...
          secret = client_password
          ...
      }
      
      client localhost_ipv6 {
          ipv6addr = ::1
          secret = client_password
      }

   2. If RADIUS clients, such as network authenticators, on remote hosts should be able to access the FreeRADIUS service, add corresponding client directives for them:

      client hostapd.example.org {
          ipaddr = 192.0.2.2/32
          secret = client_password
      }

      The ipaddr parameter accepts IPv4 and IPv6 addresses, and you can use the optional classless inter-domain routing (CIDR) notation to specify ranges. However, you can set only one value in this parameter. For example, to grant access to an IPv4 and IPv6 address, add two client directives.

      Use a descriptive name for the client directive, such as a hostname or a word that describes where the IP range is used.

6. If you want to use EAP-TTLS or EAP-PEAP, add the users to the /etc/raddb/users file:

   example_user        Cleartext-Password := "user_password"

   For users who should use certificate-based authentication (EAP-TLS), do not add any entry.

7. Verify the configuration files:

   # radiusd -XC
   ...
   Configuration appears to be OK

8. Enable and start the radiusd service:

   # systemctl enable --now radiusd

Troubleshooting

1. Stop the radiusd service:

   # systemctl stop radiusd

2. Start the service in debug mode:

   # radiusd -X
   ...
   Ready to process requests

3. Perform authentication tests on the FreeRADIUS host, as referenced in the Verification section.

Procedure

1. Create the /etc/hostapd/hostapd.conf file with the following content:

   # General settings of hostapd
   # ===========================
   
   # Control interface settings
   ctrl_interface=/var/run/hostapd
   ctrl_interface_group=wheel
   
   # Enable logging for all modules
   logger_syslog=-1
   logger_stdout=-1
   
   # Log level
   logger_syslog_level=2
   logger_stdout_level=2
   
   
   # Wired 802.1X authentication
   # ===========================
   
   # Driver interface type
   driver=wired
   
   # Enable IEEE 802.1X authorization
   ieee8021x=1
   
   # Use port access entry (PAE) group address
   # (01:80:c2:00:00:03) when sending EAPOL frames
   use_pae_group_addr=1
   
   
   # Network interface for authentication requests
   interface=br0
   
   
   # RADIUS client configuration
   # ===========================
   
   # Local IP address used as NAS-IP-Address
   own_ip_addr=192.0.2.2
   
   # Unique NAS-Identifier within scope of RADIUS server
   nas_identifier=hostapd.example.org
   
   # RADIUS authentication server
   auth_server_addr=192.0.2.1
   auth_server_port=1812
   auth_server_shared_secret=client_password
   
   # RADIUS accounting server
   acct_server_addr=192.0.2.1
   acct_server_port=1813
   acct_server_shared_secret=client_password

   For further details about the parameters used in this configuration, see their descriptions in the /usr/share/doc/hostapd/hostapd.conf example configuration file.

2. Enable and start the hostapd service:

   # systemctl enable --now hostapd

Troubleshooting

1. Stop the hostapd service:

   # systemctl stop hostapd

2. Start the service in debug mode:

   # hostapd -d /etc/hostapd/hostapd.conf

3. Perform authentication tests on the FreeRADIUS host, as referenced in the Verification section.

Procedure

1. Create the /etc/wpa_supplicant/wpa_supplicant-TTLS.conf file with the following content:

   ap_scan=0
   
   network={
       eap=TTLS
       eapol_flags=0
       key_mgmt=IEEE8021X
   
       # Anonymous identity (sent in unencrypted phase 1)
       # Can be any string
       anonymous_identity="anonymous"
   
       # Inner authentication (sent in TLS-encrypted phase 2)
       phase2="auth=PAP"
       identity="example_user"
       password="user_password"
   
       # CA certificate to validate the RADIUS server's identity
       ca_cert="/etc/pki/tls/certs/ca.pem"
   }

2. To authenticate to:

   • A FreeRADIUS server, enter:

     # eapol_test -c /etc/wpa_supplicant/wpa_supplicant-TTLS.conf -a 192.0.2.1 -s client_password
     ...
     EAP: Status notification: remote certificate verification (param=success)
     ...
     CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
     ...
     SUCCESS

     The -a option defines the IP address of the FreeRADIUS server, and the -s option specifies the password for the host on which you run the command in the FreeRADIUS server’s client configuration.

   • An authenticator, enter:

     # wpa_supplicant -c /etc/wpa_supplicant/wpa_supplicant-TTLS.conf -D wired -i enp0s31f6
     ...
     enp0s31f6: CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
     ...

     The -i option specifies the network interface name on which wpa_supplicant sends out extended authentication protocol over LAN (EAPOL) packets.

     For more debugging information, pass the -d option to the command.

Procedure

1. Create the /etc/wpa_supplicant/wpa_supplicant-TLS.conf file with the following content:

   ap_scan=0
   
   network={
       eap=TLS
       eapol_flags=0
       key_mgmt=IEEE8021X
   
       identity="user@example.org"
       client_cert="/etc/pki/tls/certs/client.pem"
       private_key="/etc/pki/tls/private/client.key"
       private_key_passwd="password_on_private_key"
   
       # CA certificate to validate the RADIUS server's identity
       ca_cert="/etc/pki/tls/certs/ca.pem"
   }

2. To authenticate to:

   • A FreeRADIUS server, enter:

     # eapol_test -c /etc/wpa_supplicant/wpa_supplicant-TLS.conf -a 192.0.2.1 -s client_password
     ...
     EAP: Status notification: remote certificate verification (param=success)
     ...
     CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
     ...
     SUCCESS

     The -a option defines the IP address of the FreeRADIUS server, and the -s option specifies the password for the host on which you run the command in the FreeRADIUS server’s client configuration.

   • An authenticator, enter:

     # wpa_supplicant -c /etc/wpa_supplicant/wpa_supplicant-TLS.conf -D wired -i enp0s31f6
     ...
     enp0s31f6: CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully
     ...

     The -i option specifies the network interface name on which wpa_supplicant sends out extended authentication protocol over LAN (EAPOL) packets.

     For more debugging information, pass the -d option to the command.

Procedure

1. Create the /usr/local/bin/802-1x-tr-mgmt file with the following content:

   #!/bin/sh
   
   if [ "x$1" == "xblock_all" ]
   then
   
       nft delete table bridge tr-mgmt-br0 2>/dev/null || true
       nft -f - << EOF
   table bridge tr-mgmt-br0 {
           set allowed_macs {
                   type ether_addr
           }
   
           chain accesscontrol {
                   ether saddr @allowed_macs accept
                   ether daddr @allowed_macs accept
                   drop
           }
   
           chain forward {
                   type filter hook forward priority 0; policy accept;
                   meta ibrname "br0" jump accesscontrol
           }
   }
   EOF
       echo "802-1x-tr-mgmt Blocking all traffic through br0. Traffic for given host will be allowed after 802.1x authentication"
   
   elif [ "x$1" == "xallow_all" ]
   then
   
       nft delete table bridge tr-mgmt-br0
       echo "802-1x-tr-mgmt Allowed all forwarding again"
   
   fi
   
   case ${2:-NOTANEVENT} in
   
       AP-STA-CONNECTED | CTRL-EVENT-EAP-SUCCESS | CTRL-EVENT-EAP-SUCCESS2)
           nft add element bridge tr-mgmt-br0 allowed_macs { $3 }
           echo "$1: Allowed traffic from $3"
           ;;
   
       AP-STA-DISCONNECTED | CTRL-EVENT-EAP-FAILURE)
           nft delete element bridge tr-mgmt-br0 allowed_macs { $3 }
           echo "802-1x-tr-mgmt $1: Denied traffic from $3"
           ;;
   
   esac

2. Create the /etc/systemd/system/802-1x-tr-mgmt@.service systemd service file with the following content:

   [Unit]
   Description=Example 802.1x traffic management for hostapd
   After=hostapd.service
   After=sys-devices-virtual-net-%i.device
   
   [Service]
   Type=simple
   ExecStartPre=-/bin/sh -c '/usr/sbin/tc qdisc del dev %i ingress > /dev/null 2>&1'
   ExecStartPre=-/bin/sh -c '/usr/sbin/tc qdisc del dev %i clsact > /dev/null 2>&1'
   ExecStartPre=/usr/sbin/tc qdisc add dev %i clsact
   ExecStartPre=/usr/sbin/tc filter add dev %i ingress pref 10000 protocol 0x888e matchall action ok index 100
   ExecStartPre=/usr/sbin/tc filter add dev %i ingress pref 10001 protocol all matchall action drop index 101
   ExecStart=/usr/sbin/hostapd_cli -i %i -a /usr/local/bin/802-1x-tr-mgmt
   ExecStopPost=-/usr/sbin/tc qdisc del dev %i clsact
   
   [Install]
   WantedBy=multi-user.target

3. Reload systemd:

   # systemctl daemon-reload

4. Enable and start the 802-1x-tr-mgmt service with the interface name hostapd is listening on:

   # systemctl enable --now 802-1x-tr-mgmt@br0.service