From 9ada0093e92388590c7368600ca4e9e3e376f0d0 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:22:51 +0200 Subject: Adding upstream version 1.5.2. Signed-off-by: Daniel Baumann --- doc/sag/Linux-PAM_SAG.xml | 570 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 570 insertions(+) create mode 100644 doc/sag/Linux-PAM_SAG.xml (limited to 'doc/sag/Linux-PAM_SAG.xml') diff --git a/doc/sag/Linux-PAM_SAG.xml b/doc/sag/Linux-PAM_SAG.xml new file mode 100644 index 0000000..0f33e0f --- /dev/null +++ b/doc/sag/Linux-PAM_SAG.xml @@ -0,0 +1,570 @@ + + + + + The Linux-PAM System Administrators' Guide + + + Andrew G. + Morgan + morgan@kernel.org + + + Thorsten + Kukuk + kukuk@thkukuk.de + + + Version 1.1.2, 31. August 2010 + + + This manual documents what a system-administrator needs to know about + the Linux-PAM library. It covers the + correct syntax of the PAM configuration file and discusses strategies + for maintaining a secure system. + + + + + + Introduction + + Linux-PAM (Pluggable Authentication + Modules for Linux) is a suite of shared libraries that enable the + local system administrator to choose how applications authenticate users. + + + In other words, without (rewriting and) recompiling a PAM-aware + application, it is possible to switch between the authentication + mechanism(s) it uses. Indeed, one may entirely upgrade the local + authentication system without touching the applications themselves. + + + Historically an application that has required a given user to be + authenticated, has had to be compiled to use a specific authentication + mechanism. For example, in the case of traditional UN*X systems, the + identity of the user is verified by the user entering a correct + password. This password, after being prefixed by a two character + ``salt'', is encrypted (with crypt(3)). The user is then authenticated + if this encrypted password is identical to the second field of the + user's entry in the system password database (the + /etc/passwd file). On such systems, most if + not all forms of privileges are granted based on this single + authentication scheme. Privilege comes in the form of a personal + user-identifier (UID) and membership of various groups. Services and + applications are available based on the personal and group identity + of the user. Traditionally, group membership has been assigned based + on entries in the /etc/group file. + + + It is the purpose of the Linux-PAM + project to separate the development of privilege granting software + from the development of secure and appropriate authentication schemes. + This is accomplished by providing a library of functions that an + application may use to request that a user be authenticated. This + PAM library is configured locally with a system file, + /etc/pam.conf (or a series of configuration + files located in /etc/pam.d/) to authenticate a + user request via the locally available authentication modules. The + modules themselves will usually be located in the directory + /lib/security or + /lib64/security and take the form of dynamically + loadable object files (see + dlopen3 + ). + + + + + Some comments on the text + + Before proceeding to read the rest of this document, it should be + noted that the text assumes that certain files are placed in certain + directories. Where they have been specified, the conventions we adopt + here for locating these files are those of the relevant RFC (RFC-86.0, + see bibliography"). If you are + using a distribution of Linux (or some other operating system) that + supports PAM but chooses to distribute these files in a different way + you should be careful when copying examples directly from the text. + + + As an example of the above, where it is explicit, the text assumes + that PAM loadable object files (the + modules) are to be located in + the following directory: /lib/security/ or + /lib64/security depending on the architecture. + This is generally the location that seems to be compatible with the + Filesystem Hierarchy Standard (FHS). On Solaris, which has its own + licensed version of PAM, and some other implementations of UN*X, + these files can be found in /usr/lib/security. + Please be careful to perform the necessary transcription when using + the examples from the text. + + + + + Overview + + For the uninitiated, we begin by considering an example. We take an + application that grants some service to users; + login is one such program. + Login does two things, it first establishes that + the requesting user is whom they claim to be and second provides + them with the requested service: in the case of + login the service is a command shell + (bash, tcsh, zsh, etc.) running with the identity of the user. + + + Traditionally, the former step is achieved by the + login application prompting the user for a + password and then verifying that it agrees with that located on + the system; hence verifying that as far as the system is concerned + the user is who they claim to be. This is the task that is delegated + to Linux-PAM. + + + From the perspective of the application programmer (in this case + the person that wrote the login application), + Linux-PAM takes care of this + authentication task -- verifying the identity of the user. + + + The flexibility of Linux-PAM is + that you, the system administrator, have + the freedom to stipulate which authentication scheme is to be + used. You have the freedom to set the scheme for any/all + PAM-aware applications on your Linux system. That is, you can + authenticate from anything as naive as + simple trust (pam_permit) + to something as paranoid as a combination of a retinal scan, a + voice print and a one-time password! + + + To illustrate the flexibility you face, consider the following + situation: a system administrator (parent) wishes to improve the + mathematical ability of her users (children). She can configure + their favorite ``Shoot 'em up game'' (PAM-aware of course) to + authenticate them with a request for the product of a couple of + random numbers less than 12. It is clear that if the game is any + good they will soon learn their + multiplication tables. As they mature, the + authentication can be upgraded to include (long) division! + + + Linux-PAM deals with four + separate types of (management) task. These are: + authentication management; + account management; + session management; and + password management. + The association of the preferred management scheme with the behavior + of an application is made with entries in the relevant + Linux-PAM configuration file. + The management functions are performed by modules + specified in the configuration file. The syntax for this + file is discussed in the section + below. + + + Here is a figure that describes the overall organization of + Linux-PAM: + + +----------------+ + | application: X | + +----------------+ / +----------+ +================+ + | authentication-[---->--\--] Linux- |--<--| PAM config file| + | + [----<--/--] PAM | |================| + |[conversation()][--+ \ | | | X auth .. a.so | + +----------------+ | / +-n--n-----+ | X auth .. b.so | + | | | __| | | _____/ + | service user | A | | |____,-----' + | | | V A + +----------------+ +------|-----|---------+ -----+------+ + +---u-----u----+ | | | + | auth.... |--[ a ]--[ b ]--[ c ] + +--------------+ + | acct.... |--[ b ]--[ d ] + +--------------+ + | password |--[ b ]--[ c ] + +--------------+ + | session |--[ e ]--[ c ] + +--------------+ + + By way of explanation, the left of the figure represents the + application; application X. Such an application interfaces with the + Linux-PAM library and knows none of + the specifics of its configured authentication method. The + Linux-PAM library (in the center) + consults the contents of the PAM configuration file and loads the + modules that are appropriate for application-X. These modules fall + into one of four management groups (lower-center) and are stacked in + the order they appear in the configuration file. These modules, when + called by Linux-PAM, perform the + various authentication tasks for the application. Textual information, + required from/or offered to the user, can be exchanged through the + use of the application-supplied conversation + function. + + + If a program is going to use PAM, then it has to have PAM + functions explicitly coded into the program. If you have + access to the source code you can add the appropriate PAM + functions. If you do not have access to the source code, and + the binary does not have the PAM functions included, then + it is not possible to use PAM. + + + + + The Linux-PAM configuration file + +
+ Configuration file syntax + +
+
+ Directory based configuration + +
+
+ Example configuration file entries + + In this section, we give some examples of entries that can + be present in the Linux-PAM + configuration file. As a first attempt at configuring your + system you could do worse than to implement these. + + + If a system is to be considered secure, it had better have a + reasonably secure 'other entry. + The following is a paranoid setting (which is not a bad place + to start!): + + +# +# default; deny access +# +other auth required pam_deny.so +other account required pam_deny.so +other password required pam_deny.so +other session required pam_deny.so + + + Whilst fundamentally a secure default, this is not very + sympathetic to a misconfigured system. For example, such + a system is vulnerable to locking everyone out should the + rest of the file become badly written. + + + The module pam_deny (documented in a + later section) is not very + sophisticated. For example, it logs no information when it + is invoked so unless the users of a system contact the + administrator when failing to execute a service application, + the administrator may go for a long while in ignorance of the + fact that his system is misconfigured. + + + The addition of the following line before those in the above + example would provide a suitable warning to the administrator. + + +# +# default; wake up! This application is not configured +# +other auth required pam_warn.so +other password required pam_warn.so + + + Having two 'other auth' lines is an + example of stacking. + + + On a system that uses the /etc/pam.d/ + configuration, the corresponding default setup would be + achieved with the following file: + + +# +# default configuration: /etc/pam.d/other +# +auth required pam_warn.so +auth required pam_deny.so +account required pam_deny.so +password required pam_warn.so +password required pam_deny.so +session required pam_deny.so + + + This is the only explicit example we give for an + /etc/pam.d/ file. In general, it + should be clear how to transpose the remaining examples + to this configuration scheme. + + + On a less sensitive computer, one on which the system + administrator wishes to remain ignorant of much of the + power of Linux-PAM, the + following selection of lines (in + /etc/pam.d/other) is likely to + mimic the historically familiar Linux setup. + + +# +# default; standard UN*X access +# +auth required pam_unix.so +account required pam_unix.so +password required pam_unix.so +session required pam_unix.so + + + In general this will provide a starting place for most applications. + +
+ + + + Security issues +
+ If something goes wrong + + Linux-PAM has the potential + to seriously change the security of your system. You can + choose to have no security or absolute security (no access + permitted). In general, Linux-PAM + errs towards the latter. Any number of configuration errors + can disable access to your system partially, or completely. + + + The most dramatic problem that is likely to be encountered when + configuring Linux-PAM is that of + deleting the configuration file(s): + /etc/pam.d/* and/or + /etc/pam.conf. This will lock you out of + your own system! + + + To recover, your best bet is to restore the system from a + backup or boot the system into a rescue system and correct + things from there. + +
+
+ Avoid having a weak `other' configuration + + It is not a good thing to have a weak default + (other) entry. + This service is the default configuration for all PAM aware + applications and if it is weak, your system is likely to be + vulnerable to attack. + + + Here is a sample "other" configuration file. The + pam_deny module will deny access and the + pam_warn module will send a syslog message + to auth.notice: + + +# +# The PAM configuration file for the `other' service +# +auth required pam_deny.so +auth required pam_warn.so +account required pam_deny.so +account required pam_warn.so +password required pam_deny.so +password required pam_warn.so +session required pam_deny.so +session required pam_warn.so + +
+ + + + A reference guide for available modules + + Here, we collect together the descriptions of the various modules + coming with Linux-PAM. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + See also + + + + The Linux-PAM Application Writers' Guide. + + + + + The Linux-PAM Module Writers' Guide. + + + + + The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH + PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation + Request For Comments 86.0, October 1995. + + + + + + + Author/acknowledgments + + This document was written by Andrew G. Morgan (morgan@kernel.org) + with many contributions from + Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger, + Craig S. Bell, Derrick J. Brashear, Ben Buxton, Seth Chaiklin, + Oliver Crow, Chris Dent, Marc Ewing, Cristian Gafton, + Emmanuel Galanos, Brad M. Garcia, Eric Hester, Michel D'Hooge, + Roger Hu, Eric Jacksch, Michael K. Johnson, David Kinchlea, + Olaf Kirch, Marcin Korzonek, Thorsten Kukuk, Stephen Langasek, + Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton, + Al Longyear, Ingo Luetkebohle, Marek Michalkiewicz, + Robert Milkowski, Aleph One, Martin Pool, Sean Reifschneider, + Jan Rekorajski, Erik Troan, Theodore Ts'o, Jeff Uphoff, Myles Uyema, + Savochkin Andrey Vladimirovich, Ronald Wahl, David Wood, John Wilmes, + Joseph S. D. Yao and Alex O. Yuriev. + + + Thanks are also due to Sun Microsystems, especially to Vipin Samar and + Charlie Lai for their advice. At an early stage in the development of + Linux-PAM, Sun graciously made the + documentation for their implementation of PAM available. This act + greatly accelerated the development of + Linux-PAM. + + + + + Copyright information for this document + +Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de> +Copyright (c) 1996-2002 Andrew G. Morgan <morgan@kernel.org> + + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + +1. Redistributions of source code must retain the above copyright + notice, and the entire permission notice in its entirety, + including the disclaimer of warranties. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. + + + Alternatively, this product may be distributed under the terms of + the GNU General Public License (GPL), in which case the provisions + of the GNU GPL are required instead of the above restrictions. + (This clause is necessary due to a potential bad interaction between + the GNU GPL and the restrictions contained in a BSD-style copyright.) + + +THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + + + -- cgit v1.2.3