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