pam_sm(3)pam_sm(3)NAME
PAM - PAM Service Module APIs
SYNOPSIS
#include <security/pam_appl.h>
#include <security/pam_modules.h>
cc [ flag ... ] file ... -lpam [ 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, libpam, consists of an interface library and multi‐
ple authentication service modules. The PAM interface library is the
layer implementing the Application Programming Interface (API). The
authentication service modules are a set of dynamically loadable
objects invoked by the PAM API to provide a particular type of user
authentication.
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 pam_sm.
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 of functions to change authentication
tokens (pam_sm_chauthtok(3)) and to manipulate authentication token
attributes (pam_sm_set_authtokattr(3)) and (pam_sm_get_authtokattr(3)).
These back-end functions implement the functionality of pam_chauth‐
tok(3), pam_set_authtokattr(3), and pam_get_authtokattr(3), respec‐
tively.
The only difference between the pam_*() interfaces and their corre‐
sponding 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.
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 pam_start(). pam_start() allocates space,
performs various initialization activities, and assigns an authentica‐
tion 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_OLDAUTH‐
TOK.
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. For example,
SUNW_PAM_DCE_AUTH_userid can be used as a name by the DCE module to
store information about the state of user's authentication. Some mod‐
ules use this technique to share data across two different module
types.
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 struc‐
ture 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.
CONVENTIONS
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 /usr/lib/security
directory. Additional modules may be located in /opt/<pkg>/lib.
By convention, the modules are named pam_<service_name>_<mod‐
ule_type>.so.1. If the given module implements more than one module
type (for example, pam_unix.so.1 module), then the module_type suffix
should be dropped.
For every such module, there should be a corresponding manual page in
section 5 which should describe the module_type 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.
Though not required, it is recommended that the modules support the
following options:
debug Syslog debugging information at LOG_DEBUG level.
Be careful as to not log any sensitive informa‐
tion such as passwords.
nowarn 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:
use_first_pass Instead of prompting the user for the password,
use the user's initial password (entered when the
user was authenticated to the first authentica‐
tion module in the stack) for authentication. If
the passwords do not match, or if no password has
been entered, return failure and do not prompt
the user for a password. Support for this scheme
allows the user to type only one password for
multiple schemes.
try_first_pass Instead of prompting the user for the password,
use the user's initial password (entered when the
user was authenticated to the first authentica‐
tion 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, DCE, etc.) is being requested. Support for
this scheme allows the user to try to use only
one password for multiple schemes, and type mul‐
tiple passwords only if necessary.
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.
ERROR LOGGING
If there are any errors, the modules should log them using syslog(3) at
the LOG_ERR level.
RETURN VALUES
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
PAM_IGNORE error number to mean that the PAM framework should ignore
this module regardless of whether it is required, optional or suffi‐
cient. 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_authenticate(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)
12 September 1995 pam_sm(3)
