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