1.\" Generated from pam_get_authtok.c by gendoc.pl
2.\" $Id: pam_get_authtok.c 807 2014-09-09 09:41:32Z des $
3.Dd September 12, 2014
4.Dt PAM_GET_AUTHTOK 3
5.Os
6.Sh NAME
7.Nm pam_get_authtok
8.Nd retrieve authentication token
9.Sh LIBRARY
10.Lb libpam
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_BUF_ERR
127Memory buffer error.
128.It Bq Er PAM_CONV_ERR
129Conversation failure.
130.It Bq Er PAM_SYSTEM_ERR
131System error.
132.It Bq Er PAM_TRY_AGAIN
133Try again.
134.El
135.Sh SEE ALSO
136.Xr openpam_get_option 3 ,
137.Xr openpam_subst 3 ,
138.Xr pam 3 ,
139.Xr pam_conv 3 ,
140.Xr pam_get_item 3 ,
141.Xr pam_get_user 3 ,
142.Xr pam_strerror 3
143.Sh STANDARDS
144The
145.Fn pam_get_authtok
146function is an OpenPAM extension.
147.Sh AUTHORS
148The
149.Fn pam_get_authtok
150function and this manual page were
151developed for the
152.Fx
153Project by ThinkSec AS and Network Associates Laboratories, the
154Security Research Division of Network Associates, Inc.\& under
155DARPA/SPAWAR contract N66001-01-C-8035
156.Pq Dq CBOSS ,
157as part of the DARPA CHATS research program.
158.Pp
159The OpenPAM library is maintained by
160.An Dag-Erling Sm\(/orgrav Aq des@des.no .
161