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.