diff options
Diffstat (limited to 'doc/mwg/Linux-PAM_MWG.xml')
| -rw-r--r-- | doc/mwg/Linux-PAM_MWG.xml | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/doc/mwg/Linux-PAM_MWG.xml b/doc/mwg/Linux-PAM_MWG.xml new file mode 100644 index 00000000..fc4831a2 --- /dev/null +++ b/doc/mwg/Linux-PAM_MWG.xml @@ -0,0 +1,397 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<book> + <bookinfo> + <title>The Linux-PAM Module Writers' Guide</title> + <authorgroup> + <author> + <firstname>Andrew G.</firstname> + <surname>Morgan</surname> + <email>morgan@kernel.org</email> + </author> + <author> + <firstname>Thorsten</firstname> + <surname>Kukuk</surname> + <email>kukuk@thkukuk.de</email> + </author> + </authorgroup> + <releaseinfo>Version 0.99, 26. June 2006</releaseinfo> + <abstract> + <para> + This manual documents what a programmer needs to know in order + to write a module that conforms to the + <emphasis remap='B'>Linux-PAM</emphasis> standard.It also + discusses some security issues from the point of view of the + module programmer. + </para> + </abstract> + </bookinfo> + + <chapter id="mwg-introduction"> + <title>Introduction</title> + <section id="mwg-introduction-description"> + <title>Description</title> + <para> + <emphasis remap='B'>Linux-PAM</emphasis> (Pluggable Authentication + Modules for Linux) is a library that enables the local system + administrator to choose how individual applications authenticate + users. For an overview of the + <emphasis remap='B'>Linux-PAM</emphasis> library see the + <emphasis>Linux-PAM System Administrators' Guide</emphasis>. + </para> + <para> + A <emphasis remap='B'>Linux-PAM</emphasis> module is a single + executable binary file that can be loaded by the + <emphasis remap='B'>Linux-PAM</emphasis> interface library. + This PAM library is configured locally with a system file, + <filename>/etc/pam.conf</filename>, to authenticate a user + request via the locally available authentication modules. The + modules themselves will usually be located in the directory + <filename>/lib/security</filename> (or + <filename>/lib64/security</filename>, depending on the architecture) + and take the form of dynamically loadable object files (see + <citerefentry> + <refentrytitle>dlopen</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. Alternatively, the modules can be statically + linked into the <emphasis remap='B'>Linux-PAM</emphasis> library; + this is mostly to allow <emphasis remap='B'>Linux-PAM</emphasis> to + be used on platforms without dynamic linking available, but this is + a <emphasis>deprecated</emphasis> functionality. It is the + <emphasis remap='B'>Linux-PAM</emphasis> interface that is called + by an application and it is the responsibility of the library to + locate, load and call the appropriate functions in a + <emphasis remap='B'>Linux-PAM</emphasis>-module. + </para> + <para> + Except for the immediate purpose of interacting with the user + (entering a password etc..) the module should never call the + application directly. This exception requires a "conversation + mechanism" which is documented below. + </para> + </section> + + <section id="mwg-introducton-synopsis"> + <title>Synopsis</title> + <programlisting> +#include <security/pam_modules.h> + +gcc -fPIC -c pam_module.c +gcc -shared -o pam_module.so pam_module.o -lpam + </programlisting> + </section> + </chapter> + + <chapter id="mwg-expected-by-module"> + <title>What can be expected by the module</title> + <para> + Here we list the interface that the conventions that all + <emphasis remap='B'>Linux-PAM</emphasis> modules must adhere to. + </para> + <section id="mwg-expected-by-module-item"> + <title> + Getting and setting <emphasis>PAM_ITEM</emphasis>s and + <emphasis>data</emphasis> + </title> + <para> + First, we cover what the module should expect from the + <emphasis remap='B'>Linux-PAM</emphasis> library and a + <emphasis remap='B'>Linux-PAM</emphasis> aware application. + Essesntially this is the <filename>libpam.*</filename> library. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_set_data.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_get_data.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_set_item.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_get_item.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_get_user.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_conv.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_putenv.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_getenv.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_getenvlist.xml"/> + </section> + <section id="mwg-expected-by-module-other"> + <title> + Other functions provided by <filename>libpam</filename> + </title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_strerror.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_fail_delay.xml"/> + </section> + </chapter> + + <chapter id="mwg-expected-of-module"> + <title>What is expected of a module</title> + <para> + The module must supply a sub-set of the six functions listed + below. Together they define the function of a + <emphasis remap='B'>Linux-PAM module</emphasis>. Module developers + are strongly urged to read the comments on security that follow + this list. + </para> + <section id="mwg-expected-of-module-overview"> + <title>Overview</title> + <para> + The six module functions are grouped into four independent + management groups. These groups are as follows: + <emphasis>authentication</emphasis>, <emphasis>account</emphasis>, + <emphasis>session</emphasis> and <emphasis>password</emphasis>. + To be properly defined, a module must define all functions within + at least one of these groups. A single module may contain the + necessary functions for <emphasis>all</emphasis> four groups. + </para> + <section id="mwg-expected-of-module-overview-1"> + <title>Functional independence</title> + <para> + The independence of the four groups of service a module can + offer means that the module should allow for the possibility + that any one of these four services may legitimately be called + in any order. Thus, the module writer should consider the + appropriateness of performing a service without the prior + success of some other part of the module. + </para> + <para> + As an informative example, consider the possibility that an + application applies to change a user's authentication token, + without having first requested that + <emphasis remap='B'>Linux-PAM</emphasis> authenticate the + user. In some cases this may be deemed appropriate: when + <command>root</command> wants to change the authentication + token of some lesser user. In other cases it may not be + appropriate: when <command>joe</command> maliciously wants + to reset <command>alice</command>'s password; or when anyone + other than the user themself wishes to reset their + <emphasis>KERBEROS</emphasis> authentication token. A policy + for this action should be defined by any reasonable + authentication scheme, the module writer should consider + this when implementing a given module. + </para> + </section> + <section id="mwg-expected-of-module-overview-2"> + <title>Minimizing administration problems</title> + <para> + To avoid system administration problems and the poor + construction of a <filename>/etc/pam.conf</filename> file, + the module developer may define all six of the following + functions. For those functions that would not be called, + the module should return <errorname>PAM_SERVICE_ERR</errorname> + and write an appropriate message to the system log. When + this action is deemed inappropriate, the function would + simply return <errorname>PAM_IGNORE</errorname>. + </para> + </section> + <section id="mwg-expected-of-module-overview-3"> + <title>Arguments supplied to the module</title> + <para> + The <parameter>flags</parameter> argument of each of + the following functions can be logically OR'd with + <parameter>PAM_SILENT</parameter>, which is used to inform the + module to not pass any <emphasis>text</emphasis> (errors or + warnings) application. + </para> + <para> + The <parameter>argc</parameter> and <parameter>argv</parameter> + arguments are taken from the line appropriate to this + module---that is, with the <emphasis>service_name</emphasis> + matching that of the application---in the configuration file + (see the <emphasis remap='B'>Linux-PAM</emphasis> + System Administrators' Guide). Together these two parameters + provide the number of arguments and an array of pointers to + the individual argument tokens. This will be familiar to C + programmers as the ubiquitous method of passing command arguments + to the function <function>main()</function>. Note, however, that + the first argument (<parameter>argv[0]</parameter>) is a true + argument and <emphasis>not</emphasis> the name of the module. + </para> + </section> + </section> + <section id="mwg-expected-of-module-auth"> + <title>Authentication management</title> + <para> + To be correctly initialized, <parameter>PAM_SM_AUTH</parameter> + must be <command>#define</command>'d prior to including + <function><security/pam_modules.h></function>. This will + ensure that the prototypes for static modules are properly declared. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_sm_authenticate.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_sm_setcred.xml"/> + </section> + <section id="mwg-expected-of-module-acct"> + <title>Account management</title> + <para> + To be correctly initialized, <parameter>PAM_SM_ACCOUNT</parameter> + must be <command>#define</command>'d prior to including + <function><security/pam_modules.h></function>. This will + ensure that the prototypes for static modules are properly declared. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_sm_acct_mgmt.xml"/> + </section> + <section id="mwg-expected-of-module-session"> + <title>Session management</title> + <para> + To be correctly initialized, <parameter>PAM_SM_SESSION</parameter> + must be <command>#define</command>'d prior to including + <function><security/pam_modules.h></function>. This will + ensure that the prototypes for static modules are properly declared. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_sm_open_session.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_sm_close_session.xml"/> + </section> + <section id="mwg-expected-of-module-chauthtok"> + <title>Authentication token management</title> + <para> + To be correctly initialized, <parameter>PAM_SM_PASSWORD</parameter> + must be <command>#define</command>'d prior to including + <function><security/pam_modules.h></function>. This will + ensure that the prototypes for static modules are properly declared. + </para> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_sm_chauthtok.xml"/> + </section> + </chapter> + + <chapter id="mwg-see-options"> + <title>Generic optional arguments</title> + <para> + Here we list the generic arguments that all modules can expect to + be passed. They are not mandatory, and their absence should be + accepted without comment by the module. + </para> + <variablelist> + <varlistentry> + <term>debug</term> + <listitem> + <para> + Use the <citerefentry> + <refentrytitle>pam_syslog</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> call to log debugging information to the system + log files. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>use_first_pass</term> + <listitem> + <para> + The module should not prompt the user for a password. + Instead, it should obtain the previously typed password + (by a call to <function>pam_get_item()</function> for the + <parameter>PAM_AUTHTOK</parameter> item), and use that. If + that doesn't work, then the user will not be authenticated. + (This option is intended for <command>auth</command> and + <command>passwd</command> modules only). + </para> + </listitem> + </varlistentry> + </variablelist> + </chapter> + + <chapter id="mwg-see-also"> + <title>See also</title> + <itemizedlist> + <listitem> + <para> + The Linux-PAM System Administrators' Guide. + </para> + </listitem> + <listitem> + <para> + The Linux-PAM Application Developers' Guide. + </para> + </listitem> + <listitem> + <para> + The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH + PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation + Request For Comments 86.0, October 1995. + </para> + </listitem> + </itemizedlist> + </chapter> + + <chapter id='mwg-author'> + <title>Author/acknowledgments</title> + <para> + 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, 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. + </para> + <para> + 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 + <emphasis remap='B'>Linux-PAM</emphasis>, Sun graciously made the + documentation for their implementation of PAM available. This act + greatly accelerated the development of + <emphasis remap='B'>Linux-PAM</emphasis>. + </para> + </chapter> + + <chapter id='mwg-copyright'> + <title>Copyright information for this document</title> + <programlisting> +Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de> +Copyright (c) 1996-2002 Andrew G. Morgan <morgan@kernel.org> + </programlisting> + <para> + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + </para> + <programlisting> +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. + </programlisting> + <para> + 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.) + </para> + <programlisting> +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 + </programlisting> + </chapter> +</book> |