1 .\" Generated from pam_get_authtok.c by gendoc.pl
2 .\" $OpenPAM: pam_get_authtok.c 938 2017-04-30 21:34:42Z des $
8 .Nd retrieve authentication token
11 .In security/pam_appl.h
13 .Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt"
17 function either prompts the user for an
18 authentication token or retrieves a cached authentication token,
19 depending on circumstances.
20 Either way, a pointer to the authentication token is stored in the
21 location pointed to by the
23 argument, and the corresponding PAM
28 argument must have one of the following values:
31 Returns the current authentication token, or the new token
32 when changing authentication tokens.
34 Returns the previous authentication token when changing
35 authentication tokens.
40 argument specifies a prompt to use if no token is cached.
44 .Dv PAM_AUTHTOK_PROMPT
46 .Dv PAM_OLDAUTHTOK_PROMPT
48 as appropriate, will be used.
51 a hardcoded default prompt will be used.
54 is called from a service module,
55 the prompt may be affected by module options as described below.
56 The prompt is then expanded using
58 before it is passed to
59 the conversation function.
65 and there is a non-null
69 will ask the user to confirm the new token by
71 If there is a mismatch,
76 When called by a service module,
79 following module options:
86 This option overrides both the
89 .Dv PAM_AUTHTOK_PROMPT
92 If the application's conversation function allows it, this
93 lets the user see what they are typing.
94 This should only be used for non-reusable authentication
96 .It Dv oldauthtok_prompt
101 This option overrides both the
104 .Dv PAM_OLDAUTHTOK_PROMPT
106 .It Dv try_first_pass
107 If the requested item is non-null, return it without
109 Typically, the service module will verify the token, and
110 if it does not match, clear the item before calling
113 .It Dv use_first_pass
114 Do not prompt the user at all; just return the cached
122 function returns one of the following values:
124 .It Bq Er PAM_SUCCESS
126 .It Bq Er PAM_BAD_CONSTANT
128 .It Bq Er PAM_BAD_ITEM
129 Unrecognized or restricted item.
130 .It Bq Er PAM_BUF_ERR
132 .It Bq Er PAM_CONV_ERR
133 Conversation failure.
134 .It Bq Er PAM_SYSTEM_ERR
136 .It Bq Er PAM_TRY_AGAIN
140 .Xr openpam_get_option 3 ,
141 .Xr openpam_subst 3 ,
150 function is an OpenPAM extension.
154 function and this manual page were
157 Project by ThinkSec AS and Network Associates Laboratories, the
158 Security Research Division of Network Associates, Inc.\& under
159 DARPA/SPAWAR contract N66001-01-C-8035
161 as part of the DARPA CHATS research program.
163 The OpenPAM library is maintained by
164 .An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .