pam(3)                                                               pam(3)




 NAME    [Toc]    [Back]
      PAM - Pluggable Authentication Module

 SYNOPSIS    [Toc]    [Back]
      #include <security/pam_appl.h>

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

 DESCRIPTION    [Toc]    [Back]
      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, libpam, 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.

    Interface Overview    [Toc]    [Back]
      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
      maintain 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 information (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_setcred(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_sessio
) 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, even when using a smart card, because the PAM
      Framework retrieves the password from the smart card.




 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 pam(3)                                                               pam(3)




      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_strerror()) 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    [Toc]    [Back]
      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_setcred() to set any user credentials associated with the
      authentication service.  Within one authentication transaction
      (between pam_start() and pam_end()), all calls to the PAM interface
      should be made with the same authentication handle returned by
      pam_start().  This is necessary because certain service modules may
      store module-specific data in the handle that is intended for use by
      other modules.  For example, during the call to pam_authenticate(),
      service modules may store 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
      authentication information.

    Application - Authentication Service Interactive Interface    [Toc]    [Back]
      The authentication service in PAM does not communicate directly with
      the user; instead it relies on the application to perform all such
      interactions.  The application passes a pointer to the function,



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 pam(3)                                                               pam(3)




      conv(), along with any associated application data pointers, through a
      pam_conv structure to the authentication service when it initiates an
      authentication transaction (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    [Toc]    [Back]
      The PAM architecture enables authentication by multiple authentication
      services 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    [Toc]    [Back]
      Various authentication services are implemented by their own loadable
      modules whose paths are specified through the pam.conf(4) file.

    User configuration    [Toc]    [Back]
      The system administrator can determine a policy by user. These are
      specified in the configuration files: pam.conf(4), pam_user.conf(4).

 APPLICATION USAGE    [Toc]    [Back]
      All the pam_*() interfaces implemented in the PAM framework, libpam,
      are thread-safe.  A cancellation point may occur while a thread is
      executing any of these interfaces.  They are not cancel-safe, asynccancel-safe,
 nor async-signal-safe.  However, system administrators
      should be aware that the pam_authenticate(), pam_open_session(),
      pam_close_session(), pam_chauthtok(), pam_setcred(), and
      pam_acct_mgmt() interfaces invoke the corresponding pam_sm_*()
      interfaces implemented in the dynamically loadable modules specified
      in the configuration file, pam.conf(4).  Therefore, the thread-safety
      of these interfaces depends on the implementation of the service
      module.  Refer to module specific man pages such as pam_unix(5) for
      this information.

 RETURN VALUES    [Toc]    [Back]
      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            Failure in dynamically loading a service
                              module.

      PAM_SYMBOL_ERR          Symbol not found.





 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003






 pam(3)                                                               pam(3)




      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.

 WARNINGS    [Toc]    [Back]
      Please note that all the PAM APIs and the data structures are subject
      to change without notice.

 SEE ALSO    [Toc]    [Back]
      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), pam_user.conf(4).


 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003