pam_sm_chauthtok(3)

NAME
     pam_sm_chauthtok - Service provider implementation for pam_chauthtok

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

     #include <security/pam_appl.h>
     #include <security/pam_modules.h>

     int pam_sm_chauthtok(pam_handle_t *pamh, const int flags);


DESCRIPTION
     In  response  to  a  call  to  pam_chauthtok(3)  the  PAM  framework  calls
     pam_sm_chauthtok(3) 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  par-
     ticular user referenced by the authentication handle, pamh.

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

            PAM_SILENT                    The password service should not gener-
                                          ate any messages

            PAM_CHANGE_EXPIRED_AUTHTOK    The  password  service should only up-
                                          date those passwords that  have  aged.
                                          If  this flag is not passed, the pass-
                                          word service should update  all  pass-
                                          words.

            PAM_PRELIM_CHECK              The  password service should only per-
                                          form 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 the various available op-
     tions.


NOTES
     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  pass-
     word.  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 eged of expired.  If the password has
     aged or expired, then the service module should proceed to update the pass-
     word.  If the status indicates that the password has not yet  aged/expired,
     then the password module should return PAM_IGNORE.


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

            PAM_PERM_DENIED                   No permission

            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  dis-
                                              abled

            PAM_USER_UNKNOWN                  User unknown to password service

            PAM_TRY_AGAIN                     Preliminary check by password ser-
                                              vice failed

SEE ALSO
     pam(3), pam_chauthtok(3), pam.conf(4)