System administrators and programmers often want to restrict access to certain parts of the system or to limit the use of certain functions of an application. Without PAM, applications must be adapted every time a new authentication mechanism, such as LDAP, Samba, or Kerberos, is introduced. This process, however, is rather time-consuming and error-prone. One way to avoid these drawbacks is to separate applications from the authentication mechanism and delegate authentication to centrally managed modules. Whenever a newly required authentication scheme is needed, it is sufficient to adapt or write a suitable PAM module for use by the program in question.

The PAM concept consists of:

PAM can be configured in two ways:

The files under /etc/pam.d/ define the PAM modules used for authentication. Each file consists of lines, which define a service, and each line consists of a maximum of four components:

TYPE CONTROL MODULE_PATH MODULE_ARGS

The components have the following meaning:

In addition, there are global configuration files for PAM modules under /etc/security, which define the exact behavior of these modules (examples include pam_env.conf and time.conf). Every application that uses a PAM module actually calls a set of PAM functions, which then process the information in the various configuration files and return the result to the requesting application.

To facilitate the creation and maintenance of PAM modules, common default configuration files for the types auth, account, password, and session modules have been introduced. These are retrieved from every application's PAM configuration. Updates to the global PAM configuration modules in common-* are thus propagated across all PAM configuration files without requiring the administrator to update every single PAM configuration file.

The global common PAM configuration files are maintained using the pam-config tool. This tool automatically adds new modules to the configuration, changes the configuration of existing ones or deletes modules (or options) from the configurations. Manual intervention in maintaining PAM configurations is minimized or no longer required.

	64-Bit and 32-Bit Mixed Installations
When using a 64-bit operating system, it is possible to also include a runtime environment for 32-bit applications. In this case, make sure that you install both versions of the pam modules.

Consider the PAM configuration of sshd as an example:

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

By including them instead of adding each module separately to the respective PAM configuration, you automatically get an updated PAM configuration when an administrator changes the defaults. Formerly, you had to adjust all configuration files manually for all applications when changes to PAM occurred or a new application was installed. Now the PAM configuration is made with central configuration files and all changes are automatically inherited by the PAM configuration of each service.

The first include file (common-auth) calls three modules of the auth type: pam_env.so, pam_gnome_keyring.so and pam_unix2.so. See Example 2.2, “Default Configuration for the auth Section”.

auth    required        pam_env.so
auth    optional        pam_gnome_keyring.so
auth    required        pam_unix2.so

The first one, pam_env.so, loads /etc/security/pam_env.conf to set the environment variables as specified in this file. It can be used to set the DISPLAY variable to the correct value, because the pam_env module knows about the location from which the login is taking place. The second one automatically unlocks the GNOME keyring when necessary. The last one, pam_unix2, checks the user's login and password against /etc/passwd and /etc/shadow.

The whole stack of auth modules is processed before sshd gets any feedback about whether the login has succeeded. Given that all modules of the stack have the required control flag, they must all be processed successfully before sshd receives a message about the positive result. If one of the modules is not successful, the entire module stack is still processed and only then is sshd notified about the negative result.

As soon as all modules of the auth type have been successfully processed, another include statement is processed, in this case, that in Example 2.3, “Default Configuration for the account Section”. common-account contains just one module, pam_unix2. If pam_unix2 returns the result that the user exists, sshd receives a message announcing this success and the next stack of modules (password) is processed, shown in Example 2.4, “Default Configuration for the password Section”.

account required        pam_unix2.so

password requisite      pam_pwcheck.so  nullok cracklib
password required       pam_unix2.so    nullok use_authtok

Again, the PAM configuration of sshd involves just an include statement referring to the default configuration for password modules located in common-password. These modules must successfully be completed (control flags requisite and required) whenever the application requests the change of an authentication token.

Changing a password or another authentication token requires a security check. This is achieved with the pam_pwcheck module. The pam_unix2 module used afterwards carries over any old and new passwords from pam_pwcheck, so the user does not need to authenticate again after changing the password. This procedure makes it impossible to circumvent the checks carried out by pam_pwcheck. Whenever the account or the auth type are configured to complain about expired passwords, the password modules should also be used.

session required        pam_limits.so
session required        pam_unix2.so
session optional        pam_umask.so

As the final step, the modules of the session type (bundled in the common-session file) are called to configure the session according to the settings for the user in question. The pam_limits module loads the file /etc/security/limits.conf, which may define limits on the use of certain system resources. The pam_unix2 module is processed again. The pam_umask module can be used to set the file mode creation mask. Since this module carries the optional flag, a failure of this module would not affect the successful completion of the entire session module stack. The session modules are called a second time when the user logs out.

Some of the PAM modules are configurable. The configuration files are located in /etc/security. This section briefly describes the configuration files relevant to the sshd example—pam_env.conf and limits.conf.

VARIABLE  [DEFAULT=value]  [OVERRIDE=value]

REMOTEHOST     DEFAULT=localhost OVERRIDE=@{PAM_RHOST}
DISPLAY        DEFAULT=${REMOTEHOST}:0.0 OVERRIDE=${DISPLAY}

The pam-config tool helps you configure the global PAM configuration files (/etc/pam.d/common-*-pc) as well as several selected application configurations. For a list of supported modules, use the pam-config --list-modules command. Use the pam-config command to maintain your PAM configuration files. Add new modules to your PAM configurations, delete other modules or modify options to these modules. When changing global PAM configuration files, no manual tweaking of the PAM setup for individual applications is required.

A simple use case for pam-config involve the following:

When you create your PAM configuration files from scratch using the pam-config --create command, it creates symbolic links from the common-* to the common-*-pc files. pam-config only modifies the common-*-pc configuration files. Removing these symbolic links effectively disable pam-config, because pam-config only operates on the common-*-pc files and these files are not put into effect without the symbolic links.

For more information on the pam-config command and the options available, refer to the manual page of pam-config(8).

In the /usr/share/doc/packages/pam directory of the installed system, find the following additional documentation:

Thorsten Kukuk has developed a number of PAM modules. Find the documentation of these modules at http://www.suse.de/~kukuk/pam/.