pam_sm_chauthtok.3 (2010 09)

p
pam_sm_chauthtok(3) 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, int flags, int argc,
const char **argv);
DESCRIPTION
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 pass-
words 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.
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
Refer to pam(3) for information on thread-safety of PAM interfaces.
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 prelim-
inary 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 applica-
tion. If all password modules pass the preliminary check, the PAM framework invokes the password ser-
vices 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.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1