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     <para>
 106       If the <emphasis>type</emphasis> value from the list above is prepended
 107       with a <emphasis>-</emphasis> character the PAM library will not log to
 108       the system log if it is not possible to load the module because it is
 109       missing in the system. This can be useful especially for modules which
 110       are not always installed on the system and are not required for correct
 111       authentication and authorization of the login session.
 112     </para>
 113
 114     <para>
 115       The third field, <emphasis>control</emphasis>, indicates the
 116       behavior of the PAM-API should the module fail to succeed in its
 117       authentication task. There are two types of syntax for this control
 118       field: the simple one has a single simple keyword; the more
 119       complicated one involves a square-bracketed selection of
 120       <emphasis>value=action</emphasis> pairs.
 121     </para>
 122
 123     <para>
 124       For the simple (historical) syntax valid <emphasis>control</emphasis>
 125       values are:
 126     </para>
 127     <variablelist>
 128       <varlistentry>
 129         <term>required</term>
 130         <listitem>
 131           <para>
 132             failure of such a PAM will ultimately lead to the PAM-API
 133             returning failure but only after the remaining
 134             <emphasis>stacked</emphasis> modules (for this
 135             <emphasis>service</emphasis> and <emphasis>type</emphasis>)
 136             have been invoked.
 137           </para>
 138         </listitem>
 139       </varlistentry>
 140       <varlistentry>
 141         <term>requisite</term>
 142         <listitem>
 143           <para>
 144             like <emphasis>required</emphasis>, however, in the case that
 145             such a module returns a failure, control is directly returned
 146             to the application or to the superior PAM stack.
 147             The return value is that associated with
 148             the first required or requisite module to fail. Note, this flag
 149             can be used to protect against the possibility of a user getting
 150             the opportunity to enter a password over an unsafe medium. It is
 151             conceivable that such behavior might inform an attacker of valid
 152             accounts on a system. This possibility should be weighed against
 153             the not insignificant concerns of exposing a sensitive password
 154             in a hostile environment.
 155           </para>
 156         </listitem>
 157       </varlistentry>
 158       <varlistentry>
 159         <term>sufficient</term>
 160         <listitem>
 161           <para>
 162             if such a module succeeds and no prior <emphasis>required</emphasis>
 163             module has failed the PAM framework returns success to
 164             the application or to the superior PAM stack immediately without
 165             calling any further modules in the stack. A failure of a
 166             <emphasis>sufficient</emphasis> module is ignored and processing
 167             of the PAM module stack continues unaffected.
 168           </para>
 169         </listitem>
 170       </varlistentry>
 171       <varlistentry>
 172         <term>optional</term>
 173         <listitem>
 174           <para>
 175             the success or failure of this module is only important if
 176             it is the only module in the stack associated with this
 177             <emphasis>service</emphasis>+<emphasis>type</emphasis>.
 178           </para>
 179         </listitem>
 180       </varlistentry>
 181       <varlistentry>
 182         <term>include</term>
 183         <listitem>
 184           <para>
 185             include all lines of given type from the configuration
 186             file specified as an argument to this control.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190       <varlistentry>
 191         <term>substack</term>
 192         <listitem>
 193           <para>
 194             include all lines of given type from the configuration
 195             file specified as an argument to this control. This differs from
 196             <emphasis>include</emphasis> in that evaluation of the
 197             <emphasis>done</emphasis> and <emphasis>die</emphasis> actions
 198             in a substack does not cause skipping the rest of the complete
 199             module stack, but only of the substack. Jumps in a substack
 200             also can not make evaluation jump out of it, and the whole substack
 201             is counted as one module when the jump is done in a parent stack.
 202             The <emphasis>reset</emphasis> action will reset the state of a
 203             module stack to the state it was in as of beginning of the substack
 204             evaluation.
 205           </para>
 206         </listitem>
 207       </varlistentry>
 208     </variablelist>
 209
 210     <para>
 211       For the more complicated syntax valid <emphasis>control</emphasis>
 212       values have the following form:
 213     </para>
 214     <programlisting>
 215       [value1=action1 value2=action2 ...]
 216     </programlisting>
 217
 218     <para>
 219       Where <emphasis>valueN</emphasis> corresponds to the return code
 220       from the function invoked in the module for which the line is
 221       defined. It is selected from one of these:
 222       <emphasis>success</emphasis>, <emphasis>open_err</emphasis>,
 223       <emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>,
 224       <emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>,
 225       <emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>,
 226       <emphasis>cred_insufficient</emphasis>,
 227       <emphasis>authinfo_unavail</emphasis>,
 228       <emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>,
 229       <emphasis>new_authtok_reqd</emphasis>,
 230       <emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>,
 231       <emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>,
 232       <emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>,
 233       <emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>,
 234       <emphasis>authtok_recover_err</emphasis>,
 235       <emphasis>authtok_lock_busy</emphasis>,
 236       <emphasis>authtok_disable_aging</emphasis>,
 237       <emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>,
 238       <emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>,
 239       <emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis>,
 240       <emphasis>conv_again</emphasis>, <emphasis>incomplete</emphasis>,
 241       and <emphasis>default</emphasis>.
 242     </para>
 243     <para>
 244       The last of these, <emphasis>default</emphasis>, implies 'all
 245       <emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the
 246       full list of PAM errors is available in
 247       <filename>/usr/include/security/_pam_types.h</filename>. The
 248       <emphasis>actionN</emphasis> can take one of the following forms:
 249     </para>
 250     <variablelist>
 251       <varlistentry>
 252         <term>ignore</term>
 253         <listitem>
 254            <para>
 255              when used with a stack of modules, the module's return
 256              status will not contribute to the return code the application
 257              obtains.
 258           </para>
 259         </listitem>
 260       </varlistentry>
 261       <varlistentry>
 262         <term>bad</term>
 263         <listitem>
 264            <para>
 265              this action indicates that the return code should be thought
 266              of as indicative of the module failing. If this module is the
 267              first in the stack to fail, its status value will be used for
 268              that of the whole stack.
 269           </para>
 270         </listitem>
 271       </varlistentry>
 272       <varlistentry>
 273         <term>die</term>
 274         <listitem>
 275            <para>
 276              equivalent to bad with the side effect of terminating the
 277              module stack and PAM immediately returning to the application.
 278           </para>
 279         </listitem>
 280       </varlistentry>
 281       <varlistentry>
 282         <term>ok</term>
 283         <listitem>
 284            <para>
 285              this tells PAM that the administrator thinks this return code
 286              should contribute directly to the return code of the full
 287              stack of modules. In other words, if the former state of the
 288              stack would lead to a return of <emphasis>PAM_SUCCESS</emphasis>,
 289              the module's return code will override this value. Note, if
 290              the former state of the stack holds some value that is
 291              indicative of a modules failure, this 'ok' value will not be
 292              used to override that value.
 293           </para>
 294         </listitem>
 295       </varlistentry>
 296       <varlistentry>
 297         <term>done</term>
 298         <listitem>
 299            <para>
 300              equivalent to ok with the side effect of terminating the module
 301              stack and PAM immediately returning to the application.
 302           </para>
 303         </listitem>
 304       </varlistentry>
 305       <varlistentry>
 306         <term>N (an unsigned integer)</term>
 307         <listitem>
 308            <para>
 309              equivalent to ok with the side effect of jumping over the
 310              next N modules in the stack. Note that N equal to 0 is not
 311              allowed (and it would be identical to ok in such case).
 312           </para>
 313         </listitem>
 314       </varlistentry>
 315       <varlistentry>
 316         <term>reset</term>
 317         <listitem>
 318            <para>
 319              clear all memory of the state of the module stack and
 320              start again with the next stacked module.
 321           </para>
 322         </listitem>
 323       </varlistentry>
 324     </variablelist>
 325
 326     <para>
 327       Each of the four keywords: required; requisite; sufficient; and
 328       optional, have an equivalent expression in terms of the [...]
 329       syntax. They are as follows:
 330     </para>
 331     <variablelist>
 332       <varlistentry>
 333         <term>required</term>
 334         <listitem>
 335            <para>
 336              [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
 337           </para>
 338         </listitem>
 339       </varlistentry>
 340       <varlistentry>
 341         <term>requisite</term>
 342         <listitem>
 343            <para>
 344              [success=ok new_authtok_reqd=ok ignore=ignore default=die]
 345           </para>
 346         </listitem>
 347       </varlistentry>
 348       <varlistentry>
 349         <term>sufficient</term>
 350         <listitem>
 351            <para>
 352              [success=done new_authtok_reqd=done default=ignore]
 353           </para>
 354         </listitem>
 355       </varlistentry>
 356       <varlistentry>
 357         <term>optional</term>
 358         <listitem>
 359            <para>
 360              [success=ok new_authtok_reqd=ok default=ignore]
 361           </para>
 362         </listitem>
 363       </varlistentry>
 364     </variablelist>
 365
 366     <para>
 367       <emphasis>module-path</emphasis> is either the full filename
 368       of the PAM to be used by the application (it begins with a '/'),
 369       or a relative pathname from the default module location:
 370       <filename>/lib/security/</filename> or
 371       <filename>/lib64/security/</filename>, depending on the architecture.
 372     </para>
 373
 374     <para>
 375       <emphasis>module-arguments</emphasis> are a space separated list
 376       of tokens that can be used to modify the specific behavior of the
 377       given PAM. Such arguments will be documented for each individual
 378       module. Note, if you wish to include spaces in an argument, you
 379       should surround that argument with square brackets.
 380     </para>
 381     <programlisting>
 382     squid auth required pam_mysql.so user=passwd_query passwd=mada \
 383           db=eminence [query=select user_name from internet_service \
 384           where user_name='%u' and password=PASSWORD('%p') and \
 385         service='web_proxy']
 386     </programlisting>
 387     <para>
 388       When using this convention, you can include `[' characters
 389       inside the string, and if you wish to include a `]' character
 390       inside the string that will survive the argument parsing, you
 391       should use `\]'. In other words:
 392     </para>
 393     <programlisting>
 394     [..[..\]..]    -->   ..[..]..
 395     </programlisting>
 396
 397     <para>
 398       Any line in (one of) the configuration file(s), that is not formatted
 399       correctly, will generally tend (erring on the side of caution) to make
 400       the authentication process fail.  A corresponding error is written to
 401       the system log files with a call to
 402       <citerefentry>
 403         <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
 404       </citerefentry>.
 405     </para>
 406
 407 </section>