PAM_GET_AUTHTOK(3)

💅 PAM_GET_AUTHTOK 💅

okay so bestie, welcome to PAM_GET_AUTHTOK(3) — that's the <hotpink>Linux-PAM Manual</hotpink> page for pam_get_authtok, pam_get_authtok_verify, and pam_get_authtok_noverify, and their whole entire job is get authentication token. that's it. that's the NAME. iconic behavior honestly. 🎀

---

✨ SYNOPSIS ✨

like, literally just include this first:

#include <security/pam_ext.h>

and then the three besties:

int pam_get_authtok(pam_handle_t *pamh, int item, const char **authtok,
                    const char *prompt);

int pam_get_authtok_noverify(pam_handle_t *pamh, const char **authtok,
                             const char *prompt);

int pam_get_authtok_verify(pam_handle_t *pamh, const char **authtok,
                           const char *prompt);

---

🌸 DESCRIPTION 🌸

pam_get_authtok — the main character 👑

so pam_get_authtok returns the cached authentication token, or — if nothing's cached yet — it prompts the user for one. it's meant for internal use by Linux-PAM and by PAM service modules, iykyk. 🫶

when it returns successfully, authtok contains a pointer to the value of the authentication token. but bestie, listen — this is a pointer to the actual data, so do not free() it and do not overwrite it. fr fr. 😭

the prompt argument is the prompt to use if no token is cached. if you hand it a NULL pointer, pam_get_authtok just uses its pre-defined prompts. lowkey convenient.

the following values are supported for item:

• PAM_AUTHTOK — returns the current authentication token. when called from pam_sm_chauthtok(3), pam_get_authtok will ask the user to confirm the new token by retyping it. and if a prompt was specified, "Retype" gets used as the prefix. double-check energy ✨
• PAM_OLDAUTHTOK — returns the previous authentication token, for when you're changing authentication tokens. the throwback token. 💜

pam_get_authtok_noverify — the "trust me" one 🙈

pam_get_authtok_noverify can only be used for changing the password (from pam_sm_chauthtok(3)). it returns the cached authentication token, or prompts the user if no token is currently cached.

the difference from pam_get_authtok? this one does not ask a second time for the password to verify it. no verification arc. skipping the vibe check, basically.

on successful return, authtok contains a pointer to the value of the authentication token — and again, that's a pointer to the actual data, so no free()-ing and no over-writing. i'm serious. 💀

pam_get_authtok_verify — the actual vibe check 🦋

pam_get_authtok_verify can only be used to verify a password for mistypes gotten by pam_get_authtok_noverify(3). it asks a second time for the password and verifies it against the password provided by the authtok argument. 👑

in case of an error, the value of authtok is undefined. otherwise, this argument will point to the actual data and should not be free()-ed or over-written. periodt.

---

⭐ OPTIONS ⭐

pam_get_authtok honours the following module options, bestie:

• try_first_pass — before prompting the user for their password, the module first tries the previous stacked module's password, in case that satisfies this module as well. like borrowing your friend's fit and it actually eats. 🔥
• use_first_pass — the argument use_first_pass forces the module to use a previous stacked module's password and will never prompt the user. if no password is available, or the password is not appropriate, the user will be denied access. no backup plan, no Plan B, no second chances. 😭
• use_authtok — when password changing, this enforces the module to set the new token to the one provided by a previously stacked password module. if no token is available, token changing will fail. harsh but fair. 💅
• authtok_type=XXX — the default action is for the module to use these prompts when requesting passwords: "New UNIX password: " and "Retype UNIX password: ". that example word UNIX can be replaced with this option — and by default it is empty. customizable queen. 🎀

---

🧚 RETURN VALUES 🧚

• PAM_AUTH_ERR — authentication token could not be retrieved. 😬
• PAM_AUTHTOK_ERR — new authentication could not be retrieved.
• PAM_SUCCESS — authentication token was successfully retrieved. slay!! 🎉
• PAM_SYSTEM_ERR — a NULL pointer was specified as the PAM handle, or no space for an authentication token was provided.
• PAM_TRY_AGAIN — new authentication tokens mismatch. the two passwords did not match, bestie, try again. 🙈

---

🌈 SEE ALSO 🌈

• pam(8) — go read it, it's the whole ecosystem.

---

👑 STANDARDS 👑

the pam_get_authtok function is a Linux-PAM extensions. that's the whole standards section, no notes.

---

so yeah, that's the whole page. 💖 this page came from Linux-PAM, dated 07/08/2026, and honestly? she ate. go forth and cache those tokens responsibly, bestie — and remember: do not free() the authtok. 🌸🫶✨