pam_sm(3)                                                         pam_sm(3)




 NAME    [Toc]    [Back]
      pam_sm - PAM Service Module APIs

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

      #include <security/pam_modules.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.

      This manual page gives an overview of the PAM APIs for the service
      modules.

    Interface Overview    [Toc]    [Back]
      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 only difference between the
      pam_*() interfaces and their corresponding 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.

      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_sessio
) 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),
      respectively.



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






 pam_sm(3)                                                         pam_sm(3)




      The fourth category consists a function to change authentication
      tokens (pam_sm_chauthtok(3)).  This back-end function implements the
      functionality of pam_chauthtok(3).

    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 an
      authentication 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_OLDAUTHTOK.

      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 pam_authenticate(), 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 pam_setcred().

      During the call to pam_acct_mgmt(), the account modules may store data
      in the handle to indicate which passwords have aged.  This information
      is intended for use by pam_chauthtok().

      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    [Toc]    [Back]
      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
      structure 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.
      The modules are responsible for the localization of all messages to
      the user.



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






 pam_sm(3)                                                         pam_sm(3)




    Conventions    [Toc]    [Back]
      By convention, applications that need to prompt for a user name should
      call pam_set_item() and set the value of PAM_USER_PROMPT before
      calling pam_authenticate().  The service module's
      pam_sm_authenticate() function will then call pam_get_user() to prompt
      for the user name. Note that certain PAM service modules (such as a
      smart card module) may override the value of PAM_USER_PROMPT 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 /usr/lib/security
      directory.

      The modules are named libpam_service_name.1 (for example,
      libpam_unix.1 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 administrator.
      For example, it should be made clear whether this module is a standalone
 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:

      debug          Syslog debugging information at LOG_DEBUG level.  Be
                     careful as to not log any sensitive information 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 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.

      try_first_pass Instead of prompting the user for the password, use the
                     user's initial password (entered when the user was



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






 pam_sm(3)                                                         pam_sm(3)




                     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.

      use_psd        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 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.

 APPLICATION USAGE    [Toc]    [Back]
      Refer to pam(3) for information on thread-safety of PAM interfaces.

 ERRORS    [Toc]    [Back]
      If there are any errors, the modules should log them using syslog(3C)
      at the LOG_ERR level.

 RETURN VALUE    [Toc]    [Back]
      The PAM service module functions may return any of the PAM error
      numbers 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
      sufficient.  This error number is normally returned when the module
      does not want to deal with the given user at all.

 SEE ALSO    [Toc]    [Back]
      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).


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