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