1.\" Generated from pam_get_authtok.c by gendoc.pl 2.\" $OpenPAM: pam_get_authtok.c 938 2017-04-30 21:34:42Z des $ 3.Dd February 24, 2019 4.Dt PAM_GET_AUTHTOK 3 5.Os 6.Sh NAME 7.Nm pam_get_authtok 8.Nd retrieve authentication token 9.Sh SYNOPSIS 10.In sys/types.h 11.In security/pam_appl.h 12.Ft "int" 13.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt" 14.Sh DESCRIPTION 15The 16.Fn pam_get_authtok 17function either prompts the user for an 18authentication token or retrieves a cached authentication token, 19depending on circumstances. 20Either way, a pointer to the authentication token is stored in the 21location pointed to by the 22.Fa authtok 23argument, and the corresponding PAM 24item is updated. 25.Pp 26The 27.Fa item 28argument must have one of the following values: 29.Bl -tag -width 18n 30.It Dv PAM_AUTHTOK 31Returns the current authentication token, or the new token 32when changing authentication tokens. 33.It Dv PAM_OLDAUTHTOK 34Returns the previous authentication token when changing 35authentication tokens. 36.El 37.Pp 38The 39.Fa prompt 40argument specifies a prompt to use if no token is cached. 41If it is 42.Dv NULL , 43the 44.Dv PAM_AUTHTOK_PROMPT 45or 46.Dv PAM_OLDAUTHTOK_PROMPT 47item, 48as appropriate, will be used. 49If that item is also 50.Dv NULL , 51a hardcoded default prompt will be used. 52Additionally, when 53.Fn pam_get_authtok 54is called from a service module, 55the prompt may be affected by module options as described below. 56The prompt is then expanded using 57.Xr openpam_subst 3 58before it is passed to 59the conversation function. 60.Pp 61If 62.Fa item 63is set to 64.Dv PAM_AUTHTOK 65and there is a non-null 66.Dv PAM_OLDAUTHTOK 67item, 68.Fn pam_get_authtok 69will ask the user to confirm the new token by 70retyping it. 71If there is a mismatch, 72.Fn pam_get_authtok 73will return 74.Dv PAM_TRY_AGAIN . 75.Sh MODULE OPTIONS 76When called by a service module, 77.Fn pam_get_authtok 78will recognize the 79following module options: 80.Bl -tag -width 18n 81.It Dv authtok_prompt 82Prompt to use when 83.Fa item 84is set to 85.Dv PAM_AUTHTOK . 86This option overrides both the 87.Fa prompt 88argument and the 89.Dv PAM_AUTHTOK_PROMPT 90item. 91.It Dv echo_pass 92If the application's conversation function allows it, this 93lets the user see what they are typing. 94This should only be used for non-reusable authentication 95tokens. 96.It Dv oldauthtok_prompt 97Prompt to use when 98.Fa item 99is set to 100.Dv PAM_OLDAUTHTOK . 101This option overrides both the 102.Fa prompt 103argument and the 104.Dv PAM_OLDAUTHTOK_PROMPT 105item. 106.It Dv try_first_pass 107If the requested item is non-null, return it without 108prompting the user. 109Typically, the service module will verify the token, and 110if it does not match, clear the item before calling 111.Fn pam_get_authtok 112a second time. 113.It Dv use_first_pass 114Do not prompt the user at all; just return the cached 115value, or 116.Dv PAM_AUTH_ERR 117if there is none. 118.El 119.Sh RETURN VALUES 120The 121.Fn pam_get_authtok 122function returns one of the following values: 123.Bl -tag -width 18n 124.It Bq Er PAM_SUCCESS 125Success. 126.It Bq Er PAM_BAD_CONSTANT 127Bad constant. 128.It Bq Er PAM_BAD_ITEM 129Unrecognized or restricted item. 130.It Bq Er PAM_BUF_ERR 131Memory buffer error. 132.It Bq Er PAM_CONV_ERR 133Conversation failure. 134.It Bq Er PAM_SYSTEM_ERR 135System error. 136.It Bq Er PAM_TRY_AGAIN 137Try again. 138.El 139.Sh SEE ALSO 140.Xr openpam_get_option 3 , 141.Xr openpam_subst 3 , 142.Xr pam 3 , 143.Xr pam_conv 3 , 144.Xr pam_get_item 3 , 145.Xr pam_get_user 3 , 146.Xr pam_strerror 3 147.Sh STANDARDS 148The 149.Fn pam_get_authtok 150function is an OpenPAM extension. 151.Sh AUTHORS 152The 153.Fn pam_get_authtok 154function and this manual page were 155developed for the 156.Fx 157Project by ThinkSec AS and Network Associates Laboratories, the 158Security Research Division of Network Associates, Inc.\& under 159DARPA/SPAWAR contract N66001-01-C-8035 160.Pq Dq CBOSS , 161as part of the DARPA CHATS research program. 162.Pp 163The OpenPAM library is maintained by 164.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 165