/usr/share/doc/libpam-doc/html/mwg-expected-of-module-overview.html is in libpam-doc 1.1.8-1ubuntu2.2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>3.1. Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><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.html" title="Chapter 3. What is expected of a module"><link rel="next" href="mwg-expected-of-module-auth.html" title="3.2. Authentication management"></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.1. Overview</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="mwg-expected-of-module.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-expected-of-module-auth.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-overview"></a>3.1. Overview</h2></div></div></div><p>
The six module functions are grouped into four independent
management groups. These groups are as follows:
<span class="emphasis"><em>authentication</em></span>, <span class="emphasis"><em>account</em></span>,
<span class="emphasis"><em>session</em></span> and <span class="emphasis"><em>password</em></span>.
To be properly defined, a module must define all functions within
at least one of these groups. A single module may contain the
necessary functions for <span class="emphasis"><em>all</em></span> four groups.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mwg-expected-of-module-overview-1"></a>3.1.1. Functional independence</h3></div></div></div><p>
The independence of the four groups of service a module can
offer means that the module should allow for the possibility
that any one of these four services may legitimately be called
in any order. Thus, the module writer should consider the
appropriateness of performing a service without the prior
success of some other part of the module.
</p><p>
As an informative example, consider the possibility that an
application applies to change a user's authentication token,
without having first requested that
<span class="emphasis"><em>Linux-PAM</em></span> authenticate the
user. In some cases this may be deemed appropriate: when
<span class="command"><strong>root</strong></span> wants to change the authentication
token of some lesser user. In other cases it may not be
appropriate: when <span class="command"><strong>joe</strong></span> maliciously wants
to reset <span class="command"><strong>alice</strong></span>'s password; or when anyone
other than the user themself wishes to reset their
<span class="emphasis"><em>KERBEROS</em></span> authentication token. A policy
for this action should be defined by any reasonable
authentication scheme, the module writer should consider
this when implementing a given module.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mwg-expected-of-module-overview-2"></a>3.1.2. Minimizing administration problems</h3></div></div></div><p>
To avoid system administration problems and the poor
construction of a <code class="filename">/etc/pam.conf</code> file,
the module developer may define all six of the following
functions. For those functions that would not be called,
the module should return <span class="errorname">PAM_SERVICE_ERR</span>
and write an appropriate message to the system log. When
this action is deemed inappropriate, the function would
simply return <span class="errorname">PAM_IGNORE</span>.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="mwg-expected-of-module-overview-3"></a>3.1.3. Arguments supplied to the module</h3></div></div></div><p>
The <em class="parameter"><code>flags</code></em> argument of each of
the following functions can be logically OR'd with
<em class="parameter"><code>PAM_SILENT</code></em>, which is used to inform the
module to not pass any <span class="emphasis"><em>text</em></span> (errors or
warnings) application.
</p><p>
The <em class="parameter"><code>argc</code></em> and <em class="parameter"><code>argv</code></em>
arguments are taken from the line appropriate to this
module---that is, with the <span class="emphasis"><em>service_name</em></span>
matching that of the application---in the configuration file
(see the <span class="emphasis"><em>Linux-PAM</em></span>
System Administrators' Guide). Together these two parameters
provide the number of arguments and an array of pointers to
the individual argument tokens. This will be familiar to C
programmers as the ubiquitous method of passing command arguments
to the function <code class="function">main()</code>. Note, however, that
the first argument (<em class="parameter"><code>argv[0]</code></em>) is a true
argument and <span class="emphasis"><em>not</em></span> the name of the module.
</p></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.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-expected-of-module-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. What is expected of a module </td><td width="20%" align="center"><a accesskey="h" href="Linux-PAM_MWG.html">Home</a></td><td width="40%" align="right" valign="top"> 3.2. Authentication management</td></tr></table></div></body></html>
|