8.6. Configuring PAM and consolehelper

Fedora uses the Pluggable Authentication Module (PAM) system to handle user authentication and identity changes. As the name implies, PAM is modular and configurable, enabling you to change the authentication (and authorization) setup on your system without programming.

8.6.1. How Do I Do That?

PAM configuration files are stored in /etc/pam.d, with one file per configured service. Each file is written in plain text and consists of at least three fields separated by spaces. The entries in these files are divided into four categories according to the first field, which identifies the module type. Possible values are:

auth

Authentication configuration (determining who is logging in).

account

Non-authentication-based access control, such as restricting activities by time of day.

password

Password changes or other authentication token updates (such as recording a new retinal scan or fingerprint).

session

Setup of the post-login session and environment.

The entries for a given module type are executed in sequence. For example, when performing authentication, the modules listed on the auth lines are executed in sequence.

The second field in each entry is called the control flag and determines the action taken when the module succeeds or fails. Possible values are:

required

The module must succeed for the module type to succeed. Regardless of whether the module fails or succeeds, processing will continue with the next line (other modules of the same module type will be executed), but at the end of all of the processing, a failure will be recorded.

requisite

The module must succeed for the module type to succeed. If it fails, processing stops immediately. If it succeeds, processing continues with the next line.

sufficient

If the module succeeds, then the module type succeeds and processing stops immediately. If it fails, processing continues with the next line.

optional

The module is executed, but the failure or success of the module is ignored.

include

In place of a module name, another configuration file is given. All of the lines of the same type from that configuration file are treated as if they were present in this configuration file.

It is also possible to use a complex expression as a control flag, but this feature is not used in the default Fedora Core configuration.

The remaining fields on the line contain the name of the module and any arguments to it (except when the control flag is include, in which case the third argument is the included file).

Here's an example. This is the content of /etc/pam.d/sshd, the configuration file for the SSH server daemon:

#%PAM-1.0
auth       include      system-auth
account    include      system-auth
password   include      system-auth
session    include      system-auth
session    required     pam_loginuid.so

Authentication is carried out by the first line, which includes all of the auth lines from the file /etc/pam.d/system-auth, which looks like this:

#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth        required      pam_env.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        required      pam_deny.so

account     required      pam_unix.so
account     sufficient    pam_succeed_if.so uid < 500 quiet
account     required      pam_permit.so

password    requisite     pam_cracklib.so try_first_pass retry=3
password    sufficient    pam_unix.so md5 shadow nullok try_first_pass use_authtok
password    required      pam_deny.so

session     required      pam_limits.so
session     required      pam_unix.so

The first line highlighted in bold executes the pam_env.so module (/lib/security/pam_env.so), which sets up environment variables according to the configuration file /etc/security/pam_env.conf. The next lines use the pam_unix.so module to perform traditional Unix password checking, then deny access if the password check does not succeed.

In this configuration, the pam_succeed_if.so lines do nothing! (They are used when a network authentication scheme is in effect, though.)

These are the account entries, as included into the sshd configuration file from the system-auth file:

account     required      pam_nologin.so
account     required      pam_unix.so
account     sufficient    pam_succeed_if.so uid < 500 quiet
account     required      pam_permit.so

The pam_nologin.so module checks for the existence of the file /etc/nologin and, if present, prevents anyone except root from logging in. This is useful during periods of system maintenance.

The contents of /etc/nologin will be displayed as a message to the user in a dialog box when he attempts to log in using the graphical user interface. In the case of a character-mode login, the file will be displayed but the screen will be cleared immediately, making it nearly impossible to read the message. The SSH daemon will not display the message at all.

The pam_unix.so module (in this account mode) performs password maintenance checking, to see if the user should be forced to change her password, warned of imminent expiry, or locked out of the system. Finally, the pam_permit.so module sets up a default action of permit for the account section of the file.

The password portion of the configuration controls password changes:

password    requisite     pam_cracklib.so try_first_pass retry=3
password    sufficient    pam_unix.so md5 shadow nullok try_first_pass use_authtok
password    required      pam_deny.so

The first line executes pam_cracklib.so to ensure that any newly set password is sufficiently complex, and the second line updates the password files on the system. The last line ensures that a failure is recorded if the password update is not successful.

Finally, we have the session entries, which set up the environment and perform logging after the user has authenticated:

session     required      pam_limits.so
session     required      pam_unix.so
session     required      pam_loginuid.so

The first two lines are included from /etc/pam.d/system-auth, while the last line is from /etc/pam.d/sshd.

The pam_limits.so module can be used to configure ulimit values according to /etc/security/limits.conf, but the default version of that file contains only comments. You can use this module to limit the amount of memory, CPU time, simultaneous logins, or other resources available to specific users.

The pam_unix.so module (in session mode) simply logs the fact that the user has authenticated using the syslog facility. The last module, pam_loginuid.so, records the fact that this is an initial login (as opposed to a switch of user ID performed using su or sudo).

8.6.1.1. Using an authentication server

Fedora can authenticate against an authentication server instead of (or in addition to) the local user and password database (/etc/passwd, /etc/shadow, /etc/group, and /etc/gshadow). Usable authentication and user information services include Kerberos, LDAP, Hesiod (DNS), Winbind (local Windows domain), and SMB (Windows domain server).

To use an established authentication server, select the desktop menu option SystemAdministrationAuthentication or run the command system-config-authentication. The window shown in Figure 8-9 will appear. Select the User Information or Authentication tab, and then select the checkbox for the server type you wish to use. Click the Configure button to the right of the server type to enter the parameters specifically required by that server type (for example, for NIS you will need to enter the NIS domain and the server name).

Click OK. system-config-authentication will then write a new version of the file /etc/pam.d/system-auth.

Figure 8-9. Authentication Configuration window

Using the Authentication Configuration tool will undo any customization that you have made in /etc/pam.d/system-auth.

Authentication can also be configured from the command line using authconfig.

8.6.1.2. Adding a PAM module: restricting access by time and user

We can tighten up the security of the system by adding additional modules into the configuration file. For example, you can restrict SSH access to certain times of day using the pam_time.so module.

Before editing any PAM configuration file, make a backup copy. You should also keep a root shell open in a virtual terminal or terminal window in case your changes accidentally lock you out of the system. Test the new configuration thoroughly before closing the root shell!

Edit /etc/pam.d/sshd to add pam_time.so in the account section:

#%PAM-1.0
auth       include      system-auth
account    required     pam_time.so
account    include      system-auth
password   include      system-auth
session    include      system-auth
session    required     pam_loginuid.so

Notice that the sequence of the lines is critical; if you place the pam_time.so line after the file system-auth is included, it will be ignored for users with IDs less than 500 (such as root) due to the pam_succeed_if.so line in system-auth.

The pam_time.so module restricts access based on the contents of the file /etc/security/time.conf, which is a text file with four semicolon-delimited fields per line. The fields are:

service

Must match the name of the service file in /etc/pam.d (sshd in this example).

tty

Terminal device names (not useful in this context, so we'll use * to match all terminals).

users

A list of usernames, combined using ! (not), & (and), or | (or).

times

A list of days (any combination of Su, Mo, Tu, We, Th, Fr, or Saor Wk for weekdays, Wd for weekends, or Al for all days) concatenated to a range of times, expressed in 24-hour format (such as 0600-1800 for 6 a.m. to 6 p.m., local time).

The default /etc/security/time.conf contains extensive notes on the line format.

To prevent all users other than root from connecting via SSH during evenings and weekends, place these lines in /etc/security/time.conf:

# Limit ssh for non-root users to 8 am to 5 pm on weekdays
sshd;*;!root;Wk0800-1700

Note that if there is no line in /etc/security/time.conf that applies to a particular connection, it is permitted by default. These restrictions also apply only when a user logs in; once logged in, the user may stay connected for as long as he chooses.

To place a time restriction on all types of loginwhether through SSH, a local character-mode virtual terminal, or the GUIplace the entry for the pam_time.so module in /etc/pam.d/system-auth instead of /etc/pam.d/sshd:

#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth        required      pam_env.so
auth        sufficient    pam_unix.so nullok try_first_pass
auth        requisite     pam_succeed_if.so uid >= 500 quiet
auth        required      pam_deny.so

account     required      pam_time.so
account     required      pam_unix.so
account     sufficient    pam_succeed_if.so uid < 500 quiet
account     required      pam_permit.so

password    requisite     pam_cracklib.so try_first_pass retry=3
password    sufficient    pam_unix.so md5 shadow nullok try_first_pass use_authtok
password    required      pam_deny.so

session     required      pam_limits.so
session     required      pam_unix.so

You can then create separate rules for each type of user access in /etc/security/time.conf:

# Character-mode login - Only root is permitted (any time).
login;*;!root;!Al0000-2400

# Remote login via ssh - Root is always permitted, other 
# users are permitted 8 am to 5 pm on weekdays.
sshd;*;!root;Wk0800-1700

# Graphical-mode login - Not available to root.
gdm;*;root;!Al0000-2400

# Switching user via 'su' command - not permitted unless 
# switching -to- the root user. Note that the root user
# can switch to any other user because of the pam_rootok.so
# module line in /etc/pam.d/su
su;*;!root;!Al0000-2400

8.6.1.3. Automatic blacklisting of sites trying a brute-force password attack

The PAM module pam_abl.so from Fedora Extras provides the ability to blacklist (block access from) users and hosts that repeatedly send an incorrect password. This is useful in guarding against brute-force password attacks, where a remote system will simply try to log in over and over again with different password guesses until it is successful.

This module will not work successfully with gdm (graphical logins), so it must not be added to system-auth. To protect SSH logins (the best use of this module), add an entry for pam_abl.so module to /etc/pam.d/sshd:

#%PAM-1.0
auth       required     pam_abl.so config=/etc/security/pam_abl.conf
auth       include      system-auth
account    include      system-auth
password   include      system-auth
session    include      system-auth
session    required     pam_loginuid.so

The file /etc/security/pam_abl.conf is installed by the pam_abl RPM and contains this configuration:

# /etc/security/pam_abl.conf
# debug
host_db=/var/lib/abl/hosts.db
host_purge=2d
host_rule=*:10/1h,30/1d
user_db=/var/lib/abl/users.db
user_purge=2d
user_rule=!root:10/1h,30/1d

The host_rule line controls which hosts may be blacklisted and the number of failed login attempts that must be registered before blacklisting; the default configuration specifies that any host (*) may be blacklisted for more than 10 login failures in one hour (10/1h), or more than 30 login failures in one day (30/1d). The user_rule line similarly blacklists any user except root (!root) who has 10 failed login attempts in one hour or 30 failed login attempts in one day.

The host_purge and user_purge lines configure how quickly a blacklist entry is revoked; the default for both is two days.

When a login failure is recorded, the pam_abl.so module updates its database. You can query the database using the pam_abl command:

# pam_abl
Failed users:
   <none>
Failed hosts:
   <none>

Initially, no failed login attempts are recorded. As login failures occur, pam_abl will count and report them (in parenthesis):

# pam_abl
Failed users:
    jane (1)
        Not blocking
Failed hosts:
    darkday (1)
        Not blocking

Eventually, access from the host or user will be blocked:

# pam_abl
Failed users:
    jane (11)
        Blocking users [!root]
Failed hosts:
    darkday (11)
        Blocking users [*]

To re-enable access from a specific host or by a specific user, use the --okhost or --okuser arguments to pam_abl:

# pam_abl --okhost darkday
# pam_abl
Failed users:
    jane (11)
        Blocking users [!root]
Failed hosts:
   <none>

8.6.1.4. PAM and consolehelper

Fedora uses the consolehelper program to control access to a number of system administration tools. It's consolehelper that asks you for the root password when you use many of the configuration menu options such as SystemAdministrationNetwork (or, equivalently, run system-config-network from the shell).

If you examine the system-config-network file, you'll see that it is actually a symbolic link to consolehelper:

$ type system-config-network
system-config-network is /usr/bin/system-config-network
$ ls -l /usr/bin/system-config-network
lrwxrwxrwx 1 root root 13 Mar 20 14:57 /usr/bin/system-config-network
         -> consolehelper

When consolehelper is invoked with another command name, it uses the PAM configuration in /etc/pam.d with the same name as the command entered. If the user runs system-config-network, then the PAM configuration /etc/pam.d/system-config-network is invoked, which looks like this:

#%PAM-1.0
auth            include         config-util
account         include         config-util
session         include         config-util

This includes /etc/pam.d/config-util, which contains these lines:

#%PAM-1.0
auth            sufficient      pam_rootok.so
auth            sufficient      pam_timestamp.so
auth            include         system-auth
account         required        pam_permit.so
session         required        pam_permit.so
session         optional        pam_xauth.so
session         optional        pam_timestamp.so

The auth configuration will succeed if the current user is root (pam_rootok.so) or there is a recent timestamp file present (pam_timestamp.so). Failing that, the traditional Unix password authentication is performed (via the included system-auth file).

The timestamp file that pam_timestamp.so checks is created by the last line, which invokes the pam_timestamp.so module in session mode. In other words, if the user successfully authenticates to the system as root in order to use one tool, she is permitted to run other tools without typing in her password for the next few minutes.

Once the authentication has succeeded, consolehelper consults the file with the same name as the originally entered command in the directory /etc/security/console.apps; in this example, the file would be /etc/security/console.apps/system-config-network, which contains:

USER=root
PROGRAM=/usr/sbin/system-config-network
SESSION=true

This instructs consolehelper to run /usr/sbin/system-config-network as the root user after performing the PAM session initialization (using the session lines in the PAM configuration file).

You can adjust the PAM configuration to suit your needs. For example, to allow regular users to run system-config-network without entering the root password, edit the auth line in /etc/pam.d/system-config-network to use the permissive pam_permit.so module instead of including the config-util file:

#%PAM-1.0
auth            sufficient      pam_permit.so
account         include         config-util
session         include         config-util

It's often convenient to enable the console userthe person physically logged on to the system keyboard and displayto run any of the programs controlled by consolehelper without entering the root password. To do this, edit /etc/pam.d/config-util and add this line:

#%PAM-1.0
auth            sufficient      pam_rootok.so
auth            sufficient      pam_timestamp.so
auth            sufficient      pam_console.so
auth            include         system-auth
account         required        pam_permit.so
session         required        pam_permit.so
session         optional        pam_xauth.so
session         optional        pam_timestamp.so

This will permit the current console owner to execute the configuration tools regardless of where he is executing them. For example, if the user joe is logged in on the console (either graphically or using a character-mode login), then joe can execute configuration tools both at the console and through a remote connection.

8.6.2. How Does It Work?

PAM is simply a group of libraries used by applications. Each PAM-aware application uses those libraries to perform authentication, account control, the management of passwords (or other tokens), and session setup.

Each PAM module is a shared object (.so) file conforming to the PAM specification. These files are stored in /lib/security and are accessed when needed according to the configuration files in /etc/pam.d.

8.6.3. What About...

8.6.3.1. ...other PAM modules?

There are many PAM modules included in Fedora Core. For documentation, refer to the PAM Administrator's manual in /usr/share/doc/pam-*/html/. Some PAM modules not documented in that manual have their own manpages; use apropos pam_ to see a list of all of them.

There are also a number of PAM modules available on the Internet and from hardware vendors, designed to support authentication using biometric devices, smart tokens, and more.

8.6.3.2. ...permitting the console user to use su without a password?

Edit /etc/pam.d/su to add this line:

#%PAM-1.0
auth            sufficient      pam_rootok.so
# Uncomment the following line to implicitly trust users in the "wheel" group.
#auth           sufficient      pam_wheel.so trust use_uid
# Uncomment the following line to require a user to be in the "wheel" group.
#auth           required        pam_wheel.so use_uid
auth            sufficient      pam_console.so
auth            include         system-auth
account         include         system-auth
password        include         system-auth
session         include         system-auth
session         optional        pam_xauth.so

Then create the file /etc/security/console.apps/su:

# touch /etc/security/console.apps/su
               

You can now use su at the console without entering the root password.

This is, obviously, a security risk.

8.6.4. Where Can I Learn More?

• The manpages for pam, consolehelper, userhelper, and authconfig

• The PAM administrator's guide: /usr/share/doc/pam*/html

• The manpages for the PAM modules (use the command apropos pam_ to see a list of all of them); not all of the PAM modules have a manpage