granicus.if.org Git - linux-pam/blob - doc/man/pam.conf-syntax.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <section id='pam.conf-syntax'>
   6   <para>
   7     The syntax of the <filename>/etc/pam.conf</filename>
   8     configuration file is as follows. The file is made up of a list
   9     of rules, each rule is typically placed on a single line,
  10     but may be extended with an escaped end of line: `\&lt;LF&gt;'.
  11     Comments are preceded with `#' marks and extend to the next end of
  12     line.
  13   </para>
  14
  15     <para>
  16       The format of each rule is a space separated collection of tokens,
  17       the first three being case-insensitive:
  18     </para>
  19
  20     <para>
  21       <emphasis remap='B'> service  type  control  module-path  module-arguments</emphasis>
  22     </para>
  23
  24     <para>
  25       The syntax of files contained in the <filename>/etc/pam.d/</filename>
  26       directory, are identical except for the absence of any
  27       <emphasis>service</emphasis> field. In this case, the
  28       <emphasis>service</emphasis> is the name of the file in the
  29       <filename>/etc/pam.d/</filename> directory. This filename must be
  30       in lower case.
  31     </para>
  32
  33     <para>
  34       An important feature of <emphasis>PAM</emphasis>, is that a
  35       number of rules may be <emphasis>stacked</emphasis> to combine
  36       the services of a number of PAMs for a given authentication task.
  37     </para>
  38
  39     <para>
  40       The <emphasis>service</emphasis> is typically the familiar name of
  41       the corresponding application: <emphasis>login</emphasis> and
  42       <emphasis>su</emphasis> are good examples. The
  43       <emphasis>service</emphasis>-name, <emphasis>other</emphasis>,
  44       is reserved for giving <emphasis>default</emphasis> rules.
  45       Only lines that mention the current service (or in the absence
  46       of such, the <emphasis>other</emphasis> entries) will be associated
  47       with the given service-application.
  48     </para>
  49
  50     <para>
  51       The <emphasis>type</emphasis> is the management group that the rule
  52       corresponds to. It is used to specify which of the management groups
  53       the subsequent module is to be associated with. Valid entries are:
  54     </para>
  55     <variablelist>
  56       <varlistentry>
  57         <term>account</term>
  58         <listitem>
  59           <para>
  60             this module type performs non-authentication based account
  61             management. It is typically used to restrict/permit access
  62             to a service based on the time of day, currently available
  63             system resources (maximum number of users) or perhaps the
  64             location of  the applicant user -- 'root' login only on the
  65             console.
  66           </para>
  67         </listitem>
  68       </varlistentry>
  69       <varlistentry>
  70         <term>auth</term>
  71         <listitem>
  72           <para>
  73             this module type provides two aspects of authenticating
  74             the user. Firstly, it establishes that the user is who they
  75             claim to be, by instructing the application to prompt the user
  76             for a password or other means of identification. Secondly, the
  77             module can grant group membership or other privileges through
  78             its credential granting properties.
  79           </para>
  80         </listitem>
  81       </varlistentry>
  82       <varlistentry>
  83         <term>password</term>
  84         <listitem>
  85           <para>
  86             this module type is required for updating the authentication
  87             token associated with the user. Typically, there is one module
  88             for each 'challenge/response' based authentication (auth) type.
  89           </para>
  90         </listitem>
  91       </varlistentry>
  92       <varlistentry>
  93         <term>session</term>
  94         <listitem>
  95           <para>
  96             this module type is associated with doing things that need to
  97             be done for the user before/after they can be given service.
  98             Such things include the logging of information concerning the
  99             opening/closing of some data exchange with a user, mounting
 100             directories, etc.
 101           </para>
 102         </listitem>
 103       </varlistentry>
 104     </variablelist>
 105
 106     <para>
 107       The third field, <emphasis>control</emphasis>, indicates the
 108       behavior of the PAM-API should the module fail to succeed in its
 109       authentication task. There are two types of syntax for this control
 110       field: the simple one has a single simple keyword; the more
 111       complicated one involves a square-bracketed selection of
 112       <emphasis>value=action</emphasis> pairs.
 113     </para>
 114
 115     <para>
 116       For the simple (historical) syntax valid <emphasis>control</emphasis>
 117       values are:
 118     </para>
 119     <variablelist>
 120       <varlistentry>
 121         <term>required</term>
 122         <listitem>
 123           <para>
 124             failure of such a PAM will ultimately lead to the PAM-API
 125             returning failure but only after the remaining
 126             <emphasis>stacked</emphasis> modules (for this
 127             <emphasis>service</emphasis> and <emphasis>type</emphasis>)
 128             have been invoked.
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term>requisite</term>
 134         <listitem>
 135           <para>
 136             like <emphasis>required</emphasis>, however, in the case that
 137             such a module returns a failure, control is directly returned
 138             to the application. The return value is that associated with
 139             the first required or requisite module to fail. Note, this flag
 140             can be used to protect against the possibility of a user getting
 141             the opportunity to enter a password over an unsafe medium. It is
 142             conceivable that such behavior might inform an attacker of valid
 143             accounts on a system. This possibility should be weighed against
 144             the not insignificant concerns of exposing a sensitive password
 145             in a hostile environment.
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term>sufficient</term>
 151         <listitem>
 152           <para>
 153             success of such a module is enough to satisfy the
 154             authentication requirements of the stack of modules (if a
 155             prior <emphasis>required</emphasis> module has failed the
 156             success of this one is <emphasis>ignored</emphasis>). A failure
 157             of this module is not deemed as fatal to satisfying the
 158             application that this type has succeeded.
 159           </para>
 160         </listitem>
 161       </varlistentry>
 162       <varlistentry>
 163         <term>optional</term>
 164         <listitem>
 165           <para>
 166             the success or failure of this module is only important if
 167             it is the only module in the stack associated with this
 168             <emphasis>service</emphasis>+<emphasis>type</emphasis>.
 169           </para>
 170         </listitem>
 171       </varlistentry>
 172       <varlistentry>
 173         <term>include</term>
 174         <listitem>
 175           <para>
 176             include all lines of given type from the configuration
 177             file specified as an argument to this control.
 178           </para>
 179         </listitem>
 180       </varlistentry>
 181     </variablelist>
 182
 183     <para>
 184       For the more complicated syntax valid <emphasis>control</emphasis>
 185       values have the following form:
 186     </para>
 187     <programlisting>
 188       [value1=action1 value2=action2 ...]
 189     </programlisting>
 190
 191     <para>
 192       Where <emphasis>valueN</emphasis> corresponds to the return code
 193       from the function invoked in the module for which the line is
 194       defined. It is selected from one of these:
 195       <emphasis>success</emphasis>, <emphasis>open_err</emphasis>,
 196       <emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>,
 197       <emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>,
 198       <emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>,
 199       <emphasis>cred_insufficient</emphasis>,
 200       <emphasis>authinfo_unavail</emphasis>,
 201       <emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>,
 202       <emphasis>new_authtok_reqd</emphasis>,
 203       <emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>,
 204       <emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>,
 205       <emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>,
 206       <emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>,
 207       <emphasis>authtok_recover_err</emphasis>,
 208       <emphasis>authtok_lock_busy</emphasis>,
 209       <emphasis>authtok_disable_aging</emphasis>,
 210       <emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>,
 211       <emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>,
 212       <emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis>
 213       and <emphasis>default</emphasis>.
 214     </para>
 215     <para>
 216       The last of these, <emphasis>default</emphasis>, implies 'all
 217       <emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the
 218       full list of PAM errors is available in
 219       <filename>/usr/include/security/_pam_types.h</filename>. The
 220       <emphasis>actionN</emphasis> can be: an unsigned integer,
 221       <emphasis>n</emphasis>, signifying an action of 'jump over the
 222       next <emphasis>n</emphasis> modules in the stack', or take one
 223       of the following forms:
 224     </para>
 225     <variablelist>
 226       <varlistentry>
 227         <term>ignore</term>
 228         <listitem>
 229            <para>
 230              when used with a stack of modules, the module's return
 231              status will not contribute to the return code the application
 232              obtains.
 233           </para>
 234         </listitem>
 235       </varlistentry>
 236       <varlistentry>
 237         <term>bad</term>
 238         <listitem>
 239            <para>
 240              this action indicates that the return code should be thought
 241              of as indicative of the module failing. If this module is the
 242              first in the stack to fail, its status value will be used for
 243              that of the whole stack.
 244           </para>
 245         </listitem>
 246       </varlistentry>
 247       <varlistentry>
 248         <term>die</term>
 249         <listitem>
 250            <para>
 251              equivalent to bad with the side effect of terminating the
 252              module stack and PAM immediately returning to the application.
 253           </para>
 254         </listitem>
 255       </varlistentry>
 256       <varlistentry>
 257         <term>ok</term>
 258         <listitem>
 259            <para>
 260              this tells PAM that the administrator thinks this return code
 261              should contribute directly to the return code of the full
 262              stack of modules. In other words, if the former state of the
 263              stack would lead to a return of <emphasis>PAM_SUCCESS</emphasis>,
 264              the module's return code will override this value. Note, if
 265              the former state of the stack holds some value that is
 266              indicative of a modules failure, this 'ok' value will not be
 267              used to override that value.
 268           </para>
 269         </listitem>
 270       </varlistentry>
 271       <varlistentry>
 272         <term>done</term>
 273         <listitem>
 274            <para>
 275              equivalent to ok with the side effect of terminating the module
 276              stack and PAM immediately returning to the application.
 277           </para>
 278         </listitem>
 279       </varlistentry>
 280       <varlistentry>
 281         <term>reset</term>
 282         <listitem>
 283            <para>
 284              clear all memory of the state of the module stack and
 285              start again with the next stacked module.
 286           </para>
 287         </listitem>
 288       </varlistentry>
 289     </variablelist>
 290
 291     <para>
 292       Each of the four keywords: required; requisite; sufficient; and
 293       optional, have an equivalent expression in terms of the [...]
 294       syntax. They are as follows:
 295     </para>
 296     <variablelist>
 297       <varlistentry>
 298         <term>required</term>
 299         <listitem>
 300            <para>
 301              [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
 302           </para>
 303         </listitem>
 304       </varlistentry>
 305       <varlistentry>
 306         <term>requisite</term>
 307         <listitem>
 308            <para>
 309              [success=ok new_authtok_reqd=ok ignore=ignore default=die]
 310           </para>
 311         </listitem>
 312       </varlistentry>
 313       <varlistentry>
 314         <term>sufficient</term>
 315         <listitem>
 316            <para>
 317              [success=done new_authtok_reqd=done default=ignore]
 318           </para>
 319         </listitem>
 320       </varlistentry>
 321       <varlistentry>
 322         <term>optional</term>
 323         <listitem>
 324            <para>
 325              [success=ok new_authtok_reqd=ok default=ignore]
 326           </para>
 327         </listitem>
 328       </varlistentry>
 329     </variablelist>
 330
 331     <para>
 332       <emphasis>module-path</emphasis> is either the full filename
 333       of the PAM to be used by the application (it begins with a '/'),
 334       or a relative pathname from the default module location:
 335       <filename>/lib/security/</filename> or
 336       <filename>/lib64/security/</filename>, depending on the architecture.
 337     </para>
 338
 339     <para>
 340       <emphasis>module-arguments</emphasis> are a space separated list
 341       of tokens that can be used to modify the specific behavior of the
 342       given PAM. Such arguments will be documented for each individual
 343       module. Note, if you wish to include spaces in an argument, you
 344       should surround that argument with square brackets.
 345     </para>
 346     <programlisting>
 347     squid auth required pam_mysql.so user=passwd_query passwd=mada \
 348           db=eminence [query=select user_name from internet_service \
 349           where user_name='%u' and password=PASSWORD('%p') and \
 350         service='web_proxy']
 351     </programlisting>
 352     <para>
 353       When using this convention, you can include `[' characters
 354       inside the string, and if you wish to include a `]' character
 355       inside the string that will survive the argument parsing, you
 356       should use `\['. In other words:
 357     </para>
 358     <programlisting>
 359     [..[..\]..]    -->   ..[..]..
 360     </programlisting>
 361
 362     <para>
 363       Any line in (one of) the configuration file(s), that is not formatted
 364       correctly, will generally tend (erring on the side of caution) to make
 365       the authentication process fail.  A corresponding error is written to
 366       the system log files with a call to
 367       <citerefentry>
 368         <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
 369       </citerefentry>.
 370     </para>
 371
 372 </section>