Name
pam_get_authtok - get authentication token
Synopsis
#include <security/pam_ext.h>
int pam_get_authtok(pam_handle_t *pamh, int item, const char **authtok, const char *prompt); | |
DESCRIPTION
The pam_get_authtok function returns the cached authentication token, or prompts the user if no token is currently cached. It is intended for internal use by Linux-PAM and PAM service modules. Upon successful return, authtok contains a pointer to the value of the authentication token. Note, this is a pointer to the actual data and should not be free()'ed or over-written!
The prompt argument specifies a prompt to use if no token is cached. If a NULL pointer is given, pam_get_authtok uses pre-defined prompts.
The following values are supported for item:
PAM_AUTHTOK
Returns the current authentication token. Called from pam_sm_chauthtok(3) pam_get_authtok will ask the user to confirm the new token by retyping it. If a prompt was specified, "Retype" will be used as prefix.
PAM_OLDAUTHTOK
Returns the previous authentication token when changing authentication tokens.
OPTIONS
pam_get_authtok honours the following module options:
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.
use_first_pass
The argument use_first_pass forces the module to use a previous stacked modules password and will never prompt the user - if no password is available or the password is not appropriate, the user will be denied access.
use_authtok
When password changing enforce 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.
authtok_type=XXX
The default action is for the module to use the following prompts when requesting passwords: "New UNIX password: " and "Retype UNIX password: ". The example word UNIX can be replaced with this option, by default it is empty.
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 successful retrieved.
PAM_SYSTEM_ERR
No space for an authentication token was provided.
PAM_TRY_AGAIN
New authentication tokens mismatch.
SEE ALSO
pam(8)
STANDARDS
The pam_get_authtok function is a Linux-PAM extensions.