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