PAM Stacking

When an application calls one of the following functions, the PAM framework reads the PAM configuration files to determine which modules implement this application's PAM service name:

• pam_authenticate(3PAM)

• pam_acct_mgmt(3PAM)

• pam_setcred(3PAM)

• pam_open_session(3PAM)

• pam_close_session(3PAM)

• pam_chauthtok(3PAM)

If the configuration files contain only one module, 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, in the /etc/pam.d/passwd file.

auth required           pam_passwd_auth.so.1

If, on the other hand, multiple modules implement a service, those modules are said to be stacked, that is, a PAM stack exists for that service name. For example, consider the entries in a sample /etc/pam.d/login service:

auth definitive         pam_user_policy.so.1
auth requisite          pam_authtok_get.so.1
auth required           pam_unix_auth.so.1
auth required           pam_dhkeys.so.1
auth required           pam_unix_cred.so.1
auth required           pam_dial_auth.so.1

These entries create an auth stack for the login service name. 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 their order in the file. Each success or failure code is integrated in to the overall result according to the module's control flag. The control flag can cause early termination of the stack. For example, the failure of a requisite or definitive module terminates the stack. If there are no previous failures, the success of a sufficient, definitive, or binding module also terminates the stack. After the stack is processed, the individual results are combined into a single, overall result that is delivered to the application. For a graphic view of the flow, see Figure 1–2 and Figure 1–3.

The control flag indicates the role that a PAM module plays in determining success or failure. 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 failures have been recorded. 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.

• Definitive – Success in meeting a definitive module's requirements returns success immediately to the application if no previous failures have been recorded.

  If a previous failure has been recorded, that failure is immediately returned to the application with no further execution of modules. Failure results in an immediate error return with no further execution of modules.

• 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 the stack to succeed. Final success for the stack is returned only if no binding or required modules have reported failures.

  Failure results in an error return after the remaining modules for this service have been executed.

• Requisite – Success in meeting a requisite module's requirements is necessary for the stack to succeed. All requisite modules in the stack must return success for the stack to be able to return success to the application.

  Failure results in an immediate error return with no further execution of modules.

• Sufficient – If no previous required failures have been recorded, success in a sufficient module returns success immediately with no further execution of modules.

  Failure causes an optional failure to be recorded.

The following two connected diagrams show how a result is determined in the integration process.

• The first diagram shows how success or failure is recorded for each type of control flag. The results are shown in the second diagram.

• The second diagram shows how the integrated value is determined. Optional failure and required failure return failure, and success returns success. The application determines how to handle these return codes.

Figure 1-2  PAM Stacking: Effect of Control Flags

Figure 1-3  PAM Stacking: How Integrated Value Is Determined