PAM_SM_CHAUTHTOK(3)

💅 PAM_SM_CHAUTHTOK 💅

okay so bestie, we're in the <security/pam_modules.h> era and this is the Linux-PAM Manual page for pam_sm_chauthtok — the PAM service function for authentication token management. yes it's a mouthful. no we're not skipping it. let's go ✨

---

🌸 SYNOPSIS 🌸

#include <security/pam_modules.h>

int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int argc,
                     const char **argv);

---

🎀 DESCRIPTION 🎀

so pam_sm_chauthtok is literally the service module's own implementation of the pam_chauthtok(3) interface. it's the glow-up function — it's used to (re-)set the authentication token of the user. new password, who dis 💅

the valid flags, which you can logically OR together with PAM_SILENT, are:

• PAM_SILENT — do not emit any messages. not a peep. silent era, main character energy, no ✨ chatter ✨
• PAM_CHANGE_EXPIRED_AUTHTOK — this argument tells the module that the user's authentication token (password) should only be changed if it has expired. this flag is optional and must be combined with one of the following two flags. but heads up 🫶 — the following two options are mutually exclusive, so pick one, not both, bestie.
• PAM_PRELIM_CHECK — this indicates that the modules are being probed as to their ready status for altering the user's authentication token. if the module needs access to another system over some network, it should attempt to verify it can connect to this system on receiving this flag. if a module can't establish that it's ready to update the user's authentication token, it should return PAM_TRY_AGAIN, and this information gets passed back to the application.

also important: if the control value sufficient is used in the password stack, the PAM_PRELIM_CHECK section of the modules following that control value is not always executed. lowkey a vibe check with a catch 🫠

• PAM_UPDATE_AUTHTOK — this informs the module that this is the call where it should change the authorization tokens. if the flag is logically OR'd with PAM_CHANGE_EXPIRED_AUTHTOK, the token is only changed if it has actually expired. no expired token, no change. periodt.

the PAM library calls this function twice in succession 🔁 — first with PAM_PRELIM_CHECK, and then, if the module does not return PAM_TRY_AGAIN, subsequently with PAM_UPDATE_AUTHTOK. it's only on the second call that the authorization token is (possibly) changed. so yes, it's a two-episode arc and the token only gets its makeover in part two 💖

---

🦋 RETURN VALUES 🦋

• PAM_AUTHTOK_ERR — the module was unable to obtain the new authentication token. 😭
• PAM_AUTHTOK_RECOVERY_ERR — the module was unable to obtain the old authentication token. 🙈
• PAM_AUTHTOK_LOCK_BUSY — cannot change the authentication token since it is currently locked. it's booked and busy, try later 💀
• PAM_AUTHTOK_DISABLE_AGING — authentication token aging has been disabled.
• PAM_PERM_DENIED — permission denied. you shall not pass 🚫
• PAM_TRY_AGAIN — preliminary check was unsuccessful. signals an immediate return to the application is desired.
• PAM_SUCCESS — the authentication token was successfully updated. ate. no crumbs. 👑
• PAM_USER_UNKNOWN — user unknown to password service. who is she? 🤔

---

⭐ SEE ALSO ⭐

pam(3), pam_chauthtok(3), pam_sm_chauthtok(3), pam_strerror(3), PAM(8)

---

and that's the whole page bestie, go forth and manage those tokens responsibly 🧚💜

signed, sealed, delivered by Linux-PAM — dated 07/08/2026 — mwah, talk later 🌈💖