pam_chauthtok(3PAM) PAM Library Functions pam_chauthtok(3PAM)NAME
pam_chauthtok - perform password related functions within the PAM framework
SYNOPSIS
cc [ flag ... ] file ... -lpam [ library ... ]
#include <security/pam_appl.h>
int pam_chauthtok(pam_handle_t *pamh, const int flags);
DESCRIPTION
The pam_chauthtok() function is called to change the authentication token associated with a particular user referenced by the authentica-
tion 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, all pass-
word services should update their passwords.
PAM_NO_AUTHTOK_CHECK The password service should not perform conformance checks on the password entered.
Upon successful completion of the call, the authentication token of the user will be changed in accordance with the password service con-
figured in the system through pam.conf(4).
RETURN VALUES
Upon successful completion, PAM_SUCCESS is returned. In addition to the error return values described in pam(3PAM), the following values
may be returned:
PAM_PERM_DENIED No permission.
PAM_AUTHTOK_ERR Authentication token manipulation error.
PAM_AUTHTOK_RECOVERY_ERR Authentication information cannot 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 service.
PAM_TRY_AGAIN Preliminary check by password service failed.
ATTRIBUTES
See attributes(5) for description of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Interface Stability | Stable |
+-----------------------------+-----------------------------+
|MT-Level |MT-Safe with exceptions |
+-----------------------------+-----------------------------+
SEE ALSO login(1), passwd(1), pam(3PAM), pam_authenticate(3PAM), pam_start(3PAM), attributes
NOTES
The flag PAM_CHANGE_EXPIRED_AUTHTOK is typically used by a login application which has determined that the user's password has aged or
expired. Before allowing the user to login, the login application may invoke pam_chauthtok() with this flag to allow the user to update the
password. Typically, applications such as passwd(1) should not use this flag.
The pam_chauthtok() functions performs a preliminary check before attempting to update passwords. This check is performed for each password
module in the stack as listed in pam.conf(4). The check may include pinging remote name services to determine if they are available. If
pam_chauthtok() returns PAM_TRY_AGAIN, then the check has failed, and passwords are not updated.
The flag PAM_NO_AUTHTOK_CHECK is typically used by programs that allow an administrator to bypass various password conformance checks when
setting a password for a user.
The interfaces in libpam are MT-Safe only if each thread within the multithreaded application uses its own PAM handle.
SunOS 5.11 1 Mar 2005 pam_chauthtok(3PAM)
Check Out this Related Man Page
pam_sm_chauthtok(3PAM) PAM Library Functions pam_sm_chauthtok(3PAM)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(3PAM) from the modules listed in the pam.conf(4) file.
The password management provider supplies the back-end functionality for this interface function.
The pam_sm_chauthtok() function changes the authentication token associated with a particular user referenced by the authentication handle
pamh.
The following flag may be passed 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 pass-
word service should update all passwords.
PAM_PRELIM_CHECK The password service should only perform preliminary checks. No passwords should be updated.
PAM_NO_AUTHTOK_CHECK The password service should not perform conformance checks on the structure of the password. Conformance
checks do not apply to verification that the same password was entered during both passes.
PAM_UPDATE_AUTHTOK The password service should update passwords.
Note that PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK cannot 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). The argv argument 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 require-
ments.
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.
RETURN VALUES
Upon successful completion, PAM_SUCCESS must be returned. The following values may also be returned:
PAM_PERM_DENIED No permission.
PAM_AUTHTOK_ERR Authentication token manipulation error.
PAM_AUTHTOK_RECOVERY_ERR Old authentication token cannot 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 service.
PAM_TRY_AGAIN Preliminary check by password service failed.
ATTRIBUTES
See attributes(5) for description of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Interface Stability | Stable |
+-----------------------------+-----------------------------+
|MT-Level |MT-Safe with exceptions |
+-----------------------------+-----------------------------+
SEE ALSO ping(1M), pam(3PAM), pam_chauthtok(3PAM), pam_get_data(3PAM), pam_get_item(3PAM), pam_set_data(3PAM), libpam(3LIB), pam.conf(4),
attributes(5)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. For example, they may ping remote name services to see if they are
ready for updates. If a password module detects a transient error such as a remote name service temporarily down, 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 pre-
liminary 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 or expired, then the password module should return PAM_IGNORE.
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 particular module.
The interfaces in libpam are MT-Safe only if each thread within the multithreaded application uses its own PAM handle.
If the PAM_REPOSITORY item_type is set and a service module does not recognize the type, the service module does not process any informa-
tion, and returns PAM_IGNORE. If the PAM_REPOSITORY item_type is not set, a service module performs its default action.
SunOS 5.11 1 Mar 2005 pam_sm_chauthtok(3PAM)