pam(3)

NAME
     PAM - Pluggable Authentication Module

SYNOPSIS
     #include <security/pam_appl.h>

     cc [ flag ... ] file ...  -lpam [ library ... ]

DESCRIPTION
     PAM gives system administrators the flexibility of choosing any authentica-
     tion service available on the system to perform authentication.  The frame-
     work  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  multiple
     authentication service modules.  The PAM interface library is the layer im-
     plementing 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.

   Interface Overview
     The PAM library interface consists of functions which can be  grouped  into
     five  categories.   The  names for all the authentication library functions
     start with pam_.

     The first category contains functions for establishing and  terminating  an
     authentication  activity  (pam_start(3) and pam_end(3)), functions to main-
     tain module specific data (pam_[sg]et_data(3)), functions to maintain state
     information (pam_[sg]et_item(3)), and a function to return error status in-
     formation (pam_strerror(3)).

     The second category contains functions to authenticate an  individual  user
     (pam_authenticate(3))  and  to  set  the  credentials of the user (pam_set-
     cred(3)).

     The  third  category  contains   functions   to   do   account   management
     (pam_acct_mgmt(3)).   This includes checking for password aging and access-
     hour restrictions.

     The fourth  category  contains  functions  to  perform  session  management
     (pam_open_session(3)  and (pam_close_session(3)) after access to the system
     has been granted.

     The fifth category consists of functions to  change  authentication  tokens
     (pam_chauthtok(3)).   An  authentication token is the object used to verify
     the identity of the user.  In UNIX, an authentication  token  is  a  user's
     password.

     All the pam_*() interfaces are implemented through the library libpam.  For
     each   of  the  categories  listed  above,  excluding  the  first  category
     (pam_start(), pam_end(), pam_[sg]et_data(), pam_[sg]et_item(), and pam_str-
     error()) there exists a dynamically loadable shared  module  that  provides
     the  appropriate  service  layer functionality upon demand.  The functional
     entry points in the service layer start with the pam_sm_ prefix.  The  only
     difference  between  the pam_sm_*() interfaces and their corresponding pam_
     interfaces is that all the pam_sm_*() interfaces require  extra  parameters
     to  pass  service  specific options to the shared modules.  Please refer to
     pam_sm(3) for an overview of the PAM service module APIs.


   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 a PAM authentication handle to be
     used for subsequent calls to the library.

     After initiating an authentication  transaction,  applications  can  invoke
     pam_authenticate()  to  authenticate a particular user, and pam_acct_mgmt()
     to perform system entry management (the application may want  to  determine
     if the user's password has expired).

     If the user has been successfully authenticated, applications call pam_set-
     cred()  to set any user credentials associated with the authentication ser-
     vice.  The calls to pam_start(), pam_authenticate() and pam_setcred()  must
     be  made with the same authentication handle returned by pam_start().  This
     is necessary because during the call to pam_authenticate(), service modules
     may store module-specific data in the handle that is intended  for  use  by
     pam_setcred().

     To  perform  session management, applications call pam_open_session().  For
     example, the system may want to store the total time for the session.   The
     function pam_close_session() closes the current session.

     When  necessary, applications can call pam_get_item() and pam_set_item() to
     access and update specific authentication  information.   Such  information
     may include the current username.

     To  terminate  an  authentication transaction, the application simply calls
     pam_end(), which frees previously allocated space used to store authentica-
     tion information.

   Application - Authentication Service Interactive Interface
     The authentication service in PAM does not communicate  directly  with  the
     user;  instead  it  relies  on the application to perform all such interac-
     tions.  The application passes a pointer to  the  function,  conv(),  along
     with any associated application data pointers, through a pam_conv structure
     to  the authentication service when it initiates an authentication transac-
     tion (via a call to pam_start()).  The service 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.


   Stacking Multiple Schemes
     The PAM architecture enables authentication by multiple authentication ser-
     vices through stacking.  System entry applications, such as login(1), stack
     multiple service modules to authenticate users with multiple authentication
     services.  The order in which authentication service modules are stacked is
     specified in the configuration file, pam.conf(4).  A  system  administrator
     determines this ordering, and also determines whether the same password can
     be used for all authentication services.


   Administrative Interface
     The  authentication  libraries, /usr/lib/libpam.so.1 and /usr/lib/libpam.a,
     implement the framework interface.  Various authentication services are im-
     plemented by their own loadable modules whose paths are  specified  through
     the pam.conf(4) file.

RETURN VALUES
     The PAM functions may return one of the following generic values, or one of
     the values defined in the specific man pages:

            PAM_SUCCESS           Successful function return

            PAM_OPEN_ERR          Dlopen()  failure  when  dynamically loading a
                                  service module

            PAM_SYMBOL_ERR        Symbol not found

            PAM_SERVICE_ERR       Error in service module

            PAM_SYSTEM_ERR        System error

            PAM_BUF_ERR           Memory buffer error

            PAM_CONV_ERR          Conversation failure

            PAM_PERM_DENIED       Permission denied


SEE ALSO
     pam_authenticate(3),         pam_open_session(3),         pam_chauthtok(3),
     pam_set_item(3),  pam_setcred(3), pam_sm(3), pam_start(3), pam_strerror(3),
     pam.conf(4)

WARNING
     Please note that all the PAM APIs and the data structures  are  subject  to
     change without notice.