Configuring the CHAP module

The mods-available/chap configuration file describes the configuration parameters accepted by the CHAP module, and what they do. This document explains how to perform testing with the CHAP module.

The default server configuration should be tested via the following command:

radiusd -XC

If the configuration is correct, then the server will print the following message:

Configuration appears to be OK

If that message does not appear, then it is necessary to correct any and all errors before proceeding to the next step. It is a good idea to ensure that the current configuration works before making changes to it.

Editing mods-available/chap

The mods-available/chap module contains no configuration items, and does not need to be edited.

Enabling mods-available/chap

The chap module is enabled by creating a soft link from the mods-enabled/ directory to the mods-available/ directory.

cd raddb/mods-enabled && ln -s ../mods-available/chap

The default installation will automatically enable the chap module. In most circumstances, no additional work is required.

Testing the Server

After configuring the module, the server should be tested again via the following command:

radiusd -XC

When the configuration is correct, then the server will print the following message:

Configuration appears to be OK

Note that this test checks only that the configuration files can be parsed. It does not check that the module works correctly when packets are received.

When the configuration is correct, FreeRADIUS can then be started in debugging mode:

radiusd -X

If the module has been configured correctly, the final (or almost final) message will be

Ready to process requests

This message should be in bold on the console. Depending on which other modules are enabled, there may be a small number messages after this one.

If the server starts, then the next step is then to perform run-time tests.

Errors

If the Ready to process requests message does not appear, then the debug output will contain error messages clearly describing what went wrong. These error message must be read in order to gain insight as to the source of the problem.

Otherwise, look for messages containing ERROR or WARNING, or the module name. While the server can produce a large volume of messages, most of those can be ignored when debugging a particular problem. Simply search for a few key strings based on the files you changed, and the solution to the problem should be clear.

We recommend running the radiusd -XC test was performed before making any module changes for other reasons. If previous configuration worked, and the only change was to a particular module, then the source of the error is simple. There is no need to go searching through other configuration files or third-party web sites. Instead, change and test the module configuration until the server works.

Testing CHAP Authentication

Once the server is started in debugging mode, CHAP authentication can be performed via the following command:

cat <<'EOF' | radclient -x localhost auth testing123
User-Name = "bob"
CHAP-Password = "hello"
EOF

The radclient program is smart enough to see that the CHAP-Password attribute is a cleartext password. It then performs CHAP calculations in order to put the correct CHAP-Password value into the packet.

The server must be configured with a known user and a "known good" password before any CHAP tests are performed. In this case, we assume that the server knows about a user bob with password hello.

The output of radclient should look like the following. Some of the numbers may be different, but the general format should be the same.

Sent Access-Request Id 47 from 0.0.0.0:52132 to 127.0.0.1:1812 length 44
	User-Name = "bob"
	CHAP-Password = 0x70170db9ab2baad7ca45b3ef9cd844eccd
	Password.Cleartext = "bob"
Received Access-Accept Id 47 from 127.0.0.1:1812 to 127.0.0.1:52132 length 25
	User-Name = "bob"

This output indicates that the authentication request was accepted.

Next, read the server output. The goal here is to look for messages containing ERROR or WARNING, or the chap module name.

(0)  Received Access-Request ID 18 from 127.0.0.1:53623 to 127.0.0.1:1812 length 44 via socket proto_radius_udp server * port 1812
(0)    User-Name = "bob"
(0)    CHAP-Password = 0x3549a4e40fc76e876499badf736712c951
...
(0)    chap - Creating &CHAP-Challenge from request authenticator
(0)    chap - Setting &control.Auth-Type = chap
(0)    chap (ok)
...
(0)  Found "known good" password in &control.Password.Cleartext
(0)  Running 'authenticate chap' from file ./raddb/sites-enabled/default
(0)  authenticate chap {
(0)    chap - Comparing with "known good" Password.Cleartext
(0)    chap - CHAP user "bob" authenticated successfully
(0)    chap (ok)
(0)  } # authenticate chap (ok)
...
(0)  Sending Access-Accept ID 18 from 127.0.0.1:1812 to 127.0.0.1:53623 length 25 via socket proto_radius_udp server * port 1812
(0)    User-Name = "bob"
...

For the purposes of this test, the other messages in the debug output can be ignored.

In the above output, the chap module is first run in the recv Access-Request { … } section. The module looks for CHAP-Password in the request packet, and if found, sets Auth-Type := CHAP. That setting tells the server core to call the chap module again for authentication.

Once the recv Access-Request { … } section has finished processing, the server calls the authenticate chap { … } section. In the default configuration, that section contains just a reference to the chap module. The chap module finds a Password.Cleartext which has previously been added to the request, and performs the CHAP calculations. If the calculated CHAP values match the CHAP values in the request packet, then the user is authenticated. Otherwise, authentication fails and the user is rejected.

This two-phase processing of CHAP ensures that the chap module is independent of any database. That is, the "known good" password can be obtained from any other module, such as ldap, sql, files, etc. The chap module only needs to know that it handles CHAP, and that it has been given a Password.Cleartext in order to authenticate the user. The source of that Password.Cleartext is unimportant.

Disabling CHAP

The local system requirements may be that CHAP authentication is forbidden. In that case, the chap module should be removed from the recv Access-Request { … } section, and the authenticate chap { … } section should be deleted. The server will then be unable to process CHAP authentication requests. All Access-Request packets that contain a CHAP-Password attribute will then result in an Access-Reject.