pam_sm_chauthtok(3)                                     pam_sm_chauthtok(3)




 NAME    [Toc]    [Back]
      pam_sm_chauthtok - Service provider implementation for pam_chauthtok

 SYNOPSIS    [Toc]    [Back]
      cc [ flag ... ] file ...  -lpam [ library ... ]

      #include <security/pam_appl.h>

      #include <security/pam_modules.h>

      int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int argc,
           const char **argv);

 DESCRIPTION    [Toc]    [Back]
      In response to a call to pam_chauthtok() the PAM framework calls
      pam_sm_chauthtok() from the modules listed in the pam.conf(4) file.
      The password management provider supplies the back-end functionality
      for this interface function.

      pam_sm_chauthtok() changes the authentication token associated with a
      particular user referenced by the authentication handle, pamh.

      The following flag may be passed in to pam_chauthtok():

      PAM_SILENT                    The password service should not generate
                                    any messages.

      PAM_CHANGE_EXPIRED_AUTHTOK    The password service should only update
                                    those passwords that have aged.  If this
                                    flag is not passed, the password service
                                    should update all passwords.

      PAM_PRELIM_CHECK              The password service should only perform
                                    preliminary checks.  No passwords should
                                    be updated.

      PAM_UPDATE_AUTHTOK            The password service should update
                                    passwords.

      Note that PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK can not be set at
      the same time.

      Upon successful completion of the call, the authentication token of
      the user will be ready for change or will be changed (depending upon
      the flag) in accordance with the authentication scheme configured
      within the system.

      The argc argument represents the number of module options passed in
      from the configuration file pam.conf(4).  argv specifies the module
      options, which are interpreted and processed by the password
      management service.  Please refer to the specific module man pages for



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






 pam_sm_chauthtok(3)                                     pam_sm_chauthtok(3)




      the various available options.

      It is the responsibility of pam_sm_chauthtok() to determine if the new
      password meets certain strength requirements.  pam_sm_chauthtok() may
      continue to re-prompt the user (for a limited number of times) for a
      new password until the password entered meets the strength
      requirements.

      Before returning, pam_sm_chauthtok() should call pam_get_item() and
      retrieve both PAM_AUTHTOK and PAM_OLDAUTHTOK.  If both are NULL,
      pam_sm_chauthtok() should set them to the new and old passwords as
      entered by the user.

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

 NOTES    [Toc]    [Back]
      The PAM framework invokes the password services twice.  The first time
      the modules are invoked with the flag, PAM_PRELIM_CHECK.  During this
      stage, the password modules should only perform preliminary checks
      (ping remote name services to see if they are ready for updates, for
      example).  If a password module detects a transient error (remote name
      service temporarily down, for example) it should return PAM_TRY_AGAIN
      to the PAM framework, which will immediately return the error back to
      the application.  If all password modules pass the preliminary check,
      the PAM framework invokes the password services again with the flag,
      PAM_UPDATE_AUTHTOK.  During this stage, each password module should
      proceed to update the appropriate password.  Any error will again be
      reported back to application.

      If a service module receives the flag, PAM_CHANGE_EXPIRED_AUTHTOK, it
      should check whether the password has aged or expired.  If the
      password has aged or expired, then the service module should proceed
      to update the password.  If the status indicates that the password has
      not yet aged/expired, then the password module should return
      PAM_IGNORE.

      If a user's password has aged or expired, a PAM account module could
      save this information as state in the authentication handle, pamh,
      using pam_set_data().  The related password management module could
      retrieve this information using pam_get_data() to determine whether or
      not it should prompt the user to update the password for this
      particular module.

 RETURN VALUES    [Toc]    [Back]
      Upon successful completion, PAM_SUCCESS must be returned.  The
      following values may also be returned:

      PAM_PERM_DENIED                     No permission.





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






 pam_sm_chauthtok(3)                                     pam_sm_chauthtok(3)




      PAM_AUTHTOK_ERR                     Authentication token manipulation
                                          error.

      PAM_AUTHTOK_RECOVERY_ERR            Old authentication token cannot be
                                          recovered.

      PAM_AUTHTOK_LOCK_BUSY               Authentication token lock busy.

      PAM_AUTHTOK_DISABLE_AGING           Authentication token aging
                                          disabled.

      PAM_USER_UNKNOWN                    User unknown to password service.

      PAM_TRY_AGAIN                       Preliminary check by password
                                          service failed.

 SEE ALSO    [Toc]    [Back]
      pam(3), pam_chauthtok(3), pam.conf(4).


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