User Authentication HOWTO
Prev		Next

3. PAM (Pluggable Authentication Modules)

Pluggable authentication modules are at the core of user authentication in any modern linux distribution.

3.1. Why

Back in the good old days of linux, if a program, such as su, passwd, login, or xlock, needed to authenticate a user, it would simply read the necessary information from /etc/passwd. If it needed to change the users' password, it would simply edit /etc/passwd. This simple but clumsy method presented numerous problems for system administrators and application developers. As MD5 and shadow passwords became increasingly popular, each program requiring user authentication had to know how to get the proper information when dealing with a number of different schemes. If you wanted to change your user authentication scheme, all these programs had to be recompiled. PAM eliminates this mess by enabling programs to transparently authenticate users, regardless of how user information is stored.

3.2. What

Quoting from the Linux-PAM System Administrator's Guide: "It is the purpose of the Linux-PAM project to separate the development of privilege granting software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated." With PAM, it doesn't matter whether your password is stored in /etc/passwd or on a server in Hong Kong. When a program needs to authenticate a user, PAM provides a library containing the functions for the proper authentication scheme. Because this library is loaded dynamically, changing authentication schemes can be done by simply editing a configuration file.

Flexibility is one of PAM's greatest strengths. PAM can be configured to deny certain programs the right to authenticate users, to only allow certain users to be authenticated, to warn when certain programs attempt to authenticate, or even to deprive all users of login privileges. PAM's modular design gives you complete control over how users are authenticated.

3.2.1. Distributions that support pam.

Nearly all popular distributions have supported PAM for some time. Here's an incomplete list of distributions that support PAM:

Redhat since version 5.0
Mandrake since 5.2
Debian since version 2.1 (partial support in 2.1 -- complete support in 2.2)
Caldera since version 1.3
Turbolinux since version 3.6
SuSE since version 6.2

This list is certainly incomplete and possibly inaccurate. I'd appreciate it if you sent any corrections or additions to this list to <petehern@yahoo.com>.

3.2.2. Installing PAM

Installing PAM from scratch is long process, beyond the scope of this HOWTO. If PAM isn't installed on your system, you're probably running such an old version of your distribution that there are many other reasons to upgrade. If you really want to do it yourself, then you're certainly not the sort of person who needs any help from me. For all these reasons, I'm going to assume that you already have PAM installed.

3.3. How

Enough talk, let's dig in.

3.3.1. PAM configuration files

PAM configuration files are stored in the /etc/pam.d/ directory. (If you don't have /etc/pam.d/ directory, don't worry, I'll cover that in the next section) Let's go over there and take a look.

  ~$ cd /etc/pam.d
  /etc/pam.d/$ ls
  chfn	chsh	login	other	passwd	su	xlock
  /etc/pam.d/$

Your system may have a few more or a few less files in this directory, depending on what's installed on your system. Whatever the details, you probably saw a file for each of the programs on your system that authenticate users. As you probably already guessed, each file contains the PAM authentication configuration for the program it's named after (except for the other file, which we'll talk about in a little bit). Let's take a look the PAM configuration file for login (I've condensed the file for the sake of simplicity):

  /etc/pam.d/$ cat login
  # PAM configuration for login
  auth       requisite  pam_securetty.so
  auth       required   pam_nologin.so
  auth       required   pam_env.so
  auth       required   pam_unix.so nullok
  account    required   pam_unix.so
  session    required   pam_unix.so
  session    optional   pam_lastlog.so
  password   required   pam_unix.so nullok obscure min=4 max=8

Before I dig into this file, I must mention a little something.

3.3.2. A little something

A small percentage of the readers are probably thinking, "Oh no! I don't have a /etc/pam.d directory! Your list of distributions says that my distribution includes PAM, but I can't find that directory. Without PAM, my life is empty and meaningless! What can I do?" Don't worry, all is not lost. If you know that your distribution includes PAM, but you have no /etc/pam.d/ directory, then your PAM configuration is stored in /etc/pam.conf. Rather than being spread across several files, all your PAM configuration is stored in a single file. This adds a little twist to PAM configuration, but the proper adjustments are pointed out in section 3.3.4.

3.3.3. Configuration syntax

PAM configuration files have the following syntax:

  type  control  module-path  module-arguments

Using the login configuration file (see above) as an example let's take a look a the syntax for PAM configuration files:

PAM configuration tokens

type

The type token tells PAM what type of authentication is to be used for this module. Modules of the same type can be "stacked", requiring a user to meet multiple requirements to be authenticated. PAM recognizes four types:

account: Determines whether the user is allowed to access the service, whether their passwords has expired, etc.
auth: Determines whether the user is who they claim to be, usually by a password, but perhaps by a more sophistcated means, such as biometrics.
password: Provides a mechanism for the user to change their authentication. Again, this usually their password.
session: Things that should be done before and/or after the user is authenticed. This might included things such as mounting/unmounting the user home directory, logging their login/logout, and restricting/unrestricting the services available to the user.

In the login config file, we see at least one entry for each type. Since this the program that allows user to login (hence the name :), it's understandable that it needs to access all of the different types of authentication.

control

The control token tells PAM what should be done in if authentication by this module fails. PAM recognizes four control types:

requisite: Failure to authenticate via this module results in immediate denial of authentication.
required: Failure also results in denial of authentication, although PAM will still call all the other modules listed for this service before denying authentication.
sufficient: If authentication by this module is successful, PAM will grant authentication, even if a previous required module failed.
optional: Whether this module succeeds or fails is only significant if it is the only module of its type for this service.

In the configuration file for login, we see nearly all of the different control types. Most of the required modules are pam_unix.so (the main authentication module), the single requisite module is pam_securetty.so (which makes sure the user is logging in on a secure console), and the only optional module is pam_lastlog.so (the module that retrieves information on the user's most recent login).

module-path

The module-path tells PAM which module to use and (optionally) where to find it. Most configurations only contain the module's name, as is the case in our login configuration file. When this is the case, PAM looks for the modules in the default PAM module directory, normally /usr/lib/security. However, if your linux distribution conforms to the Filesystem Hierarchy Standard (FHS), PAM modules can be found in /lib/security.

module-arguments

The module-arguments are arguments to be passed to the module. Each module has its own arguments. For example, in our login configuration, the "nulok" ("null ok", argument being passed to pam_unix.so module, indicating the a blank ("null") password is acceptable ("ok").

3.3.4. `pam.conf` configuration

If your PAM configuration is stored in /etc/pam.conf rather than /etc/pam.d/, PAM configuration lines are a bit different. Rather than each service having its own configuration file, all configurations are stored in /etc/pam.conf with the service name as the first token in a configuration line. For example, the following line in /etc/pam.d/login:

    auth       required   pam_unix.so nulok

would become the following line in /etc/pam.conf:

    login	auth       required   pam_unix.so nulok

Except for this minor difference, all the rest of the configuration PAM syntax applies.

3.4. Getting more information

For more information on configuring PAM and complete PAM module reference, consult the Linux-PAM System Administrator's Guide. This guide serves as a thorough and up-to-date reference on PAM configuration.

Prev	Home	Next
How User Information is Stored on Your System		Securing User Authentication