FM / html

/usr/share/doc/pam-devel/html

Name	Size	Mode	Actions
adg-author.html	3098	0644	edit dl rm
adg-copyright.html	3624	0644	edit dl rm
adg-example.html	3676	0644	edit dl rm
adg-files.html	2239	0644	edit dl rm
adg-glossary.html	3286	0644	edit dl rm
adg-interface-by-app-expected.html	62472	0644	edit dl rm
adg-interface-of-app-expected.html	8457	0644	edit dl rm
adg-interface-programming-notes.html	2614	0644	edit dl rm
adg-interface.html	5019	0644	edit dl rm
adg-introduction-description.html	3373	0644	edit dl rm
adg-introduction-synopsis.html	2683	0644	edit dl rm
adg-introduction.html	2064	0644	edit dl rm
adg-libpam-functions.html	13449	0644	edit dl rm
adg-libpam_misc.html	3421	0644	edit dl rm
adg-overview.html	8357	0644	edit dl rm
adg-porting.html	4306	0644	edit dl rm
adg-security-conv-function.html	2346	0644	edit dl rm
adg-security-library-calls.html	3203	0644	edit dl rm
adg-security-resources.html	2903	0644	edit dl rm
adg-security-service-name.html	4535	0644	edit dl rm
adg-security-user-identity.html	5512	0644	edit dl rm
adg-security.html	3824	0644	edit dl rm
adg-see-also.html	2214	0644	edit dl rm
Linux-PAM_ADG.html	8613	0644	edit dl rm
Linux-PAM_MWG.html	8803	0644	edit dl rm
mwg-author.html	3075	0644	edit dl rm
mwg-copyright.html	3603	0644	edit dl rm
mwg-example.html	2005	0644	edit dl rm
mwg-expected-by-module-item.html	46457	0644	edit dl rm
mwg-expected-by-module-other.html	8352	0644	edit dl rm
mwg-expected-by-module.html	4117	0644	edit dl rm
mwg-expected-of-module-acct.html	6187	0644	edit dl rm
mwg-expected-of-module-auth.html	10968	0644	edit dl rm
mwg-expected-of-module-chauthtok.html	7977	0644	edit dl rm
mwg-expected-of-module-overview.html	6437	0644	edit dl rm
mwg-expected-of-module-session.html	7126	0644	edit dl rm
mwg-expected-of-module.html	4374	0644	edit dl rm
mwg-introduction-description.html	3971	0644	edit dl rm
mwg-introduction-synopsis.html	2028	0644	edit dl rm
mwg-introduction.html	2032	0644	edit dl rm
mwg-see-also.html	2231	0644	edit dl rm
mwg-see-options.html	2996	0644	edit dl rm
mwg-see-programming-libs.html	3015	0644	edit dl rm
mwg-see-programming-sec.html	9141	0644	edit dl rm
mwg-see-programming-syslog.html	4741	0644	edit dl rm
mwg-see-programming.html	3078	0644	edit dl rm

Edit: /usr/share/doc/pam-devel/html/mwg-expected-of-module-chauthtok.html (7977B)

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>3.5. Authentication token management</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="Linux-PAM_MWG.html" title="The Linux-PAM Module Writers' Guide"><link rel="up" href="mwg-expected-of-module.html" title="Chapter 3. What is expected of a module"><link rel="prev" href="mwg-expected-of-module-session.html" title="3.4. Session management"><link rel="next" href="mwg-see-options.html" title="Chapter 4. Generic optional arguments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.5. Authentication token management</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="mwg-expected-of-module-session.html">Prev</a> </td><th width="60%" align="center">Chapter 3. What is expected of a module</th><td width="20%" align="right"> <a accesskey="n" href="mwg-see-options.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mwg-expected-of-module-chauthtok"></a>3.5. Authentication token management</h2></div></div></div><p>
        To be correctly initialized, <em class="parameter"><code>PAM_SM_PASSWORD</code></em>
        must be <span class="command"><strong>#define</strong></span>'d prior to including
        <code class="function">&lt;security/pam_modules.h&gt;</code>. This will
        ensure that the prototypes for static modules are properly declared.
      </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mwg-pam_sm_chauthtok"></a>3.5.1. Service function to alter authentication token</h3></div></div></div><div class="funcsynopsis"><pre class="funcsynopsisinfo">#define PAM_SM_PASSWORD</pre><pre class="funcsynopsisinfo">#include &lt;security/pam_modules.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">pam_sm_chauthtok</b>(</code></td><td><var class="pdparam">pamh</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">flags</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">argc</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">argv</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>pam_handle_t *<var class="pdparam">pamh</var></code>;<br><code>int <var class="pdparam">flags</var></code>;<br><code>int <var class="pdparam">argc</var></code>;<br><code>const char **<var class="pdparam">argv</var></code>;</div><div class="funcprototype-spacer"> </div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="mwg-pam_sm_chauthtok-description"></a>3.5.1.1. DESCRIPTION</h4></div></div></div><p>
      The <code class="function">pam_sm_chauthtok</code> function is the service
      module's implementation of the
      <span class="citerefentry"><span class="refentrytitle">pam_chauthtok</span>(3)</span> interface.
    </p><p>
      This function is used to (re-)set the authentication token of the user.
    </p><p>
       Valid flags, which may be logically OR'd with
       <span class="emphasis"><em>PAM_SILENT</em></span>, are:
    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">PAM_SILENT</span></dt><dd><p>
             Do not emit any messages.
          </p></dd><dt><span class="term">PAM_CHANGE_EXPIRED_AUTHTOK</span></dt><dd><p>
            This argument indicates to the module that the user's
            authentication token (password) should only be changed if
            it has expired. This flag is optional and
            <span class="emphasis"><em>must</em></span> be combined with one of the
            following two flags. Note, however, the following two options
            are <span class="emphasis"><em>mutually exclusive</em></span>.
          </p></dd><dt><span class="term">PAM_PRELIM_CHECK</span></dt><dd><p>
            This indicates that the modules are being probed as to
            their ready status for altering the user's authentication
            token. If the module requires access to another system over
            some network it should attempt to verify it can connect to
            this system on receiving this flag. If a module cannot establish
            it is ready to update the user's authentication token it should
            return <span class="emphasis"><em>PAM_TRY_AGAIN</em></span>, this
            information will be passed back to the application.
          </p><p>
             If the control value <span class="emphasis"><em>sufficient</em></span> is used in
             the password stack, the <span class="emphasis"><em>PAM_PRELIM_CHECK</em></span> section
             of the modules following that control value is not always executed.
          </p></dd><dt><span class="term">PAM_UPDATE_AUTHTOK</span></dt><dd><p>
            This informs the module that this is the call it should change
            the authorization tokens. If the flag is logically OR'd with
            <span class="emphasis"><em>PAM_CHANGE_EXPIRED_AUTHTOK</em></span>, the
            token is only changed if it has actually expired.
          </p></dd></dl></div><p>
      The PAM library calls this function twice in succession. The first
      time with <span class="emphasis"><em>PAM_PRELIM_CHECK</em></span> and then,
      if the module does not return
      <span class="emphasis"><em>PAM_TRY_AGAIN</em></span>, subsequently with
      <span class="emphasis"><em>PAM_UPDATE_AUTHTOK</em></span>. It is only on
      the second call that the authorization token is (possibly) changed.
    </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="mwg-pam_sm_chauthtok-return_values"></a>3.5.1.2. RETURN VALUES</h4></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">PAM_AUTHTOK_ERR</span></dt><dd><p>
             The module was unable to obtain the new authentication token.
          </p></dd><dt><span class="term">PAM_AUTHTOK_RECOVERY_ERR</span></dt><dd><p>
            The module was unable to obtain the old authentication token.
          </p></dd><dt><span class="term">PAM_AUTHTOK_LOCK_BUSY</span></dt><dd><p>
            Cannot change the authentication token since it is currently
            locked.
          </p></dd><dt><span class="term">PAM_AUTHTOK_DISABLE_AGING</span></dt><dd><p>
            Authentication token aging has been disabled.
          </p></dd><dt><span class="term">PAM_PERM_DENIED</span></dt><dd><p>
            Permission denied.
          </p></dd><dt><span class="term">PAM_TRY_AGAIN</span></dt><dd><p>
            Preliminary check was unsuccessful. Signals an immediate
            return to the application is desired.
          </p></dd><dt><span class="term">PAM_SUCCESS</span></dt><dd><p>
             The authentication token was successfully updated.
          </p></dd><dt><span class="term">PAM_USER_UNKNOWN</span></dt><dd><p>
            User unknown to password service.
          </p></dd></dl></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mwg-expected-of-module-session.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mwg-expected-of-module.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mwg-see-options.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.4. Session management </td><td width="20%" align="center"><a accesskey="h" href="Linux-PAM_MWG.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Generic optional arguments</td></tr></table></div></body></html>

3.5. Authentication token management

3.5. Authentication token management
Prev	Chapter 3. What is expected of a module	Next

3.5. Authentication token management

To be correctly initialized, PAM_SM_PASSWORD must be #define'd prior to including <security/pam_modules.h>. This will ensure that the prototypes for static modules are properly declared.

3.5.1. Service function to alter authentication token

#define PAM_SM_PASSWORD

#include <security/pam_modules.h>

`int pam_sm_chauthtok(`	`pamh`,
	`flags`,
	`argc`,
	`argv)`;

pam_handle_t *pamh;
int flags;
int argc;
const char **argv;

3.5.1.1. DESCRIPTION

The pam_sm_chauthtok function is the service module's implementation of the pam_chauthtok(3) interface.

This function is used to (re-)set the authentication token of the user.

Valid flags, which may be logically OR'd with PAM_SILENT, are:

PAM_SILENT

Do not emit any messages.

PAM_CHANGE_EXPIRED_AUTHTOK

This argument indicates to the module that the user's authentication token (password) should only be changed if it has expired. This flag is optional and must be combined with one of the following two flags. Note, however, the following two options are mutually exclusive.

PAM_PRELIM_CHECK

This indicates that the modules are being probed as to their ready status for altering the user's authentication token. If the module requires access to another system over some network it should attempt to verify it can connect to this system on receiving this flag. If a module cannot establish it is ready to update the user's authentication token it should return PAM_TRY_AGAIN, this information will be passed back to the application.

If the control value sufficient is used in the password stack, the PAM_PRELIM_CHECK section of the modules following that control value is not always executed.

PAM_UPDATE_AUTHTOK

This informs the module that this is the call it should change the authorization tokens. If the flag is logically OR'd with PAM_CHANGE_EXPIRED_AUTHTOK, the token is only changed if it has actually expired.

The PAM library calls this function twice in succession. The first time with PAM_PRELIM_CHECK and then, if the module does not return PAM_TRY_AGAIN, subsequently with PAM_UPDATE_AUTHTOK. It is only on the second call that the authorization token is (possibly) changed.

3.5.1.2. RETURN VALUES

PAM_AUTHTOK_ERR: The module was unable to obtain the new authentication token.
PAM_AUTHTOK_RECOVERY_ERR: The module was unable to obtain the old authentication token.
PAM_AUTHTOK_LOCK_BUSY: Cannot change the authentication token since it is currently locked.
PAM_AUTHTOK_DISABLE_AGING: Authentication token aging has been disabled.
PAM_PERM_DENIED: Permission denied.
PAM_TRY_AGAIN: Preliminary check was unsuccessful. Signals an immediate return to the application is desired.
PAM_SUCCESS: The authentication token was successfully updated.
PAM_USER_UNKNOWN: User unknown to password service.

Prev	Up	Next
3.4. Session management	Home	Chapter 4. Generic optional arguments