1 .\" Generated from pam_get_authtok.c by gendoc.pl
2 .\" $Id: pam_get_authtok.c 807 2014-09-09 09:41:32Z des $
8 .Nd retrieve authentication token
13 .In security/pam_appl.h
15 .Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt"
19 function either prompts the user for an
20 authentication token or retrieves a cached authentication token,
21 depending on circumstances.
22 Either way, a pointer to the authentication token is stored in the
23 location pointed to by the
25 argument, and the corresponding PAM
30 argument must have one of the following values:
33 Returns the current authentication token, or the new token
34 when changing authentication tokens.
36 Returns the previous authentication token when changing
37 authentication tokens.
42 argument specifies a prompt to use if no token is cached.
46 .Dv PAM_AUTHTOK_PROMPT
48 .Dv PAM_OLDAUTHTOK_PROMPT
50 as appropriate, will be used.
53 a hardcoded default prompt will be used.
56 is called from a service module,
57 the prompt may be affected by module options as described below.
58 The prompt is then expanded using
60 before it is passed to
61 the conversation function.
67 and there is a non-null
71 will ask the user to confirm the new token by
73 If there is a mismatch,
78 When called by a service module,
81 following module options:
88 This option overrides both the
91 .Dv PAM_AUTHTOK_PROMPT
94 If the application's conversation function allows it, this
95 lets the user see what they are typing.
96 This should only be used for non-reusable authentication
98 .It Dv oldauthtok_prompt
103 This option overrides both the
106 .Dv PAM_OLDAUTHTOK_PROMPT
108 .It Dv try_first_pass
109 If the requested item is non-null, return it without
111 Typically, the service module will verify the token, and
112 if it does not match, clear the item before calling
115 .It Dv use_first_pass
116 Do not prompt the user at all; just return the cached
124 function returns one of the following values:
126 .It Bq Er PAM_BUF_ERR
128 .It Bq Er PAM_CONV_ERR
129 Conversation failure.
130 .It Bq Er PAM_SYSTEM_ERR
132 .It Bq Er PAM_TRY_AGAIN
136 .Xr openpam_get_option 3 ,
137 .Xr openpam_subst 3 ,
146 function is an OpenPAM extension.
150 function and this manual page were
153 Project by ThinkSec AS and Network Associates Laboratories, the
154 Security Research Division of Network Associates, Inc.\& under
155 DARPA/SPAWAR contract N66001-01-C-8035
157 as part of the DARPA CHATS research program.
159 The OpenPAM library is maintained by
160 .An Dag-Erling Sm\(/orgrav Aq des@des.no .