Checkpoint commit.
This commit is contained in:
Dag-Erling Smørgrav
parent
d96e752816
commit
5089c5210c
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=11398
1 changed files with 249 additions and 24 deletions
|
|
@ -33,7 +33,7 @@ FreeBSD Entities//EN"> %freebsd;
|
|||
</articleinfo>
|
||||
|
||||
<sect1 id="pam-intro">
|
||||
<title>Introduction</title>
|
||||
<title id="pam-intro.title">Introduction</title>
|
||||
|
||||
<para>The Pluggable Authentication Modules (PAM) library is a
|
||||
generalized API for authentication-related services which allows
|
||||
|
|
@ -62,11 +62,15 @@ FreeBSD Entities//EN"> %freebsd;
|
|||
|
||||
<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>
|
||||
|
||||
<sect1 id="pam-terms">
|
||||
<title>Terms and conventions</title>
|
||||
<title id="pam-terms.title">Terms and conventions</title>
|
||||
|
||||
<sect2>
|
||||
<title>Definitions</title>
|
||||
|
|
@ -186,17 +190,17 @@ FreeBSD Entities//EN"> %freebsd;
|
|||
</glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>target</glossterm>
|
||||
<glossterm>account</glossterm>
|
||||
<glossdef>
|
||||
<para>The user or entity whose credentials the applicant
|
||||
is requesting.</para>
|
||||
<para>The set of credentials the applicant is requesting
|
||||
from the arbitrator.</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>token</glossterm>
|
||||
<glossdef>
|
||||
<para>A chunk of information associated with the target,
|
||||
<para>A chunk of information associated with the account,
|
||||
such as a password or passphrase, which the applicant
|
||||
must provide to prove his identity.</para>
|
||||
</glossdef>
|
||||
|
|
@ -233,7 +237,8 @@ alice
|
|||
-r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su
|
||||
&prompt.user; <userinput>su -</userinput>
|
||||
Password: <userinput>xi3kiune</userinput>
|
||||
&prompt.root;
|
||||
&prompt.root; whoami
|
||||
root
|
||||
</screen>
|
||||
|
||||
<itemizedlist>
|
||||
|
|
@ -241,7 +246,7 @@ Password: <userinput>xi3kiune</userinput>
|
|||
<para>The applicant is <literal>alice</literal>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The target is <literal>root</literal>.</para>
|
||||
<para>The account is <literal>root</literal>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The &man.su.1; process is both client and
|
||||
|
|
@ -261,7 +266,7 @@ Password: <userinput>xi3kiune</userinput>
|
|||
<sect3>
|
||||
<title>Client and server are separate</title>
|
||||
|
||||
<para>The example below shows <literal>alice</literal> try to
|
||||
<para>The example below shows <literal>eve</literal> try to
|
||||
initiate an &man.ssh.1; connection to
|
||||
<literal>login.example.com</literal>, ask to log in as
|
||||
<literal>bob</literal>, and succeed. Bob should have chosen
|
||||
|
|
@ -291,7 +296,7 @@ Welcome to FreeBSD!
|
|||
<literal>login.example.com</literal></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The target is <literal>bob</literal>.</para>
|
||||
<para>The account is <literal>bob</literal>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The authentication token is
|
||||
|
|
@ -310,11 +315,11 @@ Welcome to FreeBSD!
|
|||
<para>The following is FreeBSD's default policy for
|
||||
<literal>sshd</literal>:</para>
|
||||
|
||||
<screen>sshd auth required pam_nologin.so no_warn
|
||||
<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
|
||||
sshd session required pam_permit.so
|
||||
sshd password required pam_permit.so</screen>
|
||||
sshd password required pam_permit.so</programlisting>
|
||||
|
||||
|
||||
<itemizedlist>
|
||||
|
|
@ -349,40 +354,260 @@ sshd password required pam_permit.so</screen>
|
|||
</sect1>
|
||||
|
||||
<sect1 id="pam-essentials">
|
||||
<title>PAM Essentials</title>
|
||||
<title id="pam-essentials.title">PAM Essentials</title>
|
||||
|
||||
<para>This section describes the central concepts of PAM.</para>
|
||||
<sect2>
|
||||
<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>
|
||||
<listitem>
|
||||
<para><emphasis>Authentication.</emphasis> This facility
|
||||
concerns itself with authenticating the applicant and
|
||||
establishing the account credentials. It provides two
|
||||
primitives:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><function>pam_authenticate</function>
|
||||
authenticates the applicant, usually by requesting
|
||||
an authentication token and comparing it with a
|
||||
value stored in a database or obtained from an
|
||||
authentication server.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><function>pam_setcred</function> establishes
|
||||
account credentials such as user ID, group
|
||||
membership and resource limits.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>account</term>
|
||||
<listitem>
|
||||
<para><emphasis>Account management.</emphasis> This
|
||||
facility handles non-authentication-related issues of
|
||||
account availability, such as access restrictions based
|
||||
on the time of day or the server's work load. It
|
||||
provides a single primitive:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><function>pam_acct_mgmt</function> verifies that
|
||||
the requested account is available.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>session</term>
|
||||
<listitem>
|
||||
<para><emphasis>Session management.</emphasis> This
|
||||
facility handles tasks associated with session set-up
|
||||
and tear-down, such as login accounting. It provides
|
||||
two primitives:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><function>pam_open_session</function> performs
|
||||
tasks associated with session set-up: add an entry
|
||||
in the <filename>utmp</filename> and
|
||||
<filename>wtmp</filename> databases, start an SSH
|
||||
agent, etc.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><function>pam_close_session</function> performs
|
||||
tasks associated with session tear-down: add an
|
||||
entry in the <filename>utmp</filename> and
|
||||
<filename>wtmp</filename> databases, stop the SSH
|
||||
agent, etc.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>password</term>
|
||||
<listitem>
|
||||
<para><emphasis>Password management.</emphasis> This
|
||||
facility is used to change the authentication token
|
||||
associated with an account, either because it has
|
||||
expired or because the user wishes to change it. It
|
||||
provides a single primitive:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><function>pam_chauthtok</function> changes the
|
||||
authentication token, optionally verifying that it
|
||||
is sufficiently hard to guess, has not been used
|
||||
previously, etc.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Modules</title>
|
||||
|
||||
<para>Modules are a very central concept in PAM; after all,
|
||||
they're the <quote>M</quote> in <quote>PAM</quote>. A PAM
|
||||
module is a self-contained piece of program code that
|
||||
implements the primitives in one or more facilities for one
|
||||
particular mechanism; possible mechanisms for the
|
||||
authentication facility, for instance, include the UNIX
|
||||
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>
|
||||
|
||||
<sect2>
|
||||
<title>Chains and policies</title>
|
||||
|
||||
<para>Explain chains and policies</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Transactions</title>
|
||||
|
||||
<para>Describe a transaction from start to finish</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="pam-config">
|
||||
<title>PAM Configuration</title>
|
||||
<title id="pam-config.title">PAM Configuration</title>
|
||||
|
||||
<para>This section describes how to configure PAM on
|
||||
FreeBSD.</para>
|
||||
<sect2>
|
||||
<title>Location of configuration files</title>
|
||||
|
||||
<para>The traditional PAM configuration file is
|
||||
<filename>/etc/pam.conf</filename>. This file contains all
|
||||
the PAM policies for your system. Each line of the file
|
||||
describes one step in a chain, as shown below:</para>
|
||||
|
||||
<programlisting>login auth required pam_nologin.so no_warn</programlisting>
|
||||
|
||||
<para>The fields are, in order: service name, facility name,
|
||||
control flag, module name, and module arguments. Any
|
||||
additional fields are interpreted as additional module
|
||||
arguments.</para>
|
||||
|
||||
<para>A separate chain is constructed for each service /
|
||||
facility pair, so while the order in which lines for the same
|
||||
service and facility appear is significant, the order in which
|
||||
the individual services and facilities are listed is
|
||||
not—except that entries for the <literal>other</literal>
|
||||
service, which serves as a fall-back, should come last. The
|
||||
examples in the original PAM paper grouped configuration lines
|
||||
by facility, and Solaris' stock <filename>pam.conf</filename>
|
||||
still does that, but Linux-PAM (and hence FreeBSD) groups
|
||||
configuration lines by service. Either way is fine; either
|
||||
way makes equal sense.</para>
|
||||
|
||||
<para>Linux-PAM offers an alternate configuration mechanism,
|
||||
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—the service name
|
||||
field is omitted. In FreeBSD 5.0, starting from mid-December
|
||||
2001, 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
|
||||
be used as a fall-back for these services.</para>
|
||||
|
||||
<para>The great advantage of <filename>/etc/pam.d/</filename>
|
||||
over <filename>/etc/pam.conf</filename> is that it is possible
|
||||
to use the same policy for multiple services by linking each
|
||||
service name to a same policy file. For instance, to use the
|
||||
same policy for the <literal>su</literal> and
|
||||
<literal>sudo</literal> services, one could do as
|
||||
follows:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /etc/pam.d</userinput>
|
||||
&prompt.root; <userinput>ln -s su sudo</userinput></screen>
|
||||
|
||||
<para>This works because the service name is determined from the
|
||||
file name rather than specified in the policy file, so the
|
||||
same file can be used for arbitrary services.</para>
|
||||
|
||||
<para>One other advantage is that third-party software can
|
||||
easily install policies for their services without the need to
|
||||
edit <filename>/etc/pam.conf</filename>.</para>
|
||||
|
||||
<para>Whether you use <filename>/etc/pam.conf</filename> or
|
||||
<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>
|
||||
|
||||
<sect2>
|
||||
<title>Breakdown of a configuration line</title>
|
||||
|
||||
<para>As explained in the previous section, each line in
|
||||
<literal>/etc/pam.conf</literal> consists of four or more
|
||||
fields: the service name, the facility name, the control flag,
|
||||
the module name, and zero or more module arguments.</para>
|
||||
|
||||
<para>The service name is generally (though not always) the name
|
||||
of the application the statement applies to. If you're
|
||||
unsure, refer to the individual application's documentation to
|
||||
determine what service name it uses.</para>
|
||||
|
||||
<para>Note that if you use <filename>/etc/pam.d/</filename>
|
||||
instead of <filename>/etc/pam.conf</filename>, the service
|
||||
name is specified by the name of the policy file, and omitted
|
||||
from the actual configuration lines, which then start with the
|
||||
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>
|
||||
|
||||
<sect2>
|
||||
<title>Policies</title>
|
||||
|
||||
<para></para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="pam-modules">
|
||||
<title>PAM Modules</title>
|
||||
<title id="pam-modules.title">PAM Modules</title>
|
||||
|
||||
<para>This section briefly documents the various PAM modules that
|
||||
<para>This chapter briefly documents the various PAM modules that
|
||||
exist in FreeBSD.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="pam-appl-prog">
|
||||
<title>PAM Application Programming</title>
|
||||
<title id="pam-appl-prog.title">PAM Application Programming</title>
|
||||
|
||||
<para>This section describes how to integrate PAM into your
|
||||
<para>This chapter describes how to integrate PAM into your
|
||||
application.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="pam-module-prog">
|
||||
<title>PAM Module Programming</title>
|
||||
<title id="pam-module-prog.title">PAM Module Programming</title>
|
||||
|
||||
<para>This section describes how to write PAM modules.</para>
|
||||
<para>This chapter describes how to write PAM modules.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="pam-further">
|
||||
<title>Further Reading</title>
|
||||
<title id="pam-further.title">Further Reading</title>
|
||||
|
||||
<para>This is a list of documents relevant to PAM and related
|
||||
issues. It is by no means complete.</para>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue