PAM_GET_AUTHTOK

Section: Linux-PAM Manual (3)
Updated: 03/02/2009
Index Return to Main Contents

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.

STANDARDS