pam_sm(3)pam_sm(3)NAMEpam_sm - PAM Service Module APIs
SYNOPSIS
[ flag ... ] file ... [ library ... ]
DESCRIPTION
PAM gives system administrators the flexibility of choosing any authen‐
tication service available on the system to perform authentication.
The framework also allows new authentication service modules to be
plugged in and made available without modifying the applications.
The PAM framework, consists of an interface library and multiple
authentication service modules. The PAM interface library is the layer
implementing the Application Programming Interface (API). The authen‐
tication service modules are a set of dynamically loadable objects
invoked by the PAM API to provide a particular type of user authentica‐
tion.
This manual page gives an overview of the PAM APIs for the service mod‐
ules.
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 The only difference between the interfaces
and their corresponding interfaces is that all the interfaces require
extra parameters to pass service specific options to the shared mod‐
ules. 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 function‐
ality 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 func‐
tionality 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), respec‐
tively.
The fourth category consists a function to change authentication tokens
(pam_sm_chauthtok(3)). This back-end function implements the function‐
ality 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 trans‐
action begins with a call to allocates space, performs various initial‐
ization 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 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 API. Though the modules can also use to change
any of the item information, it is recommended that nothing be changed
except and
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 the UNIX module may store the authenti‐
cation status (success or reason for failure) in the handle, using a
unique name. This information is intended for use by
During the call to the account modules may store data in the handle to
indicate which passwords have aged. This information is intended for
use by
The module can also store a cleanup function associated with the data.
The PAM framework calls this cleanup function, when the application
calls 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, along with any asso‐
ciated application data pointers, through the structure when it initi‐
ates an authentication transaction (via a call to The service module
will then use the function, 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 and set the value of before calling The service module's function
will then call to prompt for the user name. Note that certain PAM ser‐
vice modules (such as a smart card module) may override the value of
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 mod‐
ule providers are expected to follow.
By convention, the modules should be located in the directory.
The modules are named (for example, module).
For every such module, there should be a corresponding manual page in
section 5 which should describe the service_name it supports, the func‐
tionality 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:
Syslog debugging information at
level. Be careful as to not log any sensitive informa‐
tion such as passwords.
Turn off warning messages such as "password is
about to expire"
In addition, it is recommended that the auth and the password module
support the following options:
Instead of prompting the user for the password,
use the user's initial password (entered when the user
was authenticated to the first authentication module in
the stack) for authentication. If the passwords do not
match, or if no password has been entered, return fail‐
ure and do not prompt the user for a password. Support
for this scheme allows the user to type only one pass‐
word for multiple schemes.
Instead of prompting the user for the password,
use the user's initial password (entered when the user
was authenticated to the first authentication module in
the stack) for authentication. If the passwords do not
match, or if no password has been entered, prompt the
user for a password after identifying which type of
password (ie. UNIX, etc.) is being requested. Support
for this scheme allows the user to try to use only one
password for multiple schemes, and type multiple pass‐
words only if necessary.
Instead of prompting the user for the password,
prompt for the user's PIN (Personal Identification Num‐
ber) associated with their smart card. This allows the
smart card to be accessed, from which the password can
be retrieved. With this option the user must plug their
smart card in the smart card reader connected to their
system.
If an unsupported option is passed to the modules, it should syslog the
error at 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.
APPLICATION USAGE
Refer to pam(3) for information on thread-safety of PAM interfaces.
ERRORS
If there are any errors, the modules should log them using syslog(3C)
at the level.
RETURN VALUE
The PAM service module functions may return any of the PAM error num‐
bers specified in the specific man pages. It can also return a error
number to mean that the PAM framework should ignore this module regard‐
less of whether it is required, optional or sufficient. This error
number is normally returned when the module does not want to deal with
the given user at all.
SEE ALSOpam(3), pam_start(3), pam_set_item(3), pam_get_user(3), pam_authenti‐
cate(3), pam_open_session(3), pam_setcred(3), pam_chauthtok(3),
pam_strerror(3), pam_sm_authenticate(3), pam_sm_open_session(3),
pam_sm_setcred(3), pam_sm_chauthtok(3), pam.conf(4), pam_user.conf(4).
pam_sm(3)
