/usr/share/doc/libpam-doc/html/adg-overview.html is in libpam-doc 1.1.8-1ubuntu2.
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 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 2. Overview</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="Linux-PAM_ADG.html" title="The Linux-PAM Application Developers' Guide"><link rel="up" href="Linux-PAM_ADG.html" title="The Linux-PAM Application Developers' Guide"><link rel="prev" href="adg-introduction-synopsis.html" title="1.2. Synopsis"><link rel="next" href="adg-interface.html" title="Chapter 3. The public interface to Linux-PAM"></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">Chapter 2. Overview</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adg-introduction-synopsis.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="adg-interface.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="adg-overview"></a>Chapter 2. Overview</h1></div></div></div><p>
Most service-giving applications are restricted. In other words,
their service is not available to all and every prospective client.
Instead, the applying client must jump through a number of hoops to
convince the serving application that they are authorized to obtain
service.
</p><p>
The process of <span class="emphasis"><em>authenticating</em></span> a client is what
PAM is designed to manage. In addition to authentication, PAM provides
account management, credential management, session management and
authentication-token (password changing) management services. It is
important to realize when writing a PAM based application that these
services are provided in a manner that is
<span class="emphasis"><em>transparent</em></span> to the application. That is
to say, when the application is written, no assumptions can be made
about <span class="emphasis"><em>how</em></span> the client will be authenticated.
</p><p>
The process of authentication is performed by the PAM library via a
call to <code class="function">pam_authenticate()</code>. The return value
of this function will indicate whether a named client (the
<span class="emphasis"><em>user</em></span>) has been authenticated. If the PAM library
needs to prompt the user for any information, such as their
<span class="emphasis"><em>name</em></span> or a <span class="emphasis"><em>password</em></span>
then it will do so. If the PAM library is configured to authenticate
the user using some silent protocol, it will do this too. (This
latter case might be via some hardware interface for example.)
</p><p>
It is important to note that the application must leave all decisions
about when to prompt the user at the discretion of the PAM library.
</p><p>
The PAM library, however, must work equally well for different styles
of application. Some applications, like the familiar
<span class="command"><strong>login</strong></span> and <span class="command"><strong>passwd</strong></span> are terminal
based applications, exchanges of information with the client in
these cases is as plain text messages. Graphically based applications,
however, have a more sophisticated interface. They generally interact
with the user via specially constructed dialogue boxes. Additionally,
network based services require that text messages exchanged with the
client are specially formatted for automated processing: one such
example is <span class="command"><strong>ftpd</strong></span> which prefixes each exchanged
message with a numeric identifier.
</p><p>
The presentation of simple requests to a client is thus something very
dependent on the protocol that the serving application will use. In
spite of the fact that PAM demands that it drives the whole
authentication process, it is not possible to leave such protocol
subtleties up to the PAM library. To overcome this potential problem,
the application provides the PAM library with a
<span class="emphasis"><em>conversation</em></span> function. This function is called
from <span class="emphasis"><em>within</em></span> the PAM library and enables the PAM
to directly interact with the client. The sorts of things that this
conversation function must be able to do are prompt the user with
text and/or obtain textual input from the user for processing by the
PAM library. The details of this function are provided in a later
section.
</p><p>
For example, the conversation function may be called by the PAM
library with a request to prompt the user for a password. Its job is
to reformat the prompt request into a form that the client will
understand. In the case of <span class="command"><strong>ftpd</strong></span>, this might involve
prefixing the string with the number <span class="command"><strong>331</strong></span> and sending
the request over the network to a connected client. The conversation
function will then obtain any reply and, after extracting the typed
password, will return this string of text to the PAM library. Similar
concerns need to be addressed in the case of an X-based graphical
server.
</p><p>
There are a number of issues that need to be addressed when one is
porting an existing application to become PAM compliant. A section
below has been devoted to this: Porting legacy applications.
</p><p>
Besides authentication, PAM provides other forms of management.
Session management is provided with calls to
<code class="function">pam_open_session()</code> and
<code class="function">pam_close_session()</code>. What these functions
actually do is up to the local administrator. But typically, they
could be used to log entry and exit from the system or for mounting
and unmounting the user's home directory. If an application provides
continuous service for a period of time, it should probably call
these functions, first open after the user is authenticated and then
close when the service is terminated.
</p><p>
Account management is another area that an application developer
should include with a call to <code class="function">pam_acct_mgmt()</code>.
This call will perform checks on the good health of the user's account
(has it expired etc.). One of the things this function may check is
whether the user's authentication token has expired - in such a case the
application may choose to attempt to update it with a call to
<code class="function">pam_chauthtok()</code>, although some applications
are not suited to this task (<span class="command"><strong>ftp</strong></span> for example)
and in this case the application should deny access to the user.
</p><p>
PAM is also capable of setting and deleting the users credentials with
the call <code class="function">pam_setcred()</code>. This function should
always be called after the user is authenticated and before service
is offered to the user. By convention, this should be the last call
to the PAM library before the PAM session is opened. What exactly a
credential is, is not well defined. However, some examples are given
in the glossary below.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adg-introduction-synopsis.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="adg-interface.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.2. Synopsis </td><td width="20%" align="center"><a accesskey="h" href="Linux-PAM_ADG.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3.
The public interface to <span class="emphasis"><em>Linux-PAM</em></span>
</td></tr></table></div></body></html>
|