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