diff options
Diffstat (limited to 'doc/pam_source.sgml')
| -rw-r--r-- | doc/pam_source.sgml | 1152 |
1 files changed, 0 insertions, 1152 deletions
diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml deleted file mode 100644 index bc091ed6..00000000 --- a/doc/pam_source.sgml +++ /dev/null @@ -1,1152 +0,0 @@ -<!doctype linuxdoc system> - -<!-- - - $Id$ - - Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved. - -Redistribution and use in source (sgml) and binary (derived) 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, 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 -DAMAGE. - - --> - -<article> - -<title>The Linux-PAM System Administrators' Guide -<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.77 2002/07/10 -<abstract> -This manual documents what a system-administrator needs to know about -the <bf>Linux-PAM</bf> library. It covers the correct syntax of the -PAM configuration file and discusses strategies for maintaining a -secure system. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Introduction - -<p><bf/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. - -<p>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. - -<p>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 <tt>/etc/passwd</tt> -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 (<tt/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 -<tt>/etc/group</tt> file. - -<p> -Unfortunately, increases in the speed of computers and the -widespread introduction of network based computing, have made once -secure authentication mechanisms, such as this, vulnerable to -attack. In the light of such realities, new methods of authentication -are continuously being developed. - -<p> -It is the purpose of the <bf/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, <tt>/etc/pam.conf</tt> (or a series of -configuration files located in <tt>/etc/pam.d/</tt>) to authenticate a -user request via the locally available authentication modules. The -modules themselves will usually be located in the directory -<tt>/lib/security</tt> and take the form of dynamically loadable -object files (see <tt/dlopen(3)/). - -<sect>Some comments on the text<label id="text-conventions"> - -<p> -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 <ref id="see-also-sec" name="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 diferent way you should -be careful when copying examples directly from the text. - -<p> -As an example of the above, where it is explicit, the text assumes -that PAM loadable object files (the <em/modules/) are to be located in -the following directory: <tt>/lib/security/</tt>. This is generally -the location that seems to be compatible with the Linux File System -Standard (the FSSTND). On Solaris, which has its own licensed version -of PAM, and some other implementations of UN*X, these files can be -found in <tt>/usr/lib/security</tt>. Please be careful to perform the -necessary transcription when using the examples from the text. - -<sect>Overview<label id="overview-section"> - -<p> -For the uninitiated, we begin by considering an example. We take an -application that grants some service to users; <em/login/ is one such -program. <em/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 <em/login/ the service is a -command shell (<em>bash, tcsh, zsh, etc.</em>) running with the -identity of the user. - -<p> -Traditionally, the former step is achieved by the <em/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 <bf/Linux-PAM/. - -<p> -From the perspective of the application programmer (in this case the -person that wrote the <em/login/ application), <bf/Linux-PAM/ takes -care of this authentication task -- verifying the identity of the user. - -<p> -The flexibility of <bf/Linux-PAM/ is that <em/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 <em/simple trust/ -(<tt/pam_permit/) to something as paranoid as a combination of a -retinal scan, a voice print and a one-time password! - -<p> -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 <em/multiplication tables/. As they mature, the authentication -can be upgraded to include (long) division! - -<p> -<bf/Linux-PAM/ deals with four separate types of (management) -task. These are: <em/authentication management/; <em/account -management/; <em/session management/; and <em/password management/. -The association of the preferred management scheme with the behavior -of an application is made with entries in the relevant <bf/Linux-PAM/ -configuration file. The management functions are performed by -<em/modules/ specified in the configuration file. The syntax for this -file is discussed in the section <ref id="configuration" -name="below">. - -<p> -Here is a figure that describes the overall organization of -<bf/Linux-PAM/. -<tscreen> -<verb> - +----------------+ - | 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 ] - +--------------+ -</verb> -</tscreen> -By way of explanation, the left of the figure represents the -application; application X. Such an application interfaces with the -<bf/Linux-PAM/ library and knows none of the specifics of its -configured authentication method. The <bf/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 <bf/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 -<em/conversation/ function. - -<sect1>Getting started - -<p> -The following text was contributed by Seth Chaiklin: -<tscreen> -<verb> -To this point, we have described how PAM should work in an -ideal world, in which all applications are coded properly. -However, at the present time (October 1998), this is far -from the case. Therefore, here are some practical considerations -in trying to use PAM in your system. - -Why bother, is it really worth all the trouble? - -If you running Linux as a single user system, or in an -environment where all the users are trusted, then there -is no real advantage for using PAM. -</verb> -</tscreen> - -<p> -<BF>Ed:</BF> there is actually an advantage since you can <em/dummy -down/ the authentication to the point where you don't have -any... Almost like Win95. -<p> -In a networked environment, it is clear that you need to think a -little more about how users etc., are authenticated:] - -<p> -<tscreen> -<verb> -If you are running Linux as a server, where several different -services are being provided (e.g., WWW with areas restricted by -password control, PPP), then there can be some real and interesting -value for PAM. In particular, through the use of modules, PAM can -enable a program to search through several different password -databases, even if that program is not explicitly coded for -that particular database. Here are some examples of the possibilities -that this enables. - - o Apache has a module that provides PAM services. Now - authentication - to use particular directories can be conducted by PAM, which - means that the range of modules that are available to PAM can - be used, including RADIUS, NIS, NCP (which means that Novell - password databases can be used). - - o pppd has a PAMified version (available from Red Hat) Now it is - possible to use a series of databases to authenticate ppp users. - In addition to the normal Linux-based password databases (such - as /etc/passwd and /etc/shadow), you can use PAM modules to - authenticate against Novell password databases or NT-based - password databases. - - o The preceding two examples can be combined. Imagaine that the - persons in your office/department are already registered with a - username and password in a Novell or NT LAN. If you wanted to - use this database on your Linux server (for PPP access, for - web access, or even for normal shell access), you can use PAM - to authenticate against this existing database, rather than - maintain a separate database on both Linux and the LAN server. - - -Can I use PAM for any program that requires authentication? - -Yes and no. Yes, if you have access to the source code, and can -add the appropriate PAM functions. No, if you do not have access -to the source code, and the binary does not have the PAM functions -included. - -In other words, if a program is going to use PAM, then it has to -have PAM functions explicitly coded into the program. If they -are not, then it is not possible to use PAM. - -How can I tell whether a program has PAM coded into it or not? - -A quick-and-dirty (but not always reliable) method is to ldd -<programname> -If libpam and libpam_misc are not among the libraries that the program -uses, then it is not going to work with PAM. However, it is possible -that the libraries are included, but there are still problems, because -the PAM coding in the program does not work as it should. So a -more reliable method is to make the follow tests. - -In the /etc/pam.d directory, one needs to make a configuration file -for the program that one wants to run. The exact name of the -configuration -file is hard-coded into the program. Usually, it is the same name as -the -program, but not always. For sake of illustration, let's assume that -the program is named "pamprog" and the name of the configuration file -is /etc/pam.d/pamprog. - -In the /etc/pam.d/pamprog but the following two lines: - -auth required pam_permit.so -auth required pam_warn.so - - -Now try to use pamprog. The first line in the configuration file -says that all users are permitted. The second line will write a -warning to your syslog file (or whether you syslog is writing - -messages). If this test succeeds, then you know that you have -a program that can understand pam, and you can start the more -interesting work of deciding how to stack modules in your -/etc/pam.d/pamprog file. -</verb> -</tscreen> - -<sect>The Linux-PAM configuration file -<label id="configuration"> - -<p> -<bf/Linux-PAM/ is designed to provide the system administrator with a -great deal of flexibility in configuring the privilege granting -applications of their system. The local configuration of those aspects -of system security controlled by <tt/Linux-PAM/ is contained in one of -two places: either the single system file, <tt>/etc/pam.conf</tt>; or -the <tt>/etc/pam.d/</tt> directory. In this section we discuss the -correct syntax of and generic options respected by entries to these -files. - -<sect1>Configuration file syntax - -<p> -The reader should note that the <bf/Linux-PAM/ specific tokens in this -file are case <em/insensitive/. The module paths, however, are case -sensitive since they indicate a file's <em/name/ and reflect the case -dependence of typical Linux file-systems. The case-sensitivity of the -arguments to any given module is defined for each module in turn. - -<p> -In addition to the lines described below, there are two <em/special/ -characters provided for the convenience of the system administrator: -comments are preceded by a `<tt/#/' and extend to the -next end-of-line; also, module specification lines may be extended -with a `<tt/\/' escaped newline. - -<p> -A general configuration line of the <tt>/etc/pam.conf</tt> file has -the following form: -<tscreen> -<verb> -service-name module-type control-flag module-path args -</verb> -</tscreen> -Below, we explain the meaning of each of these tokens. The second (and -more recently adopted) way of configuring <bf/Linux-PAM/ is via the -contents of the <tt>/etc/pam.d/</tt> directory. Once we have explained -the meaning of the above tokens, we will describe this method. - -<p> -<descrip> -<tag><tt/service-name/</tag> -The name of the service associated with this entry. Frequently the -service name is the conventional name of the given application. For -example, `<tt/ftpd/', `<tt/rlogind/' and `<tt/su/', <em/etc./ . - -<p> -There is a special <tt/service-name/, reserved for defining a default -authentication mechanism. It has the name `<tt/OTHER/' and may be -specified in either lower or upper case characters. Note, when there -is a module specified for a named service, the `<tt/OTHER/' entries -are ignored. - -<tag><tt/module-type/</tag> -One of (currently) four types of module. The four types are as -follows: -<itemize> -<item> <tt/auth/; this module type provides two aspects of -authenticating the user. Firstly, it establishes that the user is who -they claim to be, by instructing the application to prompt the user -for a password or other means of identification. Secondly, the module -can grant <tt/group/ membership (independently of the -<tt>/etc/groups</tt> file discussed above) or other privileges through -its <em/credential/ granting properties. - -<item> <tt/account/; this module performs non-authentication based -account management. It is typically used to restrict/permit access to -a service based on the time of day, currently available system -resources (maximum number of users) or perhaps the location of the -applicant user---`<tt/root/' login only on the console. - -<item> <tt/session/; primarily, this module is associated with doing -things that need to be done for the user before/after they can be -given service. Such things include the logging of information -concerning the opening/closing of some data exchange with a user, -mounting directories, etc. . - -<item> <tt/password/; this last module type is required for updating the -authentication token associated with the user. Typically, there is one -module for each `challenge/response' based authentication (<tt/auth/) -module-type. - -</itemize> - -<tag><tt/control-flag/</tag> - -The control-flag is used to indicate how the PAM library will react to -the success or failure of the module it is associated with. Since -modules can be <em/stacked/ (modules of the same type execute in -series, one after another), the control-flags determine the relative -importance of each module. The application is not made aware of the -individual success or failure of modules listed in the -`<tt>/etc/pam.conf</tt>' file. Instead, it receives a summary -<em/success/ or <em/fail/ response from the <bf/Linux-PAM/ library. -The order of execution of these modules is that of the entries in the -<tt>/etc/pam.conf</tt> file; earlier entries are executed before later -ones. As of Linux-PAM v0.60, this <em/control-flag/ can be defined -with one of two syntaxes. - -<p> -The simpler (and historical) syntax for the control-flag is a single -keyword defined to indicate the severity of concern associated with -the success or failure of a specific module. There are four such -keywords: <tt/required/, <tt/requisite/, <tt/sufficient/, -<tt/optional/ and <tt/include/. - -<p> -The Linux-PAM library interprets these keywords in the following -manner: - -<itemize> - -<item> <tt/required/; this indicates that the success of the module is -required for the <tt/module-type/ facility to succeed. Failure of this -module will not be apparent to the user until all of the remaining -modules (of the same <tt/module-type/) have been executed. - -<item> <tt/requisite/; like <tt/required/, however, in the case that -such a module returns a failure, control is directly returned to the -application. The return value is that associated with the <em/first/ -<tt/required/ or <tt/requisite/ module to fail. Note, this flag can be -used to protect against the possibility of a user getting the -opportunity to enter a password over an unsafe medium. It is -conceivable that such behavior might inform an attacker of valid -accounts on a system. This possibility should be weighed against the -not insignificant concerns of exposing a sensitive password in a -hostile environment. - -<item> <tt/sufficient/; the success of this module is deemed -`<em/sufficient/' to satisfy the <bf/Linux-PAM/ library that this -module-type has succeeded in its purpose. In the event that no -previous <tt/required/ module has failed, no more `<em/stacked/' -modules of this type are invoked. (Note, in this case subsequent -<tt/required/ modules are <bf/not/ invoked.). A failure of this module -is not deemed as fatal to satisfying the application that this -<tt/module-type/ has succeeded. - -<item> <tt/optional/; as its name suggests, this <tt/control-flag/ -marks the module as not being critical to the success or failure of -the user's application for service. In general, <bf/Linux-PAM/ -ignores such a module when determining if the module stack will -succeed or fail. However, in the absence of any definite successes or -failures of previous or subsequent stacked modules this module will -determine the nature of the response to the application. One example -of this latter case, is when the other modules return something like -<tt/PAM_IGNORE/. - -<item> <tt/include/; this tells PAM to include all lines of given type -from the configuration file specified as an argument to this control. -The whole idea is to create few "systemwide" pam configs and include -parts of them in application pam configs. - - -</itemize> - -<p> -The more elaborate (newer) syntax is much more specific and gives the -administrator a great deal of control over how the user is -authenticated. This form of the control flag is delimeted with square -brackets and consists of a series of <tt/value=action/ tokens: -<tscreen> -<verb> - [value1=action1 value2=action2 ...] -</verb> -</tscreen> - -<p> -Here, <tt/valueI/ is one of the following <em/return values/: -<tt/success/; <tt/open_err/; <tt/symbol_err/; <tt/service_err/; -<tt/system_err/; <tt/buf_err/; <tt/perm_denied/; <tt/auth_err/; -<tt/cred_insufficient/; <tt/authinfo_unavail/; <tt/user_unknown/; -<tt/maxtries/; <tt/new_authtok_reqd/; <tt/acct_expired/; -<tt/session_err/; <tt/cred_unavail/; <tt/cred_expired/; <tt/cred_err/; -<tt/no_module_data/; <tt/conv_err/; <tt/authtok_err/; -<tt/authtok_recover_err/; <tt/authtok_lock_busy/; -<tt/authtok_disable_aging/; <tt/try_again/; <tt/ignore/; <tt/abort/; -<tt/authtok_expired/; <tt/module_unknown/; <tt/bad_item/; and -<tt/default/. The last of these (<tt/default/) can be used to set the -action for those return values that are not explicitly defined. - -<p> -The <tt/actionI/ can be a positive integer or one of the following -tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and -<tt/reset/. A positive integer, <tt/J/, when specified as the action, -can be used to indicate that the next <em/J/ modules of the current -module-type will be skipped. In this way, the administrator can -develop a moderately sophisticated stack of modules with a number of -different paths of execution. Which path is taken can be determined -by the reactions of individual modules. - -<p> -<itemize> -<item><tt/ignore/ - when used with a stack of modules, the module's - return status will not contribute to the return code the application - obtains. -<item><tt/bad/ - this action indicates that the return code should be - thought of as indicative of the module failing. If this module is - the first in the stack to fail, its status value will be used for - that of the whole stack. -<item><tt/die/ - equivalent to <tt/bad/ with the side effect of - terminating the module stack and PAM immediately returning to the - application. -<item><tt/ok/ - this tells <bf/PAM/ that the administrator thinks this - return code should contribute directly to the return code of the full - stack of modules. In other words, if the former state of the stack - would lead to a return of <tt/PAM_SUCCESS/, the module's return code - will override this value. Note, if the former state of the stack - holds some value that is indicative of a modules failure, this 'ok' - value will not be used to override that value. -<item><tt/done/ - equivalent to <tt/ok/ with the side effect of - terminating the module stack and PAM immediately returning to the - application. -<item><tt/reset/ - clear all memory of the state of the module stack and - start again with the next stacked module. -</itemize> - -<p> -Each of the four keywords: <tt/required/; <tt/requisite/; -<tt/sufficient/; and <tt/optional/, have an equivalent expression in -terms of the <tt/[...]/ syntax. They are as follows: -<itemize> -<item><tt/required/ is equivalent to -<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=bad]/ -<item><tt/requisite/ is equivalent to -<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=die]/ -<item><tt/sufficient/ is equivalent to -<tt/[success=done new_authtok_reqd=done default=ignore]/ -<item><tt/optional/ is equivalent to -<tt/[success=ok new_authtok_reqd=ok default=ignore]/ -</itemize> - -<p> -Just to get a feel for the power of this new syntax, here is a taste -of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of -client plug-in agents was introduced. This is something that makes it -possible for PAM to support machine-machine authentication using the -transport protocol inherent to the client/server application. With -the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible -for an application to be configured to support binary prompts with -compliant clients, but to gracefully fall over into an alternative -authentication mode for older, legacy, applications. - -<tag> <tt/module-path/</tag> - -The path-name of the dynamically loadable object file; <em/the -pluggable module/ itself. If the first character of the module path is -`<tt>/</tt>', it is assumed to be a complete path. If this is not the -case, the given module path is appended to the default module path: -<tt>/lib/security</tt> (but see the notes <ref id="text-conventions" -name="above">). - -<tag> <tt/args/</tag> - -The <tt/args/ are a list of tokens that are passed to the module when -it is invoked. Much like arguments to a typical Linux shell command. -Generally, valid arguments are optional and are specific to any given -module. Invalid arguments are ignored by a module, however, when -encountering an invalid argument, the module is required to write an -error to <tt/syslog(3)/. For a list of <em/generic/ options see the -next section. - -Note, if you wish to include spaces in an argument, you should -surround that argument with square brackets. For example: -<tscreen> -<verb> -squid auth required pam_mysql.so user=passwd_query passwd=mada \ - db=eminence [query=select user_name from internet_service where \ - user_name='%u' and password=PASSWORD('%p') and \ - service='web_proxy'] -</verb> -</tscreen> -Note, when using this convention, you can include `<tt/[/' characters -inside the string, and if you wish to include a `<tt/]/' character -inside the string that will survive the argument parsing, you should -use `<tt/\[/'. In other words: -<tscreen> -<verb> -[..[..\]..] --> ..[..].. -</verb> -</tscreen> - -</descrip> - -<p> -Any line in (one of) the configuration file(s), that is not formatted -correctly, will generally tend (erring on the side of caution) to make -the authentication process fail. A corresponding error is written to -the system log files with a call to <tt/syslog(3)/. - -<sect1>Directory based configuration - -<p> -More flexible than the single configuration file, as of version 0.56, -it is possible to configure <tt>libpam</tt> via the contents of the -<tt>/etc/pam.d/</tt> directory. In this case the directory is filled -with files each of which has a filename equal to a service-name (in -lower-case): it is the personal configuration file for the named -service. - -<p> -<bf/Linux-PAM/ can be compiled in one of two modes. The preferred -mode uses either <tt>/etc/pam.d/</tt> or <tt>/etc/pam.conf</tt> -configuration but not both. That is to say, if there is a -<tt>/etc/pam.d/</tt> directory then libpam only uses the files -contained in this directory. However, in the absence of the -<tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is used -(this is likely to be the mode your preferred distribution uses). The -other mode is to use both <tt>/etc/pam.d/</tt> and -<tt>/etc/pam.conf</tt> in sequence. In this mode, entries in -<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>. - -The syntax of each file in <tt>/etc/pam.d/</tt> is similar to that of -the <tt>/etc/pam.conf</tt> file and is made up of lines of the -following form: -<tscreen> -<verb> -module-type control-flag module-path arguments -</verb> -</tscreen> -The only difference being that the <tt>service-name</tt> is not -present. The service-name is of course the name of the given -configuration file. For example, <tt>/etc/pam.d/login</tt> contains -the configuration for the <em>login</em> service. - -<p> -This method of configuration has a number of advantages over the -single file approach. We list them here to assist the reader in -deciding which scheme to adopt: - -<p> -<itemize> - -<item>A lower chance of misconfiguring an application. There is one -less field to mis-type when editing the configuration files by hand. - -<item>Easier to maintain. One application may be reconfigured without -risk of interfering with other applications on the system. - -<item>It is possible to symbolically link different services -configuration files to a single file. This makes it easier to keep the -system policy for access consistent across different applications. -(It should be noted, to conserve space, it is equally possible to -<em>hard</em> link a number of configuration files. However, care -should be taken when administering this arrangement as editing a hard -linked file is likely to break the link.) - -<item>A potential for quicker configuration file parsing. Only the -relevant entries are parsed when a service gets bound to its modules. - -<item>It is possible to limit read access to individual <bf/Linux-PAM/ -configuration files using the file protections of the filesystem. - -<item>Package management becomes simpler. Every time a new -application is installed, it can be accompanied by an -<tt>/etc/pam.d/</tt><em>xxxxxx</em> file. - -</itemize> - -<sect1>Generic optional arguments - -<p> -The following are optional arguments which are likely to be understood -by any module. Arguments (including these) are in general -<em/optional/. - -<p> -<descrip> -<tag><tt/debug/</tag> - -Use the <tt/syslog(3)/ call to log debugging information to the system -log files. - -<tag> <tt/no_warn/</tag> - -Instruct module to not give warning messages to the application. - -<tag> <tt/use_first_pass/</tag> - -The module should not prompt the user for a password. Instead, it -should obtain the previously typed password (from the preceding -<tt/auth/ module), and use that. If that doesn't work, then the user -will not be authenticated. (This option is intended for <tt/auth/ -and <tt/password/ modules only). - -<tag> <tt/try_first_pass/</tag> - -The module should attempt authentication with the previously typed -password (from the preceding <tt/auth/ module). If that doesn't work, -then the user is prompted for a password. (This option is intended for -<tt/auth/ modules only). - -<tag> <tt/use_mapped_pass/</tag> - -This argument is not currently supported by any of the modules in the -<bf/Linux-PAM/ distribution because of possible consequences -associated with U.S. encryption exporting restrictions. Within the -U.S., module developers are, of course, free to implement it (as are -developers in other countries). For compatibility reasons we describe -its use as suggested in the <bf/DCE-RFC 86.0/, see section <ref -id="see-also-sec" name="bibliography"> for a pointer to this document. - -<p> -The <tt/use_mapped_pass/ argument instructs the module to take the -clear text authentication token entered by a previous module (that -requests such a token) and use it to generate an encryption/decryption -key with which to safely store/retrieve the authentication token -required for this module. In this way the user can enter a single -authentication token and be quietly authenticated by a number of -stacked modules. Obviously a convenient feature that necessarily -requires some reliably strong encryption to make it secure. -This argument is intended for the <tt/auth/ and <tt/password/ module -types only. - -<tag><tt/expose_account/</tag> - -<p> -In general the leakage of some information about user accounts is not -a secure policy for modules to adopt. Sometimes information such as -users names or home directories, or preferred shell, can be used to -attack a user's account. In some circumstances, however, this sort of -information is not deemed a threat: displaying a user's full name when -asking them for a password in a secured environment could also be -called being 'friendly'. The <tt/expose_account/ argument is a -standard module argument to encourage a module to be less discrete -about account information as it is deemed appropriate by the local -administrator. - -</descrip> - -<sect1>Example configuration file entries - -<p> -In this section, we give some examples of entries that can be present -in the <bf/Linux-PAM/ configuration file. As a first attempt at -configuring your system you could do worse than to implement these. - -<sect2>Default policy - -<p> -If a system is to be considered secure, it had better have a -reasonably secure `<tt/OTHER/' entry. The following is a paranoid -setting (which is not a bad place to start!): -<tscreen> -<verb> -# -# 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 -</verb> -</tscreen> -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. - -<p> -The module <tt/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. - -<p> -The addition of the following line before those in the above example -would provide a suitable warning to the administrator. -<tscreen> -<verb> -# -# default; wake up! This application is not configured -# -OTHER auth required pam_warn.so -OTHER password required pam_warn.so -</verb> -</tscreen> -Having two ``<tt/OTHER auth/'' lines is an example of stacking. - -<p> -On a system that uses the <tt>/etc/pam.d/</tt> configuration, the -corresponding default setup would be achieved with the following file: -<tscreen> -<verb> -# -# 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 -</verb> -</tscreen> -This is the only explicit example we give for an <tt>/etc/pam.d/</tt> -file. In general, it should be clear how to transpose the remaining -examples to this configuration scheme. - -<p> -On a less sensitive computer, one on which the system administrator -wishes to remain ignorant of much of the power of <tt/Linux-PAM/, the -following selection of lines (in <tt>/etc/pam.conf</tt>) is likely to -mimic the historically familiar Linux setup. -<tscreen> -<verb> -# -# default; standard UN*X access -# -OTHER auth required pam_unix.so -OTHER account required pam_unix.so -OTHER password required pam_unix.so -OTHER session required pam_unix.so -</verb> -</tscreen> -In general this will provide a starting place for most applications. -Unfortunately, most is not all. One application that might require -additional lines is <em/ftpd/ if you wish to enable -<em/anonymous-ftp/. - -<p> -To enable anonymous-ftp, the following lines might be used to replace -the default (<tt/OTHER/) ones. (<bf/*WARNING*/ as of 1996/12/28 this -does not work correctly with any ftpd. Consequently, this description -may be subject to change or the application will be fixed.) -<tscreen> -<verb> -# -# ftpd; add ftp-specifics. These lines enable anonymous ftp over -# standard UN*X access (the listfile entry blocks access to -# users listed in /etc/ftpusers) -# -ftpd auth sufficient pam_ftp.so -ftpd auth required pam_unix_auth.so use_first_pass -ftpd auth required pam_listfile.so \ - onerr=succeed item=user sense=deny file=/etc/ftpusers -</verb> -</tscreen> -Note, the second line is necessary since the default entries are -ignored by a service application (here <em/ftpd/) if there are -<em/any/ entries in <tt>/etc/pam.conf</tt> for that specified service. -Again, this is an example of authentication module stacking. Note the -use of the <tt/sufficient/ control-flag. It says that ``if this module -authenticates the user, ignore the subsequent <tt/auth/ -modules''. Also note the use of the ``<tt/use_first_pass/'' -module-argument, this instructs the UN*X authentication module that it -is not to prompt for a password but rely on one already having been -obtained by the <tt/pam_ftp/ module. - -<sect>Security issues of Linux-PAM - -<p> -This section will discuss good practices for using PAM in a secure -manner. <em>It is currently sadly lacking...suggestions are -welcome!</em> - -<sect1>If something goes wrong - -<p> -<bf/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, <bf/Linux-PAM/ errs towards the -latter. Any number of configuration errors can dissable access to -your system partially, or completely. - -<p> -The most dramatic problem that is likely to be encountered when -configuring <bf/Linux-PAM/ is that of <em>deleting</em> the -configuration file(s): <tt>/etc/pam.d/*</tt> and/or -<tt>/etc/pam.conf</tt>. This will lock you out of your own system! - -<p> -To recover, your best bet is to reboot the system in single user mode -and set about correcting things from there. The following has been -<em>adapted</em> from a life-saving email on the subject from David -Wood: -<verb> -> What the hell do I do now? - -OK, don't panic. The first thing you have to realize is that -this happens to 50% of users who ever do anything with PAM. -It happened here, not once, not twice, but three times, all -different, and in the end, the solution was the same every -time. - -First, I hope you installed LILO with a delay. If you can, -reboot, hit shift or tab or something and type: - - LILO boot: linux single - -(Replace 'linux' with 'name-of-your-normal-linux-image'). -This will let you in without logging in. Ever wondered how -easy it is to break into a linux machine from the console? -Now you know. - -If you can't do that, then get yourself a bootkernel floppy -and a root disk a-la slackware's rescue.gz. (Red Hat's -installation disks can be used in this mode too.) - -In either case, the point is to get back your root prompt. - -Second, I'm going to assume that you haven't completely -nuked your pam installation - just your configuration files. -Here's how you make your configs nice again: - - cd /etc - mv pam.conf pam.conf.orig - mv pam.d pam.d.orig - mkdir pam.d - cd pam.d - -and then use vi to create a file called "other" in this -directory. It should contain the following four lines: - - auth required pam_unix.so - account required pam_unix.so - password required pam_unix.so - session required pam_unix.so - -Now you have the simplest possible PAM configuration that -will work the way you're used to. Everything should -magically start to work again. Try it out by hitting ALT-F2 -and logging in on another virtual console. If it doesn't -work, you have bigger problems, or you've mistyped -something. One of the wonders of this system (seriously, -perhaps) is that if you mistype anything in the conf files, -you usually get no error reporting of any kind on the -console - just some entries in the log file. So look there! -(Try 'tail /var/log/messages'.) - -From here you can go back and get a real configuration -going, hopefully after you've tested it first on a machine -you don't care about screwing up. :/ - -</verb> - -<sect1>Avoid having a weak `other' configuration - -<p> -It is not a good thing to have a weak default (<tt/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. - -<p> -Here is a sample "other" configuration file. The <em/pam_deny/ module will -deny access and the <em/pam_warn/ module will send a syslog message to -<tt/auth.notice/: - -<p> -<tscreen> -<verb> -# -# 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 -</verb> -</tscreen> - -<sect>A reference guide for available modules - -<p> -Here, we collect together some descriptions of the various modules -available for <bf/Linux-PAM/. In general these modules should be -freely available. Where this is not the case, it will be indicated. - -<p> -Also please note the comments contained in the section <ref -id="text-conventions" name="on text conventions above"> when copying -the examples listed below. - -<!-- insert-file MODULES-SGML --> - -<sect>Files - -<p><descrip> - -<tag><tt>/lib/libpam.so.*</tt></tag> - -the shared library providing applications with access to -<bf/Linux-PAM/. - -<tag><tt>/etc/pam.conf</tt></tag> - -the <bf/Linux-PAM/ configuration file. - -<tag><tt>/lib/security/pam_*.so</tt></tag> - -the primary location for <bf/Linux-PAM/ dynamically loadable object -files; the modules. - -</descrip> - -<sect>See also<label id="see-also-sec"> - -<p><itemize> - -<item>The <bf/Linux-PAM/ Application Writers' Guide. - -<item>The <bf/Linux-PAM/ Module Writers' Guide. - -<item>The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH -PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation Request -For Comments 86.0, October 1995. See this url: -<tt><htmlurl -url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz" -name="http://www.kernel.org/pub/linux/libs/pam/pre/doc/rfc86.0.txt.gz"></tt> - -</itemize> - -<sect>Notes - -<p> -I intend to put development comments here... like ``at the moment -this isn't actually supported''. At release time what ever is in -this section will be placed in the Bugs section below! :) - -<p> -Are we going to be able to support the <tt/use_mapped_pass/ module -argument? Anyone know a cheap (free) good lawyer?! - -<p> -<itemize> -<item> -This issue may go away, as Sun have investigated adding a new -management group for mappings. In this way, libpam would have mapping -modules that could securely store passwords using strong cryptography -and in such a way that they need not be distributed with Linux-PAM. -</itemize> - -<sect>Author/acknowledgments - -<p> -This document was written by Andrew G. Morgan (morgan@kernel.org) -with many contributions from -<!-- insert-file CREDITS --> - -<p> -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 -<bf/Linux-PAM/, Sun graciously made the documentation for their -implementation of PAM available. This act greatly accelerated the -development of <bf/Linux-PAM/. - -<sect>Bugs/omissions - -<p> -More PAM modules are being developed all the time. It is unlikely that -this document will ever be truely up to date! - -<p> -This manual is unfinished. Only a partial list of people is credited -for all the good work they have done. - -<sect>Copyright information for this document - -<p> -Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved. -<newline> -Email: <tt><morgan@kernel.org></tt> - -<p> -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -<p> -<itemize> - -<item> -1. Redistributions of source code must retain the above copyright - notice, and the entire permission notice in its entirety, - including the disclaimer of warranties. - -<item> -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. - -<item> -3. The name of the author may not be used to endorse or promote - products derived from this software without specific prior - written permission. - -</itemize> - -<p> -<bf/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 <bf/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.) - -<p> -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 -DAMAGE. - -<p> -<tt>$Id$</tt> - -</article> |