hpux man page for pam_sm

pam_sm(3)						     Library Functions Manual							 pam_sm(3)

NAME
       pam_sm - PAM Service Module APIs

SYNOPSIS
       [ flag ... ] file ...  [ library ... ]

DESCRIPTION
       PAM  gives  system administrators the flexibility of choosing any authentication 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 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 modules.

   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 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), respec-
       tively.

       The fourth category consists a function to change authentication tokens (pam_sm_chauthtok(3)).  This back-end function implements the func-
       tionality 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 transac-
       tion begins with a call to 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 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 authentication 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 associated 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  func-
       tion will then call to prompt for the user name. Note that certain PAM service 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
       module 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
       functionality of the module, along with the options it supports.  The dependencies should be clearly identified to the  system  administra-
       tor.   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 information 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 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.

       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 passwords only if necessary.

       Instead of prompting the user for the password,
		      prompt  for  the user's PIN (Personal Identification Number) 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 numbers specified in the specific man pages.  It can also return  a  error
       number  to  mean that the PAM framework should ignore this module regardless 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 ALSO
       pam(3),	pam_start(3),  pam_set_item(3),  pam_get_user(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), pam_user.conf(4).

																	 pam_sm(3)