pam_sm_chauthtok(3)pam_sm_chauthtok(3)NAMEpam_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
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 the various
available options.
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 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 eged of 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.
RETURN VALUES
Upon successful completion, PAM_SUCCESS must be returned. The follow‐
ing values may also be returned:
PAM_PERM_DENIED No permission
PAM_AUTHTOK_ERR Authentication token manipula‐
tion error
PAM_AUTHTOK_RECOVERY_ERR Old authentication token can‐
not 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 ser‐
vice
PAM_TRY_AGAIN Preliminary check by password
service failed
SEE ALSOpam(3), pam_chauthtok(3), pam.conf(4)
19 October 1995 pam_sm_chauthtok(3)
