# pam_sm_chauthtok

## NAME



           pam_sm_chauthtok - PAM service function for authentication token
           management
    


## SYNOPSIS



           **#include <security/pam_modules.h>**
    
           **int pam_sm_chauthtok(pam_handle_t ***_pamh_**, int** _flags_**, int** _argc_**,**
                                **const char ****_argv_**);**
    


## DESCRIPTION



           The **pam_sm_chauthtok** function is the service module's
           implementation of the pam_chauthtok(3) interface.
    
           This function is used to (re-)set the authentication token of the
           user.
    
           Valid flags, which may be logically OR'd with _PAM_SILENT_ , are:
    
           PAM_SILENT
               Do not emit any messages.
    
           PAM_CHANGE_EXPIRED_AUTHTOK
               This argument indicates to the module that the user's
               authentication token (password) should only be changed if it
               has expired. This flag is optional and _must_ be combined with
               one of the following two flags. Note, however, the following
               two options are _mutually exclusive_.
    
           PAM_PRELIM_CHECK
               This indicates that the modules are being probed as to their
               ready status for altering the user's authentication token. If
               the module requires access to another system over some network
               it should attempt to verify it can connect to this system on
               receiving this flag. If a module cannot establish it is ready
               to update the user's authentication token it should return
               **PAM_TRY_AGAIN** , this information will be passed back to the
               application.
    
               If the control value _sufficient_ is used in the password stack,
               the _PAM_PRELIM_CHECK_ section of the modules following that
               control value is not always executed.
    
           PAM_UPDATE_AUTHTOK
               This informs the module that this is the call it should change
               the authorization tokens. If the flag is logically OR'd with
               **PAM_CHANGE_EXPIRED_AUTHTOK** , the token is only changed if it
               has actually expired.
    
           The PAM library calls this function twice in succession. The first
           time with **PAM_PRELIM_CHECK** and then, if the module does not return
           **PAM_TRY_AGAIN** , subsequently with **PAM_UPDATE_AUTHTOK**. It is only on
           the second call that the authorization token is (possibly)
           changed.
    


## RETURN VALUES



           PAM_AUTHTOK_ERR
               The module was unable to obtain the new authentication token.
    
           PAM_AUTHTOK_RECOVERY_ERR
               The module was unable to obtain the old authentication token.
    
           PAM_AUTHTOK_LOCK_BUSY
               Cannot change the authentication token since it is currently
               locked.
    
           PAM_AUTHTOK_DISABLE_AGING
               Authentication token aging has been disabled.
    
           PAM_PERM_DENIED
               Permission denied.
    
           PAM_TRY_AGAIN
               Preliminary check was unsuccessful. Signals an immediate
               return to the application is desired.
    
           PAM_SUCCESS
               The authentication token was successfully updated.
    
           PAM_USER_UNKNOWN
               User unknown to password service.
    


* * *