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, int flags);

DESCRIPTION

The pam_chauthtok() function is called to change 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, all password
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
configured in the system through pam.conf(5).

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(7) 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(5). 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.

July 6, 2024 PAM_CHAUTHTOK(3PAM)