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