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