42.4. Pluggable Authentication Modules (PAM)

42.4. Pluggable Authentication Modules (PAM)

Programs that grant users access to a system use authentication to verify each other's identity (that is, to establish that a user is who they say they are).

Historically, each program had its own way of authenticating users. In Red Hat Enterprise Linux, many programs are configured to use a centralized authentication mechanism called Pluggable Authentication Modules (PAM).

PAM uses a pluggable, modular architecture, which affords the system administrator a great deal of flexibility in setting authentication policies for the system.

In most situations, the default PAM configuration file for a PAM-aware application is sufficient. Sometimes, however, it is necessary to edit a PAM configuration file. Because misconfiguration of PAM can compromise system security, it is important to understand the structure of these files before making any modifications. Refer to Section 42.4.3, “PAM Configuration File Format” for more information.

42.4.1. Advantages of PAM

PAM offers the following advantages:

  • a common authentication scheme that can be used with a wide variety of applications.

  • significant flexibility and control over authentication for both system administrators and application developers.

  • a single, fully-documented library which allows developers to write programs without having to create their own authentication schemes.

42.4.2. PAM Configuration Files

The /etc/pam.d/ directory contains the PAM configuration files for each PAM-aware application. In earlier versions of PAM, the /etc/pam.conf file was used, but this file is now deprecated and is only used if the /etc/pam.d/ directory does not exist.

42.4.2.1. PAM Service Files

Each PAM-aware application or service has a file in the /etc/pam.d/ directory. Each file in this directory has the same name as the service to which it controls access.

The PAM-aware program is responsible for defining its service name and installing its own PAM configuration file in the /etc/pam.d/ directory. For example, the login program defines its service name as login and installs the /etc/pam.d/login PAM configuration file.

42.4.3. PAM Configuration File Format

Each PAM configuration file contains a group of directives formatted as follows:

<module interface>  <control flag>   <module name>   <module arguments>

Each of these elements is explained in the following sections.

42.4.3.1. Module Interface

Four types of PAM module interface are currently available. Each of these corresponds to a different aspect of the authorization process:

  • auth — This module interface authenticates use. For example, it requests and verifies the validity of a password. Modules with this interface can also set credentials, such as group memberships or Kerberos tickets.

  • account — This module interface verifies that access is allowed. For example, it may check if a user account has expired or if a user is allowed to log in at a particular time of day.

  • password — This module interface is used for changing user passwords.

  • session — This module interface configures and manages user sessions. Modules with this interface can also perform additional tasks that are needed to allow access, like mounting a user's home directory and making the user's mailbox available.

Note

An individual module can provide any or all module interfaces. For instance, pam_unix.so provides all four module interfaces.

In a PAM configuration file, the module interface is the first field defined. For example, a typical line in a configuration may look like this:

auth	required	pam_unix.so

This instructs PAM to use the pam_unix.so module's auth interface.

42.4.3.1.1. Stacking Module Interfaces

Module interface directives can be stacked, or placed upon one another, so that multiple modules are used together for one purpose. If a module's control flag uses the "sufficient" or "requisite" value (refer to Section 42.4.3.2, “Control Flag” for more information on these flags), then the order in which the modules are listed is important to the authentication process.

Stacking makes it easy for an administrator to require specific conditions to exist before allowing the user to authenticate. For example, the reboot command normally uses several stacked modules, as seen in its PAM configuration file:

[root@MyServer ~]# cat /etc/pam.d/reboot
#%PAM-1.0
auth	sufficient	pam_rootok.so
auth	required	pam_console.so
#auth	include	system-auth
account	required	pam_permit.so
  • The first line is a comment and is not processed.

  • auth sufficient pam_rootok.so — This line uses the pam_rootok.so module to check whether the current user is root, by verifying that their UID is 0. If this test succeeds, no other modules are consulted and the command is executed. If this test fails, the next module is consulted.

  • auth required pam_console.so — This line uses the pam_console.so module to attempt to authenticate the user. If this user is already logged in at the console, pam_console.so checks whether there is a file in the /etc/security/console.apps/ directory with the same name as the service name (reboot). If such a file exists, authentication succeeds and control is passed to the next module.

  • #auth include system-auth — This line is commented and is not processed.

  • account required pam_permit.so — This line uses the pam_permit.so module to allow the root user or anyone logged in at the console to reboot the system.

42.4.3.2. Control Flag

All PAM modules generate a success or failure result when called. Control flags tell PAM what do with the result. Modules can be stacked in a particular order, and the control flags determine how important the success or failure of a particular module is to the overall goal of authenticating the user to the service.

There are four predefined control flags:

  • required — The module result must be successful for authentication to continue. If the test fails at this point, the user is not notified until the results of all module tests that reference that interface are complete.

  • requisite — The module result must be successful for authentication to continue. However, if a test fails at this point, the user is notified immediately with a message reflecting the first failed required or requisite module test.

  • sufficient — The module result is ignored if it fails. However, if the result of a module flagged sufficient is successful and no previous modules flagged required have failed, then no other results are required and the user is authenticated to the service.

  • optional — The module result is ignored. A module flagged as optional only becomes necessary for successful authentication when no other modules reference the interface.

Important

The order in which required modules are called is not critical. Only the sufficient and requisite control flags cause order to become important.

A newer control flag syntax that allows for more precise control is now available for PAM.

The pam.d man page, and the PAM documentation, located in the /usr/share/doc/pam-<version-number>/ directory, where <version-number> is the version number for PAM on your system, describe this newer syntax in detail.

42.4.3.3. Module Name

The module name provides PAM with the name of the pluggable module containing the specified module interface. In older versions of Red Hat Enterprise Linux, the full path to the module was provided in the PAM configuration file. However, since the advent of multilib systems, which store 64-bit PAM modules in the /lib64/security/ directory, the directory name is omitted because the application is linked to the appropriate version of libpam, which can locate the correct version of the module.

42.4.3.4. Module Arguments

PAM uses arguments to pass information to a pluggable module during authentication for some modules.

For example, the pam_userdb.so module uses information stored in a Berkeley DB file to authenticate the user. Berkeley DB is an open source database system embedded in many applications. The module takes a db argument so that Berkeley DB knows which database to use for the requested service.

The following is a typical pam_userdb.so line in a PAM configuration. The <path-to-file> is the full path to the Berkeley DB database file:

auth	required	pam_userdb.so db=<path-to-file>

Invalid arguments are generally ignored and do not otherwise affect the success or failure of the PAM module. Some modules, however, may fail on invalid arguments. Most modules report errors to the /var/log/secure file.

42.4.4. Sample PAM Configuration Files

The following is a sample PAM application configuration file:

#%PAM-1.0
auth	required  pam_securetty.so
auth	required  pam_unix.so nullok
auth	required  pam_nologin.so
account	required  pam_unix.so
password	required  pam_cracklib.so retry=3
password	required  pam_unix.so shadow nullok use_authtok
session	required  pam_unix.so
  • The first line is a comment, indicated by the hash mark (#) at the beginning of the line.

  • Lines two through four stack three modules for login authentication.

    auth required pam_securetty.so — This module ensures that if the user is trying to log in as root, the tty on which the user is logging in is listed in the /etc/securetty file, if that file exists.

    If the tty is not listed in the file, any attempt to log in as root fails with a Login incorrect message.

    auth required pam_unix.so nullok — This module prompts the user for a password and then checks the password using the information stored in /etc/passwd and, if it exists, /etc/shadow.

    In the authentication phase, the pam_unix.so module automatically detects whether the user's password is in the passwd file or the shadow file. Refer to Section 32.6, “Shadow Passwords” for more information.

    • The argument nullok instructs the pam_unix.so module to allow a blank password.

  • auth required pam_nologin.so — This is the final authentication step. It checks whether the /etc/nologin file exists. If it exists and the user is not root, authentication fails.

    Note

    In this example, all three auth modules are checked, even if the first auth module fails. This prevents the user from knowing at what stage their authentication failed. Such knowledge in the hands of an attacker could allow them to more easily deduce how to crack the system.

  • account required pam_unix.so — This module performs any necessary account verification. For example, if shadow passwords have been enabled, the account interface of the pam_unix.so module checks to see if the account has expired or if the user has not changed the password within the allowed grace period.

  • password required pam_cracklib.so retry=3 — If a password has expired, the password component of the pam_cracklib.so module prompts for a new password. It then tests the newly created password to see whether it can easily be determined by a dictionary-based password cracking program.

    • The argument retry=3 specifies that if the test fails the first time, the user has two more chances to create a strong password.

  • password required pam_unix.so shadow nullok use_authtok — This line specifies that if the program changes the user's password, it should use the password interface of the pam_unix.so module to do so.

    • The argument shadow instructs the module to create shadow passwords when updating a user's password.

    • The argument nullok instructs the module to allow the user to change their password from a blank password, otherwise a null password is treated as an account lock.

    • The final argument on this line, use_authtok, provides a good example of the importance of order when stacking PAM modules. This argument instructs the module not to prompt the user for a new password. Instead, it accepts any password that was recorded by a previous password module. In this way, all new passwords must pass the pam_cracklib.so test for secure passwords before being accepted.

  • session required pam_unix.so — The final line instructs the session interface of the pam_unix.so module to manage the session. This module logs the user name and the service type to /var/log/secure at the beginning and end of each session. This module can be supplemented by stacking it with other session modules for additional functionality.

42.4.5. Creating PAM Modules

You can create or add new PAM modules at any time for use by PAM-aware applications.

For example, a developer might create a one-time-password creation method and write a PAM module to support it. PAM-aware programs can immediately use the new module and password method without being recompiled or otherwise modified.

This allows developers and system administrators to mix-and-match, as well as test, authentication methods for different programs without recompiling them.

Documentation on writing modules is included in the /usr/share/doc/pam-<version-number>/ directory, where <version-number> is the version number for PAM on your system.

42.4.6. PAM and Administrative Credential Caching

A number of graphical administrative tools in Red Hat Enterprise Linux provide users with elevated privileges for up to five minutes using the pam_timestamp.so module. It is important to understand how this mechanism works, because a user who walks away from a terminal while pam_timestamp.so is in effect leaves the machine open to manipulation by anyone with physical access to the console.

In the PAM timestamp scheme, the graphical administrative application prompts the user for the root password when it is launched. When the user has been authenticated, the pam_timestamp.so module creates a timestamp file. By default, this is created in the /var/run/sudo/ directory. If the timestamp file already exists, graphical administrative programs do not prompt for a password. Instead, the pam_timestamp.so module freshens the timestamp file, reserving an extra five minutes of unchallenged administrative access for the user.

You can verify the actual state of the timestamp file by inspecting the /var/run/sudo/<user> file. For the desktop, the relevant file is unknown:root. If it is present and its timestamp is less than five minutes old, the credentials are valid.

The existence of the timestamp file is indicated by an authentication icon, which appears in the notification area of the panel.

The Authentication Icon

Figure 42.7. The Authentication Icon

42.4.6.1. Removing the Timestamp File

Before abandoning a console where a PAM timestamp is active, it is recommended that the timestamp file be destroyed. To do this from a graphical environment, click the authentication icon on the panel. This causes a dialog box to appear. Click the Forget Authorization button to destroy the active timestamp file.

Dismiss Authentication Dialog

Figure 42.8. Dismiss Authentication Dialog

You should be aware of the following with respect to the PAM timestamp file:

  • If logged in to the system remotely using ssh, use the /sbin/pam_timestamp_check -k root command to destroy the timestamp file.

  • You need to run the /sbin/pam_timestamp_check -k root command from the same terminal window from which you launched the privileged application.

  • You must be logged in as the user who originally invoked the pam_timestamp.so module in order to use the /sbin/pam_timestamp_check -k command. Do not log in as root to use this command.

  • If you want to kill the credentials on the desktop (without using the Forget Authorization action on the icon), use the following command:

    /sbin/pam_timestamp_check -k root </dev/null >/dev/null 2>/dev/null
    

    Failure to use this command will only remove the credentials (if any) from the pty where you run the command.

Refer to the pam_timestamp_check man page for more information about destroying the timestamp file using pam_timestamp_check.

42.4.6.2. Common pam_timestamp Directives

The pam_timestamp.so module accepts several directives. The following are the two most commonly used options:

  • timestamp_timeout — Specifies the period (in seconds) for which the timestamp file is valid. The default value is 300 (five minutes).

  • timestampdir — Specifies the directory in which the timestamp file is stored. The default value is /var/run/sudo/.

Refer to Section 42.4.8.1, “Installed Documentation” for more information about controlling the pam_timestamp.so module.

42.4.7. PAM and Device Ownership

In Red Hat Enterprise Linux, the first user who logs in at the physical console of the machine can manipulate certain devices and perform certain tasks normally reserved for the root user. This is controlled by a PAM module called pam_console.so.

42.4.7.1. Device Ownership

When a user logs in to a Red Hat Enterprise Linux system, the pam_console.so module is called by login or the graphical login programs, gdm, kdm, and xdm. If this user is the first user to log in at the physical console — referred to as the console user — the module grants the user ownership of a variety of devices normally owned by root. The console user owns these devices until the last local session for that user ends. After this user has logged out, ownership of the devices reverts back to the root user.

The devices affected include, but are not limited to, sound cards, diskette drives, and CD-ROM drives.

This facility allows a local user to manipulate these devices without obtaining root access, thus simplifying common tasks for the console user.

You can modify the list of devices controlled by pam_console.so by editing the following files:

  • /etc/security/console.perms

  • /etc/security/console.perms.d/50-default.perms

You can change the permissions of different devices than those listed in the above files, or override the specified defaults. Rather than modify the 50-default.perms file, you should create a new file (for example, xx-name.perms) and enter the required modifications. The name of the new default file must begin with a number higher than 50 (for example, 51-default.perms). This will override the defaults in the 50-default.perms file.

Warning

If the gdm, kdm, or xdm display manager configuration file has been altered to allow remote users to log in and the host is configured to run at runlevel 5, it is advisable to change the <console> and <xconsole> directives in the /etc/security/console.perms to the following values:

<console>=tty[0-9][0-9]* vc/[0-9][0-9]* :0\.[0-9] :0 
<xconsole>=:0\.[0-9] :0

This prevents remote users from gaining access to devices and restricted applications on the machine.

If the gdm, kdm, or xdm display manager configuration file has been altered to allow remote users to log in and the host is configured to run at any multiple user runlevel other than 5, it is advisable to remove the <xconsole> directive entirely and change the <console> directive to the following value:

<console>=tty[0-9][0-9]* vc/[0-9][0-9]*

42.4.7.2. Application Access

The console user also has access to certain programs configured for use in the /etc/security/console.apps/ directory.

This directory contains configuration files which enable the console user to run certain applications in /sbin and /usr/sbin.

These configuration files have the same name as the applications that they set up.

One notable group of applications that the console user has access to are three programs that shut down or reboot the system:

  • /sbin/halt

  • /sbin/reboot

  • /sbin/poweroff

Because these are PAM-aware applications, they call the pam_console.so module as a requirement for use.

Refer to Section 42.4.8.1, “Installed Documentation” for more information.

42.4.8. Additional Resources

The following resources further explain methods to use and configure PAM. In addition to these resources, read the PAM configuration files on the system to better understand how they are structured.

42.4.8.1. Installed Documentation

  • PAM-related man pages — Several man pages exist for the various applications and configuration files involved with PAM. The following is a list of some of the more important man pages.

    Configuration Files
    • pam — Good introductory information on PAM, including the structure and purpose of the PAM configuration files.

      Note that this man page discusses both /etc/pam.conf and individual configuration files in the /etc/pam.d/ directory. By default, Red Hat Enterprise Linux uses the individual configuration files in the /etc/pam.d/ directory, ignoring /etc/pam.conf even if it exists.

    • pam_console — Describes the purpose of the pam_console.so module. It also describes the appropriate syntax for an entry within a PAM configuration file.

    • console.apps — Describes the format and options available in the /etc/security/console.apps configuration file, which defines which applications are accessible by the console user assigned by PAM.

    • console.perms — Describes the format and options available in the /etc/security/console.perms configuration file, which specifies the console user permissions assigned by PAM.

    • pam_timestamp — Describes the pam_timestamp.so module.

  • /usr/share/doc/pam-<version-number> — Contains a System Administrators' Guide, a Module Writers' Manual, and the Application Developers' Manual, as well as a copy of the PAM standard, DCE-RFC 86.0, where <version-number> is the version number of PAM.

  • /usr/share/doc/pam-<version-number>/txts/README.pam_timestamp — Contains information about the pam_timestamp.so PAM module, where <version-number> is the version number of PAM.

42.4.8.2. Useful Websites

  • http://www.kernel.org/pub/linux/libs/pam/ — The primary distribution website for the Linux-PAM project, containing information on various PAM modules, a FAQ, and additional PAM documentation.

    Note

    The documentation in the above website is for the last released upstream version of PAM and might not be 100% accurate for the PAM version included in Red Hat Enterprise Linux.


Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.