pam_chauthtok(3)

NAME
     pam_chauthtok - updating authentication tokens


SYNOPSIS
     #include <security/pam_appl.h>

     int pam_chauthtok(pam_handle_t *pamh, int  flags);



DESCRIPTION
     pam_chauthtok

     Use this function to rejuvenate the authentication tokens (passwords
     etc.) of an applicant user.

     Note, the application should not pre-authenticate the user, as this is
     performed (if required) by the PAM framework.

     The flags argument can optionally take the value,
     PAM_CHANGE_EXPIRED_AUTHTOK.  In such cases the framework is only required
     to update those authentication tokens that have expired. Without this
     argument, the framework will attempt to obtain new tokens for all
     configured authentication mechanisms. The details of the types and number
     of such schemes should not concern the calling application.


RETURN VALUE
     A successful return from this function will be indicated with
     PAM_SUCCESS.

     Specific errors of special interest when calling this function are

     PAM_AUTHTOK_ERROR - a valid new token was not obtained

     PAM_AUTHTOK_RECOVERY_ERR - old authentication token was not available

     PAM_AUTHTOK_LOCK_BUSY - a resource needed to update the token was locked
     (try again later)

     PAM_AUTHTOK_DISABLE_AGING - one or more of the authentication modules
     does not honor authentication token aging

     PAM_TRY_AGAIN - one or more authentication mechanism is not prepared to
     update a token at this time

     In general other return values may be returned. They should be treated as
     indicating failure.
ERRORS
     May be translated to text with pam_strerror(3).


CONFORMING TO
     DCE-RFC 86.0, October 1995.


BUGS
     none known.


SEE ALSO
     pam_start(3), pam_authenticate(3), pam_setcred(3), pam_get_item(3),
     pam_strerror(3) and pam(8).

     Also, see the three PAM Guides, for System administrators, module
     developers, and application developers.