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.

openSUSE Logo

Contents