pam.conf(4)

NAME

pam.conf — configuration file for pluggable authentication modules

SYNOPSIS

/etc/pam.conf

DESCRIPTION

/etc/pam.conf is the configuration file for the Pluggable Authentication Module architecture, or PAM. A PAM module provides functionality for one or more of four possible services: authentication, account management, session management, and password management.

An authentication service module provides functionality to authenticate a user and set up user credentials. An account management module provides functionality to determine if the current user's account is valid. This includes checking for password and account expiration, as well as verifying access hour restrictions. A session management module provides functionality to set up and terminate login sessions. A password management module provides functionality to change a user's authentication token or password.

Simplified pam.conf configuration file

The /etc/pam.conf file contains a listing of services. Each service is paired with a corresponding service module. When a service is requested, its associated module is invoked. Each entry has the following format:

service_name module_type control_flag module_path options 

Below is an example of the /etc/pam.conf configuration file with support for authentication, account management, session management and password management modules. Note that the use of pam_hpsec is mandatory for some of the services. For more information, see pam_hpsec(5).

login    auth     required  libpam_hpsec.so.1 debug
login    auth     required  libpam_unix.so.1  debug
login    session  required  libpam_hpsec.so.1
login    session  required  libpam_unix.so.1
login    account  required  libpam_hpsec.so.1
login    account  required  libpam_unix.so.1
dtlogin  auth     required  libpam_hpsec.so.1
dtlogin  auth     required  libpam_unix.so.1
dtlogin  session  required  libpam_hpsec.so.1
dtlogin  session  required  libpam_unix.so.1
other    auth     required  libpam_hpsec.so.1
other    auth     required  libpam_unix.so.1
other    account  required  libpam_hpsec.so.1
other    account  required  libpam_unix.so.1
other    session  required  libpam_hpsec.so.1
other    session  required  libpam_unix.so.1
other    password required  libpam_hpsec.so.1
other    password required  libpam_unix.so.1

service_name: The service_name denotes the service (for example, login, or dtlogin). The keyword, other, indicates the module all other applications which have not been specified should use. The other keyword can also be used if all services of the same module_type have the same requirements. In the example above, since all of the services use the same account management module, they could have been replaced by a single other line.
module_type: module_type denotes the service module type: authentication (auth), account management (account), session management (session), or password management (password).
control_flag: The control_flag field determines the behavior of stacking, and will be discussed in more detail below.
module_path: The module_path field specifies the pathname to a shared library object which implements the service functionality. If the pathname is not absolute, it is assumed to be relative to /usr/lib/security/$ISA/. The $ISA (i.e Instruction Set Architecture) token is replaced by the PAM engine (libpam) with hpux32 for Itanium-based 32-bit modules, with null for PA-RISC 32-bit modules, with hpux64 for Itanium-based 64-bit modules, or with pa20_64 for PA-RISC 64-bit modules. To accommodate backward compatibility to PA-RISC library naming convention, appropriate links are provided in /usr/lib/security/ and /usr/lib/security/pa20_64 Example: /usr/lib/security/libpam_unix.so.1 -> ./libpam_unix.1 If a user-defined module is specified in /etc/pam.conf or /etc/pam_user.conf, the above convention must be followed to create symbolic links pointing to PA-RISC modules. To help reduce the impact of any future /etc/pam.conf file format changes, the only supported way of parsing /etc/pam.conf is through the PAM library interfaces. These interfaces will transparently do any necessary expansion of reserved tokens, such as $ISA.
options: The options field is used by the PAM framework layer to pass module-specific options to the modules. It is up to the module to parse and interpret the options. This field can be used by the modules to turn on debugging or to pass any module specific parameters such as a TIMEOUT value. It can also be used to support unified login. The options supported by the modules are documented in their respective manual pages. For example, pam_unix(5) lists the options accepted by the UNIX module.

Integrating Multiple Authentication Services With Stacking

When a service_name of the same module_type is defined more than once, the service is said to be stacked. Each module referenced in the module_path for that service is then processed in the order that it occurs in the configuration file. The control_flag field specifies the continuation and failure semantics of the modules, and may contain one of the following values:

optional: If the service module returns success, record the success and continue to process the PAM stack. If a failure is returned, and it is the first optional module failure, save the failure code as an optional failure. Continue to process the PAM stack.
required: If the service module returns success, record the success and continue to process the PAM stack. If a failure is returned, and it is the first required failure, save the failure code as a required failure. Continue to process the PAM stack.
requisite: If the service module returns success, record the success and continue to process the PAM stack. If a failure is returned, immediately return the first non-optional failure value recorded, without calling any subsequent modules. In other words, record this failure, unless a previous required service module failed. If a previous required service module failed, return the first of those values.
sufficient: If the service module returns success and no preceding required modules returned failures, immediately return success without calling any subsequent modules. If a failure is returned, treat the failure as an optional module failure, and continue to process the PAM stack.

If no requisite module fails and no sufficient module succeeds, the PAM stack runs to completion. In this case success is returned, providing no required module failed and at least one required, requisite, or optional module succeeded. If no module succeeded and a required module failed, the first of those errors is returned.

If all modules return PAM_IGNORE, a default error based on module type is returned.

If any entry in /etc/pam.conf is incorrect, or if a module does not exist or cannot be opened, then all PAM services fail and users are not be permitted access to the system. An error will be logged through syslog(3C) at the LOG_CRIT level, and the PAM framework returns PAM_OPEN_ERR error to the application.

Below is a sample configuration file that stacks the login, and dtlogin services.

login    auth  required   libpam_hpsec.so.1 debug
login    auth  required   libpam_unix.so.1  debug
login    auth  optional   libpam_inhouse.so.1
dtlogin  auth  required   libpam_hpsec.so.1  debug
dtlogin  auth  sufficient libpam_unix.so.1   debug
dtlogin  auth  required   libpam_inhouse.so.1

In the case of login, the user is authenticated by the hpsec, the UNIX, and inhouse authentication modules. The required keyword for control_flag requires that the user be allowed to login only if the user is authenticated by the hpsec and the UNIX service modules. The inhouse authentication is optional by virtue of the optional keyword in the control_flag field. The user can still log in even if inhouse authentication fails, as long as hpsec and UNIX both successfully authenticate the user.

In the case of dtlogin, the sufficient keyword for control_flag specifies that if the UNIX authentication check succeeds, then PAM should return success to dtlogin. The inhouse authentication module (the next module in the stack) will only be invoked if the UNIX authentication check fails.

Configuration Per User

/etc/pam.conf contains information to configure all the users on a system. But sometimes it is necessary to configure user by user. A user policy definition is made through a specific module named libpam_updbe.so.1. This module reads a file named /etc/pam_user.conf which describes the user's configurations.

Below is a sample configuration file (/etc/pam.conf) that uses the module libpam_updbe.so.1.

login    auth     required      libpam_hpsec.so.1
login    auth     required      libpam_updbe.so.1
login    auth     required      libpam_unix.so.1
su       auth     required      libpam_hpsec.so.1
su       auth     required      libpam_updbe.so.1
su       auth     required      libpam_unix.so.1
OTHER    auth     required      libpam_hpsec.so.1
OTHER    auth     required      libpam_unix.so.1

login    password required      libpam_hpsec.so.1
login    password required      libpam_updbe.so.1
login    password required      libpam_unix.so.1
passwd   password required      libpam_hpsec.so.1
passwd   password required      libpam_updbe.so.1
passwd   password required      libpam_unix.so.1
OTHER    password required      libpam_hpsec.so.1
OTHER    password required      libpam_unix.so.1

The module libpam_updbe.so.1 searches the configuration file /etc/pam_user.conf and reads the configuration associated with the login name of the current user. If there is no configuration concerning the current user in the pam_user.conf file, the PAM framework ignores the line containing libpam_updbe.so.1. /etc/pam.conf applies for those users who are not configured in pam_user.conf.

Notes

If an error is found in an entry due to invalid service_name, module_type, or control_flag, then the entry is ignored. If there are no valid entries for the given module_type, the PAM framework returns an error to the application.

EXAMPLES

The following is a sample /etc/pam.conf configuration file. Lines that begin with the # symbol are treated as comments, and therefore ignored.

#
# PAM configuration
#
# Authentication management for login service is stacked.
# Both UNIX and inhouse authentication functions are invoked,
# in addition to hpsec authentication functions.
login   auth   required   libpam_hpsec.so.1
login   auth   required   libpam_unix.so.1
login   auth   required   libpam_inhouse.so.1  try_first_pass
dtlogin auth   required   libpam_hpsec.so.1
dtlogin auth   required   libpam_unix.so.1
dtlogin auth   required   libpam_inhouse.so.1  try_first_pass
#
# Other services use hpsec and UNIX authentication
other   auth     required     libpam_hpsec.so.1
other   auth     required     libpam_unix.so.1
#
# Account management for login service is stacked.
# hpsec and UNIX account management are required;
# inhouse account management is optional
login   account  required     libpam_hpsec.so.1
login   account  required     libpam_unix.so.1
login   account  optional     libpam_inhouse.so.1
dtlogin account  required     libpam_hpsec.so.1
dtlogin account  required     libpam_unix.so.1
dtlogin account  optional     libpam_inhouse.so.1
#
# Other services use hpsec and UNIX account management
other   account  required     libpam_hpsec.so.1
other   account  required     libpam_unix.so.1
#
# Session management for login service is stacked.
# hpsec and UNIX account management are required;
login   session  required     libpam_hpsec.so.1
login   session  required     libpam_unix.so.1
dtlogin session  required     libpam_hpsec.so.1
dtlogin session  required     libpam_unix.so.1
#
# Other services use hpsec and UNIX session management
other   session  required     libpam_hpsec.so.1
other   session  required     libpam_unix.so.1
#
# Password management
other   password required     libpam_hpsec.so.1
other   password required     libpam_unix.so.1

The following is a sample /etc/pam.conf configuration which uses the libpam_updbe.so.1 module to configure a user. Lines that begin with the # symbol are treated as comments, and therefore ignored.

#
# PAM configuration
#
# Authentication management for login service is stacked.
# Both UNIX and inhouse authentication functions are invoked,
# in addition to hpsec authentication functions.
login   auth   required   libpam_hpsec.so.1
login   auth   required   libpam_updbe.so.1
login   auth   required   libpam_unix.so.1
login   auth   required   libpam_inhouse.so.1  try_first_pass
dtlogin auth   required   libpam_hpsec.so.1
dtlogin auth   required   libpam_updbe.so.1
dtlogin auth   required   libpam_unix.so.1
dtlogin auth   required   libpam_inhouse.so.1  try_first_pass
#
# Other services use hpsec and UNIX authentication
other   auth     required     pam_hpsec.so.1
other   auth     required     pam_unix.so.1
#
# Account management for login service is stacked.
# hpsec and UNIX account management are required;
# inhouse account management is optional
login   account  required     libpam_hpsec.so.1
login   account  required     libpam_unix.so.1
login   account  optional     libpam_inhouse.so.1
dtlogin account  required     libpam_hpsec.so.1
dtlogin account  required     libpam_unix.so.1
dtlogin account  optional     libpam_inhouse.so.1
other   account  required     libpam_hpsec.so.1
other   account  required     libpam_unix.so.1
#
# Session management for login service is stacked.
# hpsec and UNIX account management are required
login   session  required     libpam_hpsec.so.1
login   session  required     libpam_unix.so.1
login   session  optional     libpam_inhouse.so.1
dtlogin session  required     libpam_hpsec.so.1
dtlogin session  required     libpam_unix.so.1
dtlogin session  optional     libpam_inhouse.so.1
#
# Other services use hpsec and UNIX session management
other   session  required     libpam_hpsec.so.1
other   session  required     libpam_unix.so.1
#
# Password management
passwd  password required     libpam_hpsec.so.1
passwd  password required     libpam_updbe.so.1
passwd  password required     libpam_unix.so.1
other   password required     libpam_hpsec.so.1
other   password required     libpam_unix.so.1

Utilities and Files

A list of utilities that are known to use PAM includes: login, passwd, su, dtlogin, ftp, remsh/rexec, and ssh.

The PAM configuration file does not dictate either the name or the location of the service specific modules. The convention, however, is the following:

/usr/lib/security/$ISA/libpam_service_name.so.1: Implements various functions of specific authentication services.
/etc/pam.conf: Configuration file.
/usr/lib/hpux32/libpam.so.1: Implements the 32-bit PAM framework library on Itanium-based systems.
/usr/lib/hpux64/libpam.so.1: Implements the 64-bit PAM framework library on Itanium-based systems.
/usr/lib/libpam.1: Implements the 32-bit PAM framework library on PA-RISC.
/usr/lib/pa20_64/libpam.1: Implements the 64-bit PAM framework library on PA-RISC.