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">
4 <refentry id='pam_sm_chauthtok'>
6 <refentrytitle>pam_sm_chauthtok</refentrytitle>
7 <manvolnum>3</manvolnum>
8 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
11 <refnamediv id="pam_sm_chauthtok-name">
12 <refname>pam_sm_chauthtok</refname>
13 <refpurpose>PAM service function for authentication token management</refpurpose>
16 <!-- body begins here -->
19 <funcsynopsis id='pam_sm_chauthtok-synopsis'>
20 <funcsynopsisinfo>#define PAM_SM_PASSWORD</funcsynopsisinfo>
21 <funcsynopsisinfo>#include <security/pam_modules.h></funcsynopsisinfo>
23 <funcdef>int <function>pam_sm_chauthtok</function></funcdef>
24 <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
25 <paramdef>int <parameter>flags</parameter></paramdef>
26 <paramdef>int <parameter>argc</parameter></paramdef>
27 <paramdef>const char **<parameter>argv</parameter></paramdef>
33 <refsect1 id='pam_sm_chauthtok-description'>
34 <title>DESCRIPTION</title>
36 The <function>pam_sm_chauthtok</function> function is the service
37 module's implementation of the
39 <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
40 </citerefentry> interface.
43 This function is used to (re-)set the authentication token of the user.
46 Valid flags, which may be logically OR'd with
47 <emphasis>PAM_SILENT</emphasis>, are:
51 <term>PAM_SILENT</term>
54 Do not emit any messages.
59 <term>PAM_CHANGE_EXPIRED_AUTHTOK</term>
62 This argument indicates to the module that the user's
63 authentication token (password) should only be changed if
64 it has expired. This flag is optional and
65 <emphasis>must</emphasis> be combined with one of the
66 following two flags. Note, however, the following two options
67 are <emphasis>mutually exclusive</emphasis>.
72 <term>PAM_PRELIM_CHECK</term>
75 This indicates that the modules are being probed as to
76 their ready status for altering the user's authentication
77 token. If the module requires access to another system over
78 some network it should attempt to verify it can connect to
79 this system on receiving this flag. If a module cannot establish
80 it is ready to update the user's authentication token it should
81 return <emphasis remap='B'>PAM_TRY_AGAIN</emphasis>, this
82 information will be passed back to the application.
85 If the control value <emphasis>sufficient</emphasis> is used in
86 the password stack, the <emphasis>PAM_PRELIM_CHECK</emphasis> section
87 of the modules following that control value is not always executed.
92 <term>PAM_UPDATE_AUTHTOK</term>
95 This informs the module that this is the call it should change
96 the authorization tokens. If the flag is logically OR'd with
97 <emphasis remap='B'>PAM_CHANGE_EXPIRED_AUTHTOK</emphasis>, the
98 token is only changed if it has actually expired.
104 The PAM library calls this function twice in succession. The first
105 time with <emphasis remap='B'>PAM_PRELIM_CHECK</emphasis> and then,
106 if the module does not return
107 <emphasis remap='B'>PAM_TRY_AGAIN</emphasis>, subsequently with
108 <emphasis remap='B'>PAM_UPDATE_AUTHTOK</emphasis>. It is only on
109 the second call that the authorization token is (possibly) changed.
113 <refsect1 id="pam_sm_chauthtok-return_values">
114 <title>RETURN VALUES</title>
117 <term>PAM_AUTHTOK_ERR</term>
120 The module was unable to obtain the new authentication token.
125 <term>PAM_AUTHTOK_RECOVERY_ERR</term>
128 The module was unable to obtain the old authentication token.
133 <term>PAM_AUTHTOK_LOCK_BUSY</term>
136 Cannot change the authentication token since it is currently
142 <term>PAM_AUTHTOK_DISABLE_AGING</term>
145 Authentication token aging has been disabled.
150 <term>PAM_PERM_DENIED</term>
158 <term>PAM_TRY_AGAIN</term>
161 Preliminary check was unsuccessful. Signals an immediate
162 return to the application is desired.
167 <term>PAM_SUCCESS</term>
170 The authentication token was successfully updated.
175 <term>PAM_USER_UNKNOWN</term>
178 User unknown to password service.
185 <refsect1 id='pam_sm_chauthtok-see_also'>
186 <title>SEE ALSO</title>
189 <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
192 <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
195 <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
198 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
201 <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>