PAM Configuration (Reference)
The PAM configuration file, pam.conf(4), is used to configure PAM service modules for
system services, such as login, rlogin, su, and cron. The system administrator manages
this file. An incorrect order of entries in pam.conf can cause unforeseen
side effects. For example, a badly configured pam.conf can lock out users
so that single-user mode becomes necessary for repair. For a description of
setting the order, see How PAM Stacking Works.
PAM Configuration File Syntax
The entries in the configuration file are in the format:
service-name module-type control-flag module-path module-options
- service-name
Name of the service, for example, ftp, login, or passwd. An application can use different service names for the services that the application provides. For example, the Solaris secure shell daemon uses these service names: sshd-none, sshd-password, sshd-kbdint, sshd-pubkey, and sshd-hostbased. The service-name other is a predefined name that is used as a wildcard service-name. If a particular service-name is not found in the configuration file, the configuration for other is used.
- module-type
The type of service, that is, auth, account, session, or password.
- control-flag
Indicates the role of the module in determining the integrated success or failure value for the service. Valid control flags are binding, include, optional, required, requisite, and sufficient. See How PAM Stacking Works for information on the use of these flags.
- module-path
The path to the library object that implements the service. If the pathname is not absolute, the pathname is assumed to be relative to /usr/lib/security/$ISA/. Use the architecture-dependent macro $ISA to cause libpam to look in the directory for the particular architecture of the application.
- module-options
Options that are passed to the service modules. A module's man page describes the options that are accepted by that module. Typical module options include nowarn and debug.
How PAM Stacking Works
When an application calls on the following functions, libpam reads the configuration file /etc/pam.conf
to determine which modules participate in the operation for this service:
If /etc/pam.conf contains only one module for an operation for this service such
as authentication or account management, the result of that module determines the outcome
of the operation. For example, the default authentication operation for the passwd application contains
one module, pam_passwd_auth.so.1:
passwd auth required pam_passwd_auth.so.1
If, on the other hand, there are multiple modules defined for the
service's operation, those modules are said to be stacked and that a PAM stack exists
for that service. For example, consider the case where pam.conf contains the following
entries:
login auth requisite pam_authtok_get.so.1
login auth required pam_dhkeys.so.1
login auth required pam_unix_cred.so.1
login auth required pam_unix_auth.so.1
login auth required pam_dial_auth.so.1
These entries represent a sample auth stack for the login service. To
determine the outcome of this stack, the result codes of the individual modules
require an integration process. In the integration process, the modules are executed in order
as specified in /etc/pam.conf. Each success or failure code is integrated in the overall
result depending on the module's control flag. The control flag can cause early
termination of the stack. For example, a requisite module might fail, or a
sufficient or binding module might succeed. After the stack has been processed, the
individual results are combined into a single, overall result that is delivered to
the application.
The control flag indicates the role that a PAM module plays in determining
access to the service. The control flags and their effects are:
Binding – Success in meeting a binding module's requirements returns success immediately to the application if no previous required modules have failed. If these conditions are met, then no further execution of modules occurs. Failure causes a required failure to be recorded and the processing of modules to be continued.
Include – Adds lines from a separate PAM configuration file to be used at this point in the PAM stack. This flag does not control success or failure behaviors. When a new file is read, the PAM include stack is incremented. When the stack check in the new file finishes, the include stack value is decremented. When the end of a file is reached and the PAM include stack is 0, then the stack processing ends. The maximum number for the PAM include stack is 32.
Optional – Success in meeting an optional module's requirements is not necessary for using the service. Failure causes an optional failure to be recorded.
Required – Success in meeting a required module's requirements is necessary for using the service. Failure results in an error return after the remaining modules for this service have been executed. Final success for the service is returned only if no binding or required modules have reported failures.
Requisite – Success in meeting a requisite module's requirements is necessary for using the service. Failure results in an immediate error return with no further execution of modules. All requisite modules for a service must return success for the function to be able to return success to the application.
Sufficient – If no previous required failures have occurred, success in a sufficient module returns success to the application immediately with no further execution of modules. Failure causes an optional failure to be recorded.
The following two diagrams shows how access is determined in the integration process.
The first diagram indicates how success or failure is recorded for each type
of control flag. The second diagram shows how the integrated value is determined.
Figure 17-2 PAM Stacking: Effect of Control Flags
Figure 17-3 PAM Stacking: How Integrated Value Is Determined
PAM Stacking Example
Consider the following example of an rlogin service that requests authentication.
Example 17-1 Partial Contents of a Typical PAM Configuration File
The pam.conf file in this example has the following contents for rlogin services:
# Authentication management
...
# rlogin service
rlogin auth sufficient pam_rhosts_auth.so.1
rlogin auth requisite pam_authtok_get.so.1
rlogin auth required pam_dhkeys.so.1
rlogin auth required pam_unix_auth.so.1
...When the rlogin service requests authentication, libpam first executes the pam_rhosts_auth(5) module.
The control flag is set to sufficient for the pam_rhosts_auth module. If the pam_rhosts_auth
module is able to authenticate the user, then processing stops and success is
returned to the application.
If the pam_rhosts_auth module fails to authenticate the user, then the next PAM
module, pam_authtok_get(5) is executed. The control flag for this module is set to
requisite. If pam_authtok_get fails, then the authentication process ends and the failure
is returned to rlogin.
If pam_authtok_get succeeds, then the next two modules, pam_dhkeys(5) and pam_unix_auth(5), are
executed. Both modules have the associated control flags that are set to required
so that the process continues regardless of whether an individual failure is returned. After
pam_unix_auth is executed, no modules for rlogin authentication remain. At this point,
if either pam_dhkeys or pam_unix_auth has returned a failure, the user is denied
access through rlogin.
