NAME [Toc] [Back]
pam_sm_chauthtok - Service provider implementation for pam_chauthtok
SYNOPSIS [Toc] [Back]
cc [ flag ... ] file ... -lpam [ library ... ]
int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int argc,
const char **argv);
DESCRIPTION [Toc] [Back]
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
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
PAM_UPDATE_AUTHTOK The password service should update
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
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
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
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 [Toc] [Back]
Refer to pam(3) for information on thread-safety of PAM interfaces.
NOTES [Toc] [Back]
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 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
If a user's password has aged or expired, a PAM account module could
save this information as state in the authentication handle, pamh,
using pam_set_data(). The related password management module could
retrieve this information using pam_get_data() to determine whether or
not it should prompt the user to update the password for this
RETURN VALUES [Toc] [Back]
Upon successful completion, PAM_SUCCESS must be returned. The
following values may also be returned:
PAM_PERM_DENIED No permission.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
PAM_AUTHTOK_ERR Authentication token manipulation
PAM_AUTHTOK_RECOVERY_ERR Old authentication token cannot be
PAM_AUTHTOK_LOCK_BUSY Authentication token lock busy.
PAM_AUTHTOK_DISABLE_AGING Authentication token aging
PAM_USER_UNKNOWN User unknown to password service.
PAM_TRY_AGAIN Preliminary check by password
SEE ALSO [Toc] [Back]
pam(3), pam_chauthtok(3), pam.conf(4).
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003 [ Back ]