Section A.3. PAM Modules

A.3. PAM Modules

Creating or modifying a PAM configuration requires at least a basic understanding of the available PAM modules. If you check your existing PAM configuration files, you're likely to see quite a range of module calls, and modifying them to get the results you expect can be tricky if you don't understand what the existing modules do.

Some PAM modules can be called for only some management groups. Others can be called as part of a stack for any management group.

A.3.1. Standard PAM Modules

PAM ships with quite a few different modules. Table A-2 summarizes those that you're most likely to encounter in your existing configuration files. Note that, although some modules directly relate to password handling, others don't; they're used to display information to users, set environment variables, and so on. For these modules, PAM is simply a convenient tool for accomplishing their goals. Such modules may not affect the login process at all.

Table A-2. Common standard PAM modules

Module filename	Management groups	Common arguments	Description
pam_unix.so	auth, account, session, and password	nullok, likeauth, shadow, try_first_pass, use_first_pass, use_authtok	Implements the traditional Unix (and Linux) authentication, based on /etc/passwd and /etc/shadow files.
pam_unix2.so	auth, account, session, and password	nullok, likeauth, shadow, try_first_pass, use_first_pass, use_authtok	A variant on pam_unix.so that implements additional features, such as an ability to authenticate against a Network Information Service (NIS) server.
pam_smb_auth.so	auth	use_first_pass, nolocal	This module is an alternative way to authenticate against NT domain controllers to that described in Chapter 7. It uses the /etc/pam_smb.conf configuration file.
pam_securetty.so	auth	-	Blocks root access to the login service unless the environment variable PAM_TTY is set to a string listed in the /etc/securetty file.
pam_time.so	account	-	Reads /etc/security/time.conf, which specifies time-based access restriction rules.
pam_nologin.so	auth and account	successok	If /etc/nologin exists, only root is permitted to log in, and all users are shown the contents of that file. If the file doesn't exist, the module has no effect, unless the successok parameter is used, in which case the login succeeds (as if the module were called with a sufficient control flag).
pam_homecheck.so	auth and session	abort	Prints a warning if the user's home directory or certain other files are world-writable or if they're owned by another user. If the abort option is used, the login fails under these circumstances.
pam_env.so	auth	conffile=filename, envfile=filename	Sets environment variables for the login session, based on the contents of the configuration file (/etc/security/pam_env.conf by default).
pam_mail.so	auth and session	dir=directory, empty	Checks for mail in the specified directory and notifies the user if any is present. If empty is used, also informs the user when no mail is present.
pam_lastlog.so	auth	nodate, noterm, nohost, silent, never	Displays information on the user's last login. The module's options tell it what information to omit from this display. It maintains last login information in the /var/log/lastlog file.
pam_motd.so	session	motd=filename	Displays the contents of the message of the day (MOTD) file, which is /etc/motd by default, upon a successful login.
pam_deny.so	auth, account, session, and password	-	Always indicates a failure; useful at the end of certain stacks or as part of a default service to eliminate the risk of an unauthorized login due to misconfiguration.
pam_limits.so	session	conf=filename	Places limits, described in the /etc/security/limits.conf or specified configuration file, on users' resource uses (memory, CPU time, etc.). Requires kernel support for resource limits.
pam_mkhomedir.so	session	skel=directory, umask=octal-umask	Creates a home directory for users if one doesn't already exist, using the specified skeleton (skel) directory to populate the home directory with default configuration files and setting the directory's permissions based on the specified umask.
pam_access.so	account	accessfile=filename	Uses /etc/security/access.conf or the specified access file to determine username/machine name pairs that are or aren't granted accesse.g., to deny root the right to log in from particular machines.
pam_pwcheck.so	password	nullok, use_first_pass, use_authtok	Performs extra checks on password changes, as defined in /etc/login.defs, to improve security on user-selected passwords.
pam_cracklib.so	password	use_authtok and others to set specific checks	Adds checks for various features, such as passwords that have been used in the past or passwords that are too simple, to password-change interactions. Uses the libcrack library and a system dictionary (/usr/lib/cracklib_dict).
pam_stack.so	auth, account, session, and password	service=name	Calls a stack for the specified service. Provides easier configuration; you need to modify only one PAM configuration file to implement PAM changes across all the services that call pam_stack.so.

Not all the modules mentioned in Table A-2 ship with all Linux distributions. These modules are all present and used in the default installations of at least one major distribution, though, with the exception of pam_mkhomedir.so. This module ships with all the major distributions but isn't used by default. It is, however, extremely useful with NT domain and LDAP add-on PAM modules.

Some modules accept parameters that are common to other modules. These common parameters include:

debug

Although it's not mentioned in Table A-2, this parameter causes most modules to dump extra debugging information to your system logfiles.

try_first_pass

Used in auth stacks, this option causes a module to try to use a password collected by a previous module for authentication. If this password fails, the module prompts the user again. Using this option on the second and subsequent password-checking modules can eliminate multiple password requests when you try to log in.

use_first_pass

This parameter works much like TRy_first_pass, but it causes the module that uses it to not request a password if the one it's given from a prior module fails.

nullok

Most modules that handle passwords refuse null passwords (that is, passwords of zero length). This option tells these modules that null passwords are acceptable. (For authentication, of course, the authentication database must contain a null password; this option doesn't bypass the password check.)

likeauth

This parameter causes the module to return the same value when called as a credential-setting module as an authentication module. This practice helps PAM navigate the module stack most efficiently.

shadow

If this option is present, the module takes extra care to maintain a system with shadow passwords. In particular, it better handles password aging, expiration, and similar information.

use_authtok

This option causes a module in a password stack to use the password given to a previous module in a stack.

Linux distributions vary substantially in how they build PAM stacks from these modules. If you check two distributions' files, you'll probably find they call modules using different options, and they may call different sets of modules. Even within a distribution, different services may call different modules, even when the services are similar in function. Ultimately, though, most PAM stacks call pam_unix.so or pam_unix2.so, either directly for each service or indirectly via pam_stack.so. This is the most important PAM module, especially for logins.

A.3.2. Additional PAM Modules

Chapters Chapter 7, Chapter 8, and Chapter 9 present information on PAM modules that can be used in addition to or instead of the standard modules. In particular, these modules can replace or supplement pam_unix.so or pam_unix2.so. If you check the Internet, you can find still more PAM modules.

As described in the relevant chapters, there's more to adding support for most network authentication modules than simply configuring PAM. These modules typically rely on external configuration files to point them to their authentication servers. Sometimes you must configure the server to accept authentication requests from your Linux system or take other special steps to get the system to work.

When you add new PAM modules for authentication, you should first decide where to add them. If your distribution uses the pam_stack.so module, you should modify the stack that it referencestypically /etc/pam.d/system-auth. If your distribution doesn't use this module, however, you may need to modify the configuration files for all the services that should use the new PAM module. For login services (login, xdm, sshd, and so on), you need to add auth and account lines:

auth     sufficient  /lib/security/pam_winbind.so try_first_pass account  sufficient  /lib/security/pam_winbind.so

Of course, the name of the module you call depends on what you're adding. Add the auth line to the existing auth stack just after the line that references pam_unix.so, and add the account line just after the existing account line. This placement causes PAM to check the new service after checking the local account database. The sufficient control flag tells PAM that if this authentication succeeds, it doesn't need to perform additional authentication checks; however, if it fails, PAM falls back on the local account database. The TRy_first_pass option prevents PAM from prompting for a password again should this happen; it delivers the password the user entered first into the next authentication tool.

Some servers and login tools must be restarted before they'll read the new PAM configuration files, so, if you forget to restart a server, you may think your change hasn't worked, when in fact it simply hasn't yet taken effect. Try to be methodical in your tests if you run into problems. Create some test accounts and take notes on the effects.

Be sure to test the effect of incorrect loginsboth nonexistent usernames and valid usernames with invalid passwords. Some PAM configurations result in successful logins even when invalid passwords, and sometimes even invalid usernames, are entered. If you run into this problem, try adding a required call to pam_deny.so and make the actual authentication modules sufficient.

For password-changing services, such as passwd, your concerns are a bit different from those for login services. Depending on your needs, you might consider doing any of several things:

• Adding a new entry to the password stack causes the passwd program to prompt for two password changes: one for the local Unix password database and again for the new service you've added.

• Adding a new entry to the password stack and using the options use_authtok or use_first_pass with the second call causes both systems to use the password you enter the first time. You may need to make both these entries sufficient rather than required.

• Replacing the existing call to pam_unix.so or pam_unix2.so causes a single prompt for a password change using the new service, leaving the local password (if it exists) untouched.

• Not changing the password stack causes only the local account to change, if it exists. Users need to use tools specific to their new authentication system, such as smbpasswd for an NT domain controller, to change their network passwords.

As if these concerns weren't enough, a further complication is root's power to change normal users' passwords. Network authentication tools typically provide strong protections against anybody but the user or the password server's administrator from changing passwords. A local root account is unlikely to have this power, so chances are you'll need to use the administrative database's tools to make these changes.