pam_sm(3)

Interface Overview

The PAM service module interface consists of functions which can be grouped into four categories. The names for all the authentication library functions start with pam_sm. The only difference between the pam_*() interfaces and their corresponding pam_sm_*() interfaces is that all the pam_sm_*() interfaces require extra parameters to pass service specific options to the shared modules. They are otherwise identical.

The first category contains functions to authenticate an individual user (pam_sm_authenticate(3)) and to set the credentials of the user (pam_sm_setcred(3)). These back-end functions implement the functionality of pam_authenticate(3) and pam_setcred(3), respectively.

The second category contains functions to do account management (pam_sm_acct_mgmt(3)). This includes checking for password aging and access-hour restrictions. This back-end function implements the functionality of pam_acct_mgmt(3).

The third category contains functions to perform session management (pam_sm_open_session(3) and pam_sm_close_session(3)) after access to the system has been granted. These back-end functions implement the functionality of pam_open_session(3) and pam_close_session(3), respectively.

The fourth category consists a function to change authentication tokens (pam_sm_chauthtok(3)). This back-end function implements the functionality of pam_chauthtok(3).

Stateful Interface

A sequence of calls sharing a common set of state information is referred to as an authentication transaction. An authentication transaction begins with a call to pam_start(). pam_start() allocates space, performs various initialization activities, and assigns an authentication handle to be used for subsequent calls to the library. Note that the service modules do not get called or initialized when pam_start() is called. The modules are loaded and the symbols resolved upon first use of that function.

The PAM handle keeps certain information about the transaction that can be accessed through the pam_get_item() API. Though the modules can also use pam_set_item() to change any of the item information, it is recommended that nothing be changed except PAM_AUTHTOK and PAM_OLDAUTHTOK.

If the modules want to store any module specific state information then they can use the pam_set_data(3) function to store that information with the PAM handle. The data should be stored with a name which is unique across all modules and module types. Some modules use this technique to share data across two different module types.

For example, during the call to pam_authenticate(), the UNIX module may store the authentication status (success or reason for failure) in the handle, using a unique name. This information is intended for use by pam_setcred().

During the call to pam_acct_mgmt(), the account modules may store data in the handle to indicate which passwords have aged. This information is intended for use by pam_chauthtok().

The module can also store a cleanup function associated with the data. The PAM framework calls this cleanup function, when the application calls pam_end() to close the transaction.

Interaction With the User

The PAM service modules do not communicate directly with the user; instead they rely on the application to perform all such interactions. The application passes a pointer to the function, conv(), along with any associated application data pointers, through the pam_conv structure when it initiates an authentication transaction (via a call to pam_start()). The service module will then use the function, conv(), to prompt the user for data, output error messages, and display text information. Refer to pam_start(3) for more information. The modules are responsible for the localization of all messages to the user.

Conventions

By convention, applications that need to prompt for a user name should call pam_set_item() and set the value of PAM_USER_PROMPT before calling pam_authenticate(). The service module's pam_sm_authenticate() function will then call pam_get_user() to prompt for the user name. Note that certain PAM service modules (such as a smart card module) may override the value of PAM_USER_PROMPT and pass in their own prompt.

Though the PAM framework enforces no rules about the module's names, location, options and such, there are certain conventions that all module providers are expected to follow.

By convention, the modules should be located in the /usr/lib/security directory.

The modules are named libpam_service_name.1 (for example, libpam_unix.1 module).

For every such module, there should be a corresponding manual page in section 5 which should describe the service_name it supports, the functionality of the module, along with the options it supports. The dependencies should be clearly identified to the system administrator. For example, it should be made clear whether this module is a stand-alone module or depends upon the presence of some other module. One should also specify whether this module should come before or after some other module in the stack.

By convention, the modules should support the following options:

In addition, it is recommended that the auth and the password module support the following options:

If an unsupported option is passed to the modules, it should syslog the error at LOG_ERR level.

The permission bits on the service module should be set such that it is not writable by either "group" or "other". The PAM framework will not load the module if the above permission rules are not followed.