os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Lots more text, and some markup and whitespace fixes.

Browse source
This commit is contained in:
Dag-Erling Smørgrav 2002-01-12 20:42:39 +00:00
parent 37ae63573a
commit 9dc2ba6133
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=11690
1 changed files with 268 additions and 92 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

360
en_US.ISO8859-1/articles/pam/article.sgml
View file

@ -66,7 +66,7 @@ FreeBSD Entities//EN"> %freebsd;
</authorgroup>
</articleinfo>
<sect1 id="pam-intro">
<section id="pam-intro">
<title id="pam-intro.title">Introduction</title>
<para>The Pluggable Authentication Modules (PAM) library is a
@ -84,31 +84,31 @@ FreeBSD Entities//EN"> %freebsd;
adopted as a standard.</para>
<para>Although this article focuses on FreeBSD's implementation of
PAM (which is based on Linux-PAM), most of it should be
PAM (which is based on Linux-PAM,) most of it should be
applicable to most other operating systems which implement PAM,
including Solaris.</para>
<sect2>
<section>
<title>Trademarks</title>
<para>Sun, Sun Microsystems and Solaris are trademarks or
registered trademarks of Sun Microsystems, Inc.</para>
<para>UNIX and The Open Group are trademarks or registered
trademarks of The Open Group.</para>
<para>All other brand or product names mentioned in this
document may be trademarks or registered trademarks of their
respective owners.</para>
</sect2>
</sect1>
</section>
</section>
<sect1 id="pam-terms">
<section id="pam-terms">
<title id="pam-terms.title">Terms and conventions</title>
<sect2>
<title>Definitions</title>
<section id="pam-definitions">
<title id="pam-definitions.title">Definitions</title>
<para>The terminology surrounding PAM is rather confused.
Neither Samar and Lai's original paper nor the XSSO
specification made any attempt at formally defining terms for
@ -124,6 +124,14 @@ FreeBSD Entities//EN"> %freebsd;
PAM.</para>
<glosslist>
<glossentry>
<glossterm>account</glossterm>
<glossdef>
<para>The set of credentials the applicant is requesting
from the arbitrator.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>applicant</glossterm>
<glossdef>
@ -223,14 +231,6 @@ FreeBSD Entities//EN"> %freebsd;
</glossdef>
</glossentry>
<glossentry>
<glossterm>account</glossterm>
<glossdef>
<para>The set of credentials the applicant is requesting
from the arbitrator.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>token</glossterm>
<glossdef>
@ -250,21 +250,21 @@ FreeBSD Entities//EN"> %freebsd;
</glossdef>
</glossentry>
</glosslist>
</sect2>
</section>
<sect2>
<section>
<title>Usage examples</title>
<para>This section aims to illustrate the meanings of some of
the terms defined above by way of a handful of simple
examples.</para>
<sect3>
<section>
<title>Client and server are one</title>
<para>This simple example shows <literal>alice</literal>
&man.su.1;'ing to <literal>root</literal>.</para>
<screen>&prompt.user; <userinput>whoami</userinput>
alice
&prompt.user; <userinput>ls -l `which su`</userinput>
@ -295,9 +295,9 @@ root
why &man.su.1; is setuid <literal>root</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
</section>
<sect3>
<section>
<title>Client and server are separate</title>
<para>The example below shows <literal>eve</literal> try to
@ -305,7 +305,7 @@ root
<literal>login.example.com</literal>, ask to log in as
<literal>bob</literal>, and succeed. Bob should have chosen
a better password!</para>
<screen>&prompt.user; <userinput>whoami</userinput>
eve
&prompt.user; <userinput>ssh bob@login.example.com</userinput>
@ -341,14 +341,14 @@ Welcome to FreeBSD!
arbitrator is <literal>root</literal>.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
</section>
<section>
<title>Sample policy</title>
<para>The following is FreeBSD's default policy for
<literal>sshd</literal>:</para>
<programlisting>sshd auth required pam_nologin.so no_warn
sshd auth required pam_unix.so no_warn try_first_pass
sshd account required pam_unix.so
@ -360,7 +360,7 @@ sshd password required pam_permit.so</programlisting>
<listitem>
<para>This policy applies to the <literal>sshd</literal>
service (which is not necessarily restricted to the
&man.sshd.8; server).</para>
&man.sshd.8; server.)</para>
</listitem>
<listitem>
<para><literal>auth</literal>, <literal>account</literal>,
@ -377,28 +377,29 @@ sshd password required pam_permit.so</programlisting>
facilities each.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</section>
</section>
<sect2>
<section>
<title>Conventions</title>
<para>This section is intentionally left blank.</para>
</sect2>
</sect1>
</section>
</section>
<sect1 id="pam-essentials">
<section id="pam-essentials">
<title id="pam-essentials.title">PAM Essentials</title>
<sect2>
<title>Facilities and primitives</title>
<section id="pam-facilities-primitives">
<title id="pam-facilities-primitives.title">Facilities and
primitives</title>
<para>The PAM API offers six different authentication primitives
grouped in four facilities, which are described below.</para>
<variablelist>
<varlistentry>
<term>auth</term>
<term><literal>auth</literal></term>
<listitem>
<para><emphasis>Authentication.</emphasis> This facility
concerns itself with authenticating the applicant and
@ -422,9 +423,9 @@ sshd password required pam_permit.so</programlisting>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>account</term>
<term><literal>account</literal></term>
<listitem>
<para><emphasis>Account management.</emphasis> This
facility handles non-authentication-related issues of
@ -440,9 +441,9 @@ sshd password required pam_permit.so</programlisting>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>session</term>
<term><literal>session</literal></term>
<listitem>
<para><emphasis>Session management.</emphasis> This
facility handles tasks associated with session set-up
@ -468,9 +469,9 @@ sshd password required pam_permit.so</programlisting>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>password</term>
<term><literal>password</literal></term>
<listitem>
<para><emphasis>Password management.</emphasis> This
facility is used to change the authentication token
@ -489,10 +490,10 @@ sshd password required pam_permit.so</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2>
</section>
<section>
<title>Modules</title>
<para>Modules are a very central concept in PAM; after all,
@ -504,29 +505,188 @@ sshd password required pam_permit.so</programlisting>
password database, NIS, LDAP and Radius.</para>
<para>FreeBSD groups all facilities for the same mechanism in
one module called <literal>pam_mechanism.so</literal>. The
original PAM implementation, on the other hand, had separate
modules for each facility, called
<literal>pam_mechanism_facility.so</literal>.</para>
</sect2>
one module called <literal>pam_mechanism.so</literal> (e.g.
<literal>pam_unix.so</literal>.) The original PAM
implementation, on the other hand, had separate modules for
each facility, called
<literal>pam_mechanism_facility.so</literal> (e.g.
<literal>pam_unix_auth.so</literal>.)</para>
</section>
<sect2>
<title>Chains and policies</title>
<para>Explain chains and policies</para>
</sect2>
<section id="pam-chains-policies">
<title id="pam-chains-policies.title">Chains and
policies</title>
<sect2>
<para>When a server initiates a PAM transaction, the PAM library
tries to load a policy for the service specified in the
<function>pam_start</function> call. The policy specifies how
authentication requests should be processed, and is defined in
a configuration file. This is the other central concept in
PAM: the possibility for the admin to tune the system security
policy (in the wider sense of the word) simply by editing a
text file.</para>
<para>A policy consists of four chains, one for each of the four
PAM facilities. Each chain is a sequence of configuration
statements, each specifying a module to invoke, some
(optional) parameters to pass to the module, and a control
flag that describes how to interpret the return code from the
module.</para>
<para>Understanding the control flags is essential to
understanding PAM configuration files. There are four
different control flags:</para>
<variablelist>
<varlistentry>
<term><literal>required</literal></term>
<listitem>
<para>Success is required, but the chain continues no
matter what this module returns, so that later modules
can override it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>requisite</literal></term>
<listitem>
<para>A negative result from this module will immediately
terminate the chain and deny the request.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>sufficient</literal></term>
<listitem>
<para>A positive result from this module will immediately
terminate the chain and grant the request. On failure,
the chain continues.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>optional</literal></term>
<listitem>
<para>A negative result from this module will be
ignored.</para>
</listitem>
</varlistentry>
</variablelist>
<para>When a server invokes one of the six PAM primitives, PAM
retrieves the chain for the facility the primitive belongs to,
and invokes each of the modules listed in the chain, in the
order they're listed, until it reaches the end, or determines
that no further processing is necessary (either because a
<literal>sufficient</literal> module succeeded, or because a
<literal>requisite</literal> module failed.) The request is
granted if and only if at least one module was invoked, and
all non-optional modules succeeded.</para>
<para>Note that it is possible, though not very common, to have
the same module listed several times in the same chain. For
instance, a module that looks up user names and passwords in a
directory server could be invoked multiple times with
different parameters specifying different directory servers to
contact. PAM treat different occurrences of the same module
in the same chain as different, unrelated modules.</para>
</section>
<section>
<title>Transactions</title>
<para>Describe a transaction from start to finish</para>
</sect2>
</sect1>
<sect1 id="pam-config">
<para>The lifecycle of a typical PAM transaction goes like
this:</para>
<orderedlist>
<listitem>
<para>If necessary, the server obtains arbitrator
credentials through a mechanism independent of
PAM&mdash;most commonly by virtue of having been started
by <literal>root</literal>, or of being setuid
<literal>root</literal>.</para>
</listitem>
<listitem>
<para>The server calls <function>pam_start</function> to
initialize the PAM library and specify its service name
and the target account, and register a suitable
conversation function.</para>
</listitem>
<listitem>
<para>The server obtains various information relating to the
transaction (such as the applicant's user name and the
name of the host the client runs on) and submits it to PAM
using <function>pam_set_item</function>.</para>
</listitem>
<listitem>
<para>The server calls <function>pam_authenticate</function>
to authenticate the applicant. If
<function>pam_authenticate</function> returns something
else than <literal>PAM_SUCCESS</literal> or
<literal>PAM_NEW_AUTHTOK_REQD</literal>, it notifies the
client that the request was denied, and aborts the
transaction.</para>
</listitem>
<listitem>
<para>If the previous step returned
<literal>PAM_NEW_AUTHTOK_REQD</literal>, the server now
calls <function>pam_chauthtok</function> to force the
client to change the authentication token for the
requested account. If this fails, the server aborts the
transaction.</para>
</listitem>
<listitem>
<para>The server calls <function>pam_acct_mgmt</function> to
verify that the requested account is available. If this
fails, the server aborts the transaction.</para>
</listitem>
<listitem>
<para>Now that the applicant has been properly
authenticated, the server calls
<function>pam_setcred</function> to establish the
credentials of the requested account. It is able to do
this because it acts on behalf of the arbitrator, and
holds the arbitrator's credentials.</para>
</listitem>
<listitem>
<para>Once the correct credentials have been established,
the server calls <function>pam_open_session</function> to
set up the session.</para>
</listitem>
<listitem>
<para>The server now performs whatever service the client
requested&mdash;for instance, provide the applicant with a
shell.</para>
</listitem>
<listitem>
<para>Once the server is done serving the client, it alls
<function>pam_close_session</function> to tear down the
session.</para>
</listitem>
<listitem>
<para>Finally, the server calls <function>pam_end</function>
to notify the PAM library that it is done and that it can
release whatever resources it has allocated in the course
of the transaction.</para>
</listitem>
</orderedlist>
</section>
</section>
<section id="pam-config">
<title id="pam-config.title">PAM Configuration</title>
<sect2>
<section>
<title>Location of configuration files</title>
<para>The traditional PAM configuration file is
@ -557,8 +717,8 @@ sshd password required pam_permit.so</programlisting>
where policies are contained in separate files, named for the
service they apply to, in <filename>/etc/pam.d/</filename>,
with only four fields instead of five&mdash;the service name
field is omitted. In FreeBSD 5.0, starting from mid-December
2001, this is the preferred mechanism. Note, however, that if
field is omitted. In FreeBSD 5.0, starting from mid-January
2002, this is the preferred mechanism. Note, however, that if
<filename>/etc/pam.conf</filename> exists, and contains
configuration statements for services which do not have a
specific policy in <filename>/etc/pam.d/</filename>, it will
@ -587,9 +747,9 @@ sshd password required pam_permit.so</programlisting>
<filename>/etc/pam.d/</filename>, the policy for the special
service <literal>other</literal> is used as a fall-back for
any service that does not have its own policy.</para>
</sect2>
</section>
<sect2>
<section>
<title>Breakdown of a configuration line</title>
<para>As explained in the previous section, each line in
@ -609,38 +769,54 @@ sshd password required pam_permit.so</programlisting>
facility name.</para>
<para>The facility is one of the four facility keywords
described in the <link linkend="pam-essentials"
endterm="pam-essentials.title"></link> chapter.</para>
</sect2>
described in the <link linkend="pam-facilities-primitives"
endterm="pam-facilities-primitives.title"></link>
section.</para>
<sect2>
<para>Likewise, the control flag is one of the four keywords
described in the <link linkend="pam-chains-policies"
endterm="pam-chains-policies.title"></link> section,
describing how to interpret the return code from the module.
Linux-PAM supports an alternate syntax that lets you specify
the action to associate with each possible return code, but
this should be avoided as it is non-standard and requires very
detailed knowledge of the PAM library to use properly.</para>
</section>
<section>
<title>Policies</title>
<para></para>
</sect2>
</sect1>
</section>
</section>
<sect1 id="pam-modules">
<section id="pam-modules">
<title id="pam-modules.title">PAM Modules</title>
<para>This chapter briefly documents the various PAM modules that
exist in FreeBSD.</para>
</sect1>
</section>
<sect1 id="pam-appl-prog">
<section id="pam-appl-prog">
<title id="pam-appl-prog.title">PAM Application Programming</title>
<para>This chapter describes how to integrate PAM into your
application.</para>
</sect1>
</section>
<sect1 id="pam-module-prog">
<section id="pam-module-prog">
<title id="pam-module-prog.title">PAM Module Programming</title>
<para>This chapter describes how to write PAM modules.</para>
</sect1>
<sect1 id="pam-further">
</section>
<appendix id="pam-sample-appl">
<title id="pam-sample-appl.title">Sample PAM application</title>
<para>Source code for a minimal &man.su.1; workalike</para>
</appendix>
<appendix id="pam-further">
<title id="pam-further.title">Further Reading</title>
<para>This is a list of documents relevant to PAM and related
@ -649,10 +825,10 @@ sshd password required pam_permit.so</programlisting>
<itemizedlist>
<listitem>
<para><ulink
url="http://www.sun.com/software/solaris/pam/pam.external.pdf">
Making Login Services Independent of Authentication
Technologies</ulink>&mdash;the original PAM whitepaper from
Sun.</para>
url="http://www.sun.com/software/solaris/pam/pam.external.pdf">
Making Login Services Independent of Authentication
Technologies</ulink>&mdash;the original PAM whitepaper from
Sun.</para>
</listitem>
<listitem>
<para><ulink
@ -665,7 +841,7 @@ sshd password required pam_permit.so</programlisting>
url="http://www.opengroup.org/pubs/catalog/p702.htm"> X/Open
Single Sign-on Preliminary Specification</ulink> (OpenGroup
members can get the PDF; others will have to register to
download the text version, or buy the paper version).</para>
download the text version, or buy the paper version.)</para>
</listitem>
<listitem>
<para><ulink
@ -674,5 +850,5 @@ sshd password required pam_permit.so</programlisting>
by Andrew G. Morgan, author of Linux-PAM.</para>
</listitem>
</itemizedlist>
</sect1>
</appendix>
</article>