summaryrefslogtreecommitdiff
path: root/doc/man/pam.conf-syntax.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/pam.conf-syntax.xml')
-rw-r--r--doc/man/pam.conf-syntax.xml372
1 files changed, 372 insertions, 0 deletions
diff --git a/doc/man/pam.conf-syntax.xml b/doc/man/pam.conf-syntax.xml
new file mode 100644
index 00000000..b422cba9
--- /dev/null
+++ b/doc/man/pam.conf-syntax.xml
@@ -0,0 +1,372 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<section id='pam.conf-syntax'>
+ <para>
+ The syntax of the <filename>/etc/pam.conf</filename>
+ configuration file is as follows. The file is made up of a list
+ of rules, each rule is typically placed on a single line,
+ but may be extended with an escaped end of line: `\&lt;LF&gt;'.
+ Comments are preceded with `#' marks and extend to the next end of
+ line.
+ </para>
+
+ <para>
+ The format of each rule is a space separated collection of tokens,
+ the first three being case-insensitive:
+ </para>
+
+ <para>
+ <emphasis remap='B'> service type control module-path module-arguments</emphasis>
+ </para>
+
+ <para>
+ The syntax of files contained in the <filename>/etc/pam.d/</filename>
+ directory, are identical except for the absence of any
+ <emphasis>service</emphasis> field. In this case, the
+ <emphasis>service</emphasis> is the name of the file in the
+ <filename>/etc/pam.d/</filename> directory. This filename must be
+ in lower case.
+ </para>
+
+ <para>
+ An important feature of <emphasis>PAM</emphasis>, is that a
+ number of rules may be <emphasis>stacked</emphasis> to combine
+ the services of a number of PAMs for a given authentication task.
+ </para>
+
+ <para>
+ The <emphasis>service</emphasis> is typically the familiar name of
+ the corresponding application: <emphasis>login</emphasis> and
+ <emphasis>su</emphasis> are good examples. The
+ <emphasis>service</emphasis>-name, <emphasis>other</emphasis>,
+ is reserved for giving <emphasis>default</emphasis> rules.
+ Only lines that mention the current service (or in the absence
+ of such, the <emphasis>other</emphasis> entries) will be associated
+ with the given service-application.
+ </para>
+
+ <para>
+ The <emphasis>type</emphasis> is the management group that the rule
+ corresponds to. It is used to specify which of the management groups
+ the subsequent module is to be associated with. Valid entries are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>account</term>
+ <listitem>
+ <para>
+ this module type 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 -- 'root' login only on the
+ console.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>auth</term>
+ <listitem>
+ <para>
+ 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 group membership or other privileges through
+ its credential granting properties.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>password</term>
+ <listitem>
+ <para>
+ this module type is required for updating the authentication
+ token associated with the user. Typically, there is one module
+ for each 'challenge/response' based authentication (auth) type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>session</term>
+ <listitem>
+ <para>
+ this module type 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The third field, <emphasis>control</emphasis>, indicates the
+ behavior of the PAM-API should the module fail to succeed in its
+ authentication task. There are two types of syntax for this control
+ field: the simple one has a single simple keyword; the more
+ complicated one involves a square-bracketed selection of
+ <emphasis>value=action</emphasis> pairs.
+ </para>
+
+ <para>
+ For the simple (historical) syntax valid <emphasis>control</emphasis>
+ values are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>required</term>
+ <listitem>
+ <para>
+ failure of such a PAM will ultimately lead to the PAM-API
+ returning failure but only after the remaining
+ <emphasis>stacked</emphasis> modules (for this
+ <emphasis>service</emphasis> and <emphasis>type</emphasis>)
+ have been invoked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>requisite</term>
+ <listitem>
+ <para>
+ like <emphasis>required</emphasis>, 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 first required or 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>sufficient</term>
+ <listitem>
+ <para>
+ success of such a module is enough to satisfy the
+ authentication requirements of the stack of modules (if a
+ prior <emphasis>required</emphasis> module has failed the
+ success of this one is <emphasis>ignored</emphasis>). A failure
+ of this module is not deemed as fatal to satisfying the
+ application that this type has succeeded.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>optional</term>
+ <listitem>
+ <para>
+ the success or failure of this module is only important if
+ it is the only module in the stack associated with this
+ <emphasis>service</emphasis>+<emphasis>type</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>include</term>
+ <listitem>
+ <para>
+ include all lines of given type from the configuration
+ file specified as an argument to this control.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ For the more complicated syntax valid <emphasis>control</emphasis>
+ values have the following form:
+ </para>
+ <programlisting>
+ [value1=action1 value2=action2 ...]
+ </programlisting>
+
+ <para>
+ Where <emphasis>valueN</emphasis> corresponds to the return code
+ from the function invoked in the module for which the line is
+ defined. It is selected from one of these:
+ <emphasis>success</emphasis>, <emphasis>open_err</emphasis>,
+ <emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>,
+ <emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>,
+ <emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>,
+ <emphasis>cred_insufficient</emphasis>,
+ <emphasis>authinfo_unavail</emphasis>,
+ <emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>,
+ <emphasis>new_authtok_reqd</emphasis>,
+ <emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>,
+ <emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>,
+ <emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>,
+ <emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>,
+ <emphasis>authtok_recover_err</emphasis>,
+ <emphasis>authtok_lock_busy</emphasis>,
+ <emphasis>authtok_disable_aging</emphasis>,
+ <emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>,
+ <emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>,
+ <emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis>
+ and <emphasis>default</emphasis>.
+ </para>
+ <para>
+ The last of these, <emphasis>default</emphasis>, implies 'all
+ <emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the
+ full list of PAM errors is available in
+ <filename>/usr/include/security/_pam_types.h</filename>. The
+ <emphasis>actionN</emphasis> can be: an unsigned integer,
+ <emphasis>n</emphasis>, signifying an action of 'jump over the
+ next <emphasis>n</emphasis> modules in the stack', or take one
+ of the following forms:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>ignore</term>
+ <listitem>
+ <para>
+ when used with a stack of modules, the module's return
+ status will not contribute to the return code the application
+ obtains.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>bad</term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>die</term>
+ <listitem>
+ <para>
+ equivalent to bad with the side effect of terminating the
+ module stack and PAM immediately returning to the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ok</term>
+ <listitem>
+ <para>
+ this tells 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 <emphasis>PAM_SUCCESS</emphasis>,
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>done</term>
+ <listitem>
+ <para>
+ equivalent to ok with the side effect of terminating the module
+ stack and PAM immediately returning to the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>reset</term>
+ <listitem>
+ <para>
+ clear all memory of the state of the module stack and
+ start again with the next stacked module.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Each of the four keywords: required; requisite; sufficient; and
+ optional, have an equivalent expression in terms of the [...]
+ syntax. They are as follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>required</term>
+ <listitem>
+ <para>
+ [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>requisite</term>
+ <listitem>
+ <para>
+ [success=ok new_authtok_reqd=ok ignore=ignore default=die]
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>sufficient</term>
+ <listitem>
+ <para>
+ [success=done new_authtok_reqd=done default=ignore]
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>optional</term>
+ <listitem>
+ <para>
+ [success=ok new_authtok_reqd=ok default=ignore]
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <emphasis>module-path</emphasis> is either the full filename
+ of the PAM to be used by the application (it begins with a '/'),
+ or a relative pathname from the default module location:
+ <filename>/lib/security/</filename> or
+ <filename>/lib64/security/</filename>, depending on the architecture.
+ </para>
+
+ <para>
+ <emphasis>module-arguments</emphasis> are a space separated list
+ of tokens that can be used to modify the specific behavior of the
+ given PAM. Such arguments will be documented for each individual
+ module. Note, if you wish to include spaces in an argument, you
+ should surround that argument with square brackets.
+ </para>
+ <programlisting>
+ 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']
+ </programlisting>
+ <para>
+ When using this convention, you can include `[' characters
+ inside the string, and if you wish to include a `]' character
+ inside the string that will survive the argument parsing, you
+ should use `\['. In other words:
+ </para>
+ <programlisting>
+ [..[..\]..] --> ..[..]..
+ </programlisting>
+
+ <para>
+ 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
+ <citerefentry>
+ <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+
+</section>