1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5 <refentry id="pam_get_authtok">
8 <refentrytitle>pam_get_authtok</refentrytitle>
9 <manvolnum>3</manvolnum>
10 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
13 <refnamediv id="pam_get_authtok-name">
14 <refname>pam_get_authtok</refname>
15 <refname>pam_get_authtok_verify</refname>
16 <refname>pam_get_authtok_noverify</refname>
17 <refpurpose>get authentication token</refpurpose>
20 <!-- body begins here -->
22 <refsynopsisdiv id="pam_get_authtok-synopsis">
24 <funcsynopsisinfo>#include <security/pam_ext.h></funcsynopsisinfo>
26 <funcdef>int <function>pam_get_authtok</function></funcdef>
27 <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
28 <paramdef>int <parameter>item</parameter></paramdef>
29 <paramdef>const char **<parameter>authtok</parameter></paramdef>
30 <paramdef>const char *<parameter>prompt</parameter></paramdef>
33 <funcdef>int <function>pam_get_authtok_noverify</function></funcdef>
34 <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
35 <paramdef>const char **<parameter>authtok</parameter></paramdef>
36 <paramdef>const char *<parameter>prompt</parameter></paramdef>
39 <funcdef>int <function>pam_get_authtok_verify</function></funcdef>
40 <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
41 <paramdef>const char **<parameter>authtok</parameter></paramdef>
42 <paramdef>const char *<parameter>prompt</parameter></paramdef>
47 <refsect1 id='pam_get_authtok-description'>
48 <title>DESCRIPTION</title>
50 The <function>pam_get_authtok</function> function returns the
51 cached authentication token, or prompts the user if no token is
52 currently cached. It is intended for internal use by Linux-PAM and
53 PAM service modules. Upon successful return,
54 <emphasis>authtok</emphasis> contains a pointer to the value of the
55 authentication token. Note, this is a pointer to the
56 <emphasis>actual</emphasis> data and should
57 <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
61 The <emphasis>prompt</emphasis> argument specifies a prompt to use
62 if no token is cached. If a NULL pointer
63 is given, <function>pam_get_authtok</function> uses pre-defined prompts.
66 The following values are supported for <emphasis>item</emphasis>:
70 <term>PAM_AUTHTOK</term>
73 Returns the current authentication token. Called from
74 <citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
75 </citerefentry> <function>pam_get_authtok</function> will
76 ask the user to confirm the new token by retyping it. If
77 a prompt was specified, "Retype" will be used as prefix.
82 <term>PAM_OLDAUTHTOK</term>
85 Returns the previous authentication token when changing
86 authentication tokens.
92 The <function>pam_get_authtok_noverify</function> function can
93 only be used for changing the password
95 <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
96 </citerefentry>). It returns the cached
97 authentication token, or prompts the user if no token is
98 currently cached. The difference to <function>pam_get_authtok</function>
99 is, that this function does not ask a second time for the password
100 to verify it. Upon successful return, <emphasis>authtok</emphasis>
101 contains a pointer to the value of the authentication token. Note,
102 this is a pointer to the
103 <emphasis>actual</emphasis> data and should
104 <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
108 The <function>pam_get_authtok_verify</function> function can
109 only be used to verify a password for mistypes gotten by
111 <refentrytitle>pam_get_authtok_noverify</refentrytitle><manvolnum>3</manvolnum>
112 </citerefentry>. This function asks a second time for the password
113 and verify it with the password provided by <emphasis>authtok</emphasis>
114 argument. In case of an error, the value of <emphasis>authtok</emphasis>
115 is undefined. Else this argument will point to the
116 <emphasis>actual</emphasis> data and should
117 <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
122 <refsect1 id="pam_get_authtok-options">
123 <title>OPTIONS</title>
125 <function>pam_get_authtok</function> honours the following module
131 <option>try_first_pass</option>
135 Before prompting the user for their password, the module first
136 tries the previous stacked module's password in case that
137 satisfies this module as well.
143 <option>use_first_pass</option>
147 The argument <option>use_first_pass</option> forces the module
148 to use a previous stacked modules password and will never prompt
149 the user - if no password is available or the password is not
150 appropriate, the user will be denied access.
156 <option>use_authtok</option>
160 When password changing enforce the module to set the new
161 token to the one provided by a previously stacked
162 <option>password</option> module. If no token is available
163 token changing will fail.
169 <option>authtok_type=<replaceable>XXX</replaceable></option>
173 The default action is for the module to use the
174 following prompts when requesting passwords:
175 "New UNIX password: " and "Retype UNIX password: ".
176 The example word <emphasis>UNIX</emphasis> can
177 be replaced with this option, by default it is empty.
185 <refsect1 id="pam_get_authtok-return_values">
186 <title>RETURN VALUES</title>
189 <term>PAM_AUTH_ERR</term>
192 Authentication token could not be retrieved.
197 <term>PAM_AUTHTOK_ERR</term>
200 New authentication could not be retrieved.
205 <term>PAM_SUCCESS</term>
208 Authentication token was successfully retrieved.
213 <term>PAM_SYSTEM_ERR</term>
216 No space for an authentication token was provided.
221 <term>PAM_TRY_AGAIN</term>
224 New authentication tokens mismatch.
231 <refsect1 id='pam_get_authtok-see_also'>
232 <title>SEE ALSO</title>
235 <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
240 <refsect1 id='pam_get_authtok-standards'>
241 <title>STANDARDS</title>
243 The <function>pam_get_authtok</function> function is a Linux-PAM