$Id: pam_get_authtok.c 807 2014-09-09 09:41:32Z des $
.Dd September 12, 2014 .Dt PAM_GET_AUTHTOK 3 .Os .Sh NAME .Nm pam_get_authtok .Nd retrieve authentication token .Sh LIBRARY .Lb libpam .Sh SYNOPSIS n sys/types.h n security/pam_appl.h .Ft "int" .Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt" .Sh DESCRIPTION The .Fn pam_get_authtok function either prompts the user for an authentication token or retrieves a cached authentication token, depending on circumstances. Either way, a pointer to the authentication token is stored in the location pointed to by the .Fa authtok argument, and the corresponding PAM item is updated.
p The .Fa item argument must have one of the following values: l -tag -width 18n t Dv PAM_AUTHTOK Returns the current authentication token, or the new token when changing authentication tokens. t Dv PAM_OLDAUTHTOK Returns the previous authentication token when changing authentication tokens. .El
p The .Fa prompt argument specifies a prompt to use if no token is cached. If it is .Dv NULL , the .Dv PAM_AUTHTOK_PROMPT or .Dv PAM_OLDAUTHTOK_PROMPT item, as appropriate, will be used. If that item is also .Dv NULL , a hardcoded default prompt will be used. Additionally, when .Fn pam_get_authtok is called from a service module, the prompt may be affected by module options as described below. The prompt is then expanded using .Xr openpam_subst 3 before it is passed to the conversation function.
p If .Fa item is set to .Dv PAM_AUTHTOK and there is a non-null .Dv PAM_OLDAUTHTOK item, .Fn pam_get_authtok will ask the user to confirm the new token by retyping it. If there is a mismatch, .Fn pam_get_authtok will return .Dv PAM_TRY_AGAIN . .Sh MODULE OPTIONS When called by a service module, .Fn pam_get_authtok will recognize the following module options: l -tag -width 18n t Dv authtok_prompt Prompt to use when .Fa item is set to .Dv PAM_AUTHTOK . This option overrides both the .Fa prompt argument and the .Dv PAM_AUTHTOK_PROMPT item. t Dv echo_pass If the application's conversation function allows it, this lets the user see what they are typing. This should only be used for non-reusable authentication tokens. t Dv oldauthtok_prompt Prompt to use when .Fa item is set to .Dv PAM_OLDAUTHTOK . This option overrides both the .Fa prompt argument and the .Dv PAM_OLDAUTHTOK_PROMPT item. t Dv try_first_pass If the requested item is non-null, return it without prompting the user. Typically, the service module will verify the token, and if it does not match, clear the item before calling .Fn pam_get_authtok a second time. t Dv use_first_pass Do not prompt the user at all; just return the cached value, or .Dv PAM_AUTH_ERR if there is none. .El .Sh RETURN VALUES The .Fn pam_get_authtok function returns one of the following values: l -tag -width 18n t Bq Er PAM_BUF_ERR Memory buffer error. t Bq Er PAM_CONV_ERR Conversation failure. t Bq Er PAM_SYSTEM_ERR System error. t Bq Er PAM_TRY_AGAIN Try again. .El .Sh SEE ALSO .Xr openpam_get_option 3 , .Xr openpam_subst 3 , .Xr pam 3 , .Xr pam_conv 3 , .Xr pam_get_item 3 , .Xr pam_get_user 3 , .Xr pam_strerror 3 .Sh STANDARDS The .Fn pam_get_authtok function is an OpenPAM extension. .Sh AUTHORS The .Fn pam_get_authtok function and this manual page were developed for the .Fx Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
q Dq CBOSS , as part of the DARPA CHATS research program.
p The OpenPAM library is maintained by .An Dag-Erling Sm\(/orgrav Aq des@des.no .