granicus.if.org Git - linux-pam/blob - modules/pam_unix/pam_unix.8.xml

   1 <?xml version="1.0" encoding='UTF-8'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4
   5 <refentry id="pam_unix">
   6
   7   <refmeta>
   8     <refentrytitle>pam_unix</refentrytitle>
   9     <manvolnum>8</manvolnum>
  10     <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_unix-name">
  14     <refname>pam_unix</refname>
  15     <refpurpose>Module for traditional password authentication</refpurpose>
  16   </refnamediv>
  17
  18   <refsynopsisdiv>
  19     <cmdsynopsis id="pam_unix-cmdsynopsis">
  20       <command>pam_unix.so</command>
  21       <arg choice="opt">
  22         ...
  23       </arg>
  24     </cmdsynopsis>
  25   </refsynopsisdiv>
  26
  27   <refsect1 id="pam_unix-description">
  28
  29     <title>DESCRIPTION</title>
  30
  31     <para>
  32       This is the standard Unix authentication module. It uses standard
  33       calls from the system's libraries to retrieve and set account
  34       information as well as authentication. Usually this is obtained
  35       from the /etc/passwd and the /etc/shadow file as well if shadow is
  36       enabled.
  37     </para>
  38
  39     <para>
  40       The account component performs the task of establishing the status
  41       of the user's account and password based on the following
  42       <emphasis>shadow</emphasis> elements: expire, last_change, max_change,
  43       min_change, warn_change. In the case of the latter, it may offer advice
  44       to the user on changing their password or, through the
  45       <emphasis remap='B'>PAM_AUTHTOKEN_REQD</emphasis> return, delay
  46       giving service to the user until they have established a new password.
  47       The entries listed above are documented in the <citerefentry>
  48       <refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum>
  49       </citerefentry> manual page. Should the user's record not contain
  50       one or more of these entries, the corresponding
  51       <emphasis>shadow</emphasis> check is not performed.
  52     </para>
  53
  54     <para>
  55       The authentication component performs the task of checking the
  56       users credentials (password). The default action of this module
  57       is to not permit the user access to a service if their official
  58       password is blank.
  59     </para>
  60
  61     <para>
  62       A helper binary, <citerefentry>
  63       <refentrytitle>unix_chkpwd</refentrytitle><manvolnum>8</manvolnum>
  64       </citerefentry>, is provided
  65       to check the user's password when it is stored in a read
  66       protected database. This binary is very simple and will only
  67       check the password of the user invoking it. It is called
  68       transparently on behalf of the user by the authenticating
  69       component of this module. In this way it is possible
  70       for applications like <citerefentry>
  71       <refentrytitle>xlock</refentrytitle><manvolnum>1</manvolnum>
  72       </citerefentry> to work without
  73       being setuid-root. The module, by default, will temporarily turn
  74       off SIGCHLD handling for the duration of execution of the helper
  75       binary. This is generally the right thing to do, as many applications
  76       are not prepared to handle this signal from a child they didn't know
  77       was <function>fork()</function>d. The <option>noreap</option> module
  78       argument can be used to suppress this temporary shielding and may be
  79       needed for use with certain applications.
  80     </para>
  81
  82     <para>
  83       The maximum length of a password supported by the pam_unix module
  84       via the helper binary is <emphasis>PAM_MAX_RESP_SIZE</emphasis>
  85       - currently 512 bytes. The rest of the password provided by the
  86       conversation function to the module will be ignored.
  87     </para>
  88
  89     <para>
  90       The password component of this module performs the task of updating
  91       the user's password. The default encryption hash is taken from the
  92       <emphasis remap='B'>ENCRYPT_METHOD</emphasis> variable from
  93       <emphasis>/etc/login.defs</emphasis>
  94     </para>
  95
  96     <para>
  97       The session component of this module logs when a user logins
  98       or leave the system.
  99     </para>
 100
 101     <para>
 102       Remaining arguments, supported by others functions of this
 103       module, are silently ignored. Other arguments are logged as
 104       errors through <citerefentry>
 105       <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
 106       </citerefentry>.
 107     </para>
 108   </refsect1>
 109
 110   <refsect1 id="pam_unix-options">
 111
 112     <title>OPTIONS</title>
 113     <variablelist>
 114       <varlistentry>
 115         <term>
 116           <option>debug</option>
 117         </term>
 118         <listitem>
 119           <para>
 120             Turns on debugging via
 121             <citerefentry>
 122               <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
 123             </citerefentry>.
 124           </para>
 125         </listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term>
 130           <option>audit</option>
 131         </term>
 132         <listitem>
 133           <para>
 134             A little more extreme than debug.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term>
 141           <option>quiet</option>
 142         </term>
 143         <listitem>
 144           <para>
 145             Turns off informational messages namely messages about
 146             session open and close via
 147             <citerefentry>
 148               <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
 149             </citerefentry>.
 150           </para>
 151         </listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term>
 156           <option>nullok</option>
 157         </term>
 158         <listitem>
 159           <para>
 160             The default action of this module is to not permit the
 161             user access to a service if their official password is blank.
 162             The <option>nullok</option> argument overrides this default.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry>
 167         <term>
 168           <option>try_first_pass</option>
 169         </term>
 170         <listitem>
 171           <para>
 172             Before prompting the user for their password, the module first
 173             tries the previous stacked module's password in case that
 174             satisfies this module as well.
 175           </para>
 176         </listitem>
 177       </varlistentry>
 178       <varlistentry>
 179         <term>
 180           <option>use_first_pass</option>
 181         </term>
 182         <listitem>
 183           <para>
 184             The argument <option>use_first_pass</option> forces the module
 185             to use a previous stacked modules password and will never prompt
 186             the user - if no password is available or the password is not
 187             appropriate, the user will be denied access.
 188           </para>
 189         </listitem>
 190       </varlistentry>
 191       <varlistentry>
 192         <term>
 193           <option>nodelay</option>
 194         </term>
 195         <listitem>
 196           <para>
 197             This argument can be used to discourage the authentication
 198             component from requesting a delay should the authentication
 199             as a whole fail. The default action is for the module to
 200             request a delay-on-failure of the order of two second.
 201           </para>
 202         </listitem>
 203       </varlistentry>
 204       <varlistentry>
 205         <term>
 206           <option>use_authtok</option>
 207         </term>
 208         <listitem>
 209           <para>
 210             When password changing enforce the module to set the new
 211             password to the one provided by a previously stacked
 212             <option>password</option> module (this is used in the
 213             example of the stacking of the <command>pam_cracklib</command>
 214             module documented below).
 215           </para>
 216         </listitem>
 217       </varlistentry>
 218       <varlistentry>
 219         <term>
 220           <option>authtok_type=<replaceable>type</replaceable></option>
 221         </term>
 222         <listitem>
 223           <para>
 224             This argument can be used to modify the password prompt
 225             when changing passwords to include the type of the password.
 226             Empty by default.
 227           </para>
 228         </listitem>
 229       </varlistentry>
 230       <varlistentry>
 231         <term>
 232           <option>nis</option>
 233         </term>
 234         <listitem>
 235           <para>
 236             NIS RPC is used for setting new passwords.
 237           </para>
 238         </listitem>
 239       </varlistentry>
 240       <varlistentry>
 241         <term>
 242           <option>remember=<replaceable>n</replaceable></option>
 243         </term>
 244         <listitem>
 245           <para>
 246             The last <replaceable>n</replaceable> passwords for each
 247             user are saved in <filename>/etc/security/opasswd</filename>
 248             in order to force password change history and keep the user
 249             from alternating between the same password too frequently.
 250             The MD5 password hash algorithm is used for storing the
 251             old passwords.
 252             Instead of this option the <command>pam_pwhistory</command>
 253             module should be used.
 254           </para>
 255         </listitem>
 256       </varlistentry>
 257       <varlistentry>
 258         <term>
 259           <option>shadow</option>
 260         </term>
 261         <listitem>
 262           <para>
 263             Try to maintain a shadow based system.
 264           </para>
 265         </listitem>
 266       </varlistentry>
 267       <varlistentry>
 268         <term>
 269           <option>md5</option>
 270         </term>
 271         <listitem>
 272           <para>
 273             When a user changes their password next, encrypt
 274             it with the MD5 algorithm.
 275           </para>
 276         </listitem>
 277       </varlistentry>
 278       <varlistentry>
 279         <term>
 280           <option>bigcrypt</option>
 281         </term>
 282         <listitem>
 283           <para>
 284             When a user changes their password next,
 285             encrypt it with the DEC C2 algorithm.
 286           </para>
 287         </listitem>
 288       </varlistentry>
 289       <varlistentry>
 290         <term>
 291           <option>sha256</option>
 292         </term>
 293         <listitem>
 294           <para>
 295             When a user changes their password next,
 296             encrypt it with the SHA256 algorithm. If the
 297             SHA256 algorithm is not known to the <citerefentry>
 298             <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
 299             </citerefentry> function,
 300             fall back to MD5.
 301           </para>
 302         </listitem>
 303       </varlistentry>
 304       <varlistentry>
 305         <term>
 306           <option>sha512</option>
 307         </term>
 308         <listitem>
 309           <para>
 310             When a user changes their password next,
 311             encrypt it with the SHA512 algorithm. If the
 312             SHA512 algorithm is not known to the <citerefentry>
 313             <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
 314             </citerefentry> function,
 315             fall back to MD5.
 316           </para>
 317         </listitem>
 318       </varlistentry>
 319       <varlistentry>
 320         <term>
 321           <option>blowfish</option>
 322         </term>
 323         <listitem>
 324           <para>
 325             When a user changes their password next,
 326             encrypt it with the blowfish algorithm. If the
 327             blowfish algorithm is not known to the <citerefentry>
 328             <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
 329             </citerefentry> function,
 330             fall back to MD5.
 331           </para>
 332         </listitem>
 333       </varlistentry>
 334       <varlistentry>
 335         <term>
 336           <option>gost_yescrypt</option>
 337         </term>
 338         <listitem>
 339           <para>
 340             When a user changes their password next,
 341             encrypt it with the gost-yescrypt algorithm. If the
 342             gost-yescrypt algorithm is not known to the <citerefentry>
 343             <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
 344             </citerefentry> function,
 345             fall back to MD5.
 346           </para>
 347         </listitem>
 348       </varlistentry>
 349       <varlistentry>
 350         <term>
 351           <option>yescrypt</option>
 352         </term>
 353         <listitem>
 354           <para>
 355             When a user changes their password next,
 356             encrypt it with the yescrypt algorithm. If the
 357             yescrypt algorithm is not known to the <citerefentry>
 358             <refentrytitle>crypt</refentrytitle><manvolnum>3</manvolnum>
 359             </citerefentry> function,
 360             fall back to MD5.
 361           </para>
 362         </listitem>
 363       </varlistentry>
 364       <varlistentry>
 365         <term>
 366           <option>rounds=<replaceable>n</replaceable></option>
 367         </term>
 368         <listitem>
 369           <para>
 370             Set the optional number of rounds of the SHA256, SHA512,
 371             blowfish, gost-yescrypt, and yescrypt password hashing
 372             algorithms to
 373             <replaceable>n</replaceable>.
 374           </para>
 375         </listitem>
 376       </varlistentry>
 377       <varlistentry>
 378         <term>
 379           <option>broken_shadow</option>
 380         </term>
 381         <listitem>
 382           <para>
 383             Ignore errors reading shadow information for
 384             users in the account management module.
 385           </para>
 386         </listitem>
 387       </varlistentry>
 388       <varlistentry>
 389         <term>
 390           <option>minlen=<replaceable>n</replaceable></option>
 391         </term>
 392         <listitem>
 393           <para>
 394             Set a minimum password length of <replaceable>n</replaceable>
 395             characters. The max. for DES crypt based passwords are 8
 396             characters.
 397           </para>
 398         </listitem>
 399       </varlistentry>
 400       <varlistentry>
 401         <term>
 402           <option>no_pass_expiry</option>
 403         </term>
 404         <listitem>
 405           <para>
 406             When set ignore password expiration as defined by the
 407             <emphasis>shadow</emphasis> entry of the user. The option has an
 408             effect only in case <emphasis>pam_unix</emphasis> was not used
 409             for the authentication or it returned authentication failure
 410             meaning that other authentication source or method succeeded.
 411             The example can be public key authentication in
 412             <emphasis>sshd</emphasis>. The module will return
 413             <emphasis remap='B'>PAM_SUCCESS</emphasis> instead of eventual
 414             <emphasis remap='B'>PAM_NEW_AUTHTOK_REQD</emphasis> or
 415             <emphasis remap='B'>PAM_AUTHTOK_EXPIRED</emphasis>.
 416           </para>
 417         </listitem>
 418       </varlistentry>
 419     </variablelist>
 420     <para>
 421       Invalid arguments are logged with  <citerefentry>
 422       <refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
 423       </citerefentry>.
 424     </para>
 425   </refsect1>
 426
 427   <refsect1 id="pam_unix-types">
 428     <title>MODULE TYPES PROVIDED</title>
 429     <para>
 430       All module types (<option>account</option>, <option>auth</option>,
 431       <option>password</option> and <option>session</option>) are provided.
 432     </para>
 433   </refsect1>
 434
 435   <refsect1 id='pam_unix-return_values'>
 436     <title>RETURN VALUES</title>
 437     <variablelist>
 438       <varlistentry>
 439         <term>PAM_IGNORE</term>
 440         <listitem>
 441           <para>
 442             Ignore this module.
 443           </para>
 444         </listitem>
 445       </varlistentry>
 446     </variablelist>
 447      </refsect1>
 448
 449   <refsect1 id='pam_unix-examples'>
 450     <title>EXAMPLES</title>
 451     <para>
 452       An example usage for <filename>/etc/pam.d/login</filename>
 453       would be:
 454       <programlisting>
 455 # Authenticate the user
 456 auth       required   pam_unix.so
 457 # Ensure users account and password are still active
 458 account    required   pam_unix.so
 459 # Change the user's password, but at first check the strength
 460 # with pam_cracklib(8)
 461 password   required   pam_cracklib.so retry=3 minlen=6 difok=3
 462 password   required   pam_unix.so use_authtok nullok md5
 463 session    required   pam_unix.so
 464       </programlisting>
 465     </para>
 466   </refsect1>
 467
 468   <refsect1 id='pam_unix-see_also'>
 469     <title>SEE ALSO</title>
 470     <para>
 471       <citerefentry>
 472         <refentrytitle>login.defs</refentrytitle><manvolnum>5</manvolnum>
 473       </citerefentry>,
 474       <citerefentry>
 475         <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
 476       </citerefentry>,
 477       <citerefentry>
 478         <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
 479       </citerefentry>,
 480       <citerefentry>
 481         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 482       </citerefentry>
 483     </para>
 484   </refsect1>
 485
 486   <refsect1 id='pam_unix-author'>
 487     <title>AUTHOR</title>
 488       <para>
 489         pam_unix was written by various people.
 490       </para>
 491   </refsect1>
 492
 493 </refentry>