pam_faillock: New module for locking after multiple auth failures

1 files changed, 322 insertions, 0 deletions

diff --git a/modules/pam_faillock/pam_faillock.8.xml b/modules/pam_faillock/pam_faillock.8.xml
new file mode 100644
index 00000000..899d8634
--- /dev/null
+++ b/modules/pam_faillock/pam_faillock.8.xml
@@ -0,0 +1,322 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="pam_faillock">
+
+  <refmeta>
+    <refentrytitle>pam_faillock</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_faillock-name">
+    <refname>pam_faillock</refname>
+    <refpurpose>Module counting authentication failures during a specified interval</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_faillock-cmdsynopsisauth">
+      <command>auth ... pam_faillock.so</command>
+      <arg choice="req">
+        preauth|authfail|authsucc
+      </arg>
+      <arg choice="opt">
+        dir=<replaceable>/path/to/tally-directory</replaceable>
+      </arg>
+      <arg choice="opt">
+        even_deny_root
+      </arg>
+      <arg choice="opt">
+        deny=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        fail_interval=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        unlock_time=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        root_unlock_time=<replaceable>n</replaceable>
+      </arg>
+      <arg choice="opt">
+        admin_group=<replaceable>name</replaceable>
+      </arg>
+      <arg choice="opt">
+        audit
+      </arg>
+      <arg choice="opt">
+        silent
+      </arg>
+      <arg choice="opt">
+        no_log_info
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis id="pam_faillock-cmdsynopsisacct">
+      <command>account ... pam_faillock.so</command>
+      <arg choice="opt">
+        dir=<replaceable>/path/to/tally-directory</replaceable>
+      </arg>
+      <arg choice="opt">
+        no_log_info
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_faillock-description">
+
+    <title>DESCRIPTION</title>
+
+    <para>
+      This module maintains a list of failed authentication attempts per
+      user during a specified interval and locks the account in case
+      there were more than <replaceable>deny</replaceable> consecutive
+      failed authentications.
+    </para>
+    <para>
+      Normally, failed attempts to authenticate <emphasis>root</emphasis> will
+      <emphasis remap='B'>not</emphasis> cause the root account to become
+      blocked, to prevent denial-of-service: if your users aren't given
+      shell accounts and root may only login via <command>su</command> or
+      at the machine console (not telnet/rsh, etc), this is safe.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_faillock-options">
+
+    <title>OPTIONS</title>
+         <variablelist>
+            <varlistentry>
+              <term>
+                <option>{preauth|authfail|authsucc}</option>
+              </term>
+              <listitem>
+                <para>
+                  This argument must be set accordingly to the position of this module
+                  instance in the PAM stack.
+                </para>
+                <para>
+                  The <emphasis>preauth</emphasis> argument must be used when the module
+                  is called before the modules which ask for the user credentials such
+                  as the password. The module just examines whether the user should
+                  be blocked from accessing the service in case there were anomalous
+                  number of failed consecutive authentication attempts recently. This
+                  call is optional if <emphasis>authsucc</emphasis> is used.
+                </para>
+                <para>
+                  The <emphasis>authfail</emphasis> argument must be used when the module
+                  is called after the modules which determine the authentication outcome,
+                  failed. Unless the user is already blocked due to previous authentication
+                  failures, the module will record the failure into the appropriate user
+                  tally file.
+                </para>
+                <para>
+                  The <emphasis>authsucc</emphasis> argument must be used when the module
+                  is called after the modules which determine the authentication outcome,
+                  succeeded. Unless the user is already blocked due to previous authentication
+                  failures, the module will then clear the record of the failures in the
+                  respective user tally file. Otherwise it will return authentication error.
+                  If this call is not done, the pam_faillock will not distinguish between
+                  consecutive and non-consecutive failed authentication attempts. The
+                  <emphasis>preauth</emphasis> call must be used in such case. Due to
+                  complications in the way the PAM stack can be configured it is also
+                  possible to call <emphasis>pam_faillock</emphasis> as an account module.
+                  In such configuration the module must be also called in the
+                  <emphasis>preauth</emphasis> stage.
+                </para>
+              </listitem>
+            </varlistentry>
+        </variablelist>
+        <para>
+          The options for configuring the module behavior are described in the
+          <citerefentry><refentrytitle>faillock.conf</refentrytitle><manvolnum>5</manvolnum>
+          </citerefentry> manual page. The options specified on the module command
+          line override the values from the configuration file.
+        </para>
+  </refsect1>
+
+  <refsect1 id="pam_faillock-types">
+    <title>MODULE TYPES PROVIDED</title>
+    <para>
+      The <option>auth</option> and <option>account</option> module types are
+      provided.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_faillock-return_values'>
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_AUTH_ERR</term>
+        <listitem>
+          <para>
+            An invalid option was given, the module was not able
+            to retrieve the user name, no valid counter file
+            was found, or too many failed logins.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+          <para>
+            Everything was successful.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_IGNORE</term>
+        <listitem>
+          <para>
+            User not present in passwd database.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_faillock-notes'>
+    <title>NOTES</title>
+    <para>
+      Configuring options on the module command line is not recommend. The
+      <emphasis>/etc/security/faillock.conf</emphasis> should be used instead.
+    </para>
+    <para>
+      The setup of <emphasis>pam_faillock</emphasis> in the PAM stack is different
+      from the <emphasis>pam_tally2</emphasis> module setup.
+    </para>
+    <para>
+      Individual files with the failure records are created as owned by
+      the user. This allows <emphasis remap='B'>pam_faillock.so</emphasis> module
+      to work correctly when it is called from a screensaver.
+    </para>
+    <para>
+      Note that using the module in <option>preauth</option> without the
+      <option>silent</option> option specified in <filename>/etc/security/faillock.conf</filename>
+      or with <emphasis>requisite</emphasis> control field leaks an information about
+      existence or non-existence of an user account in the system because
+      the failures are not recorded for the unknown users. The message
+      about the user account being locked is never displayed for non-existing
+      user accounts allowing the adversary to infer that a particular account
+      is not existing on a system.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_faillock-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      Here are two possible configuration examples for <filename>/etc/pam.d/login</filename>.
+      They make <emphasis>pam_faillock</emphasis> to lock the account after 4 consecutive
+      failed logins during the default interval of 15 minutes. Root account will be locked
+      as well. The accounts will be automatically unlocked after 20 minutes.
+    </para>
+    <para>
+      In the first example the module is called only in the <emphasis>auth</emphasis>
+      phase and the module does not print any information about the account being blocked
+      by <emphasis>pam_faillock</emphasis>. The <emphasis>preauth</emphasis> call can
+      be added to tell users that their logins are blocked by the module and also to abort
+      the authentication without even asking for password in such case.
+    </para>
+    <para>
+      /etc/security/faillock.conf file example:
+    </para>
+    <programlisting>
+deny=4
+unlock_time=1200
+silent
+    </programlisting>
+    <para>
+      /etc/pam.d/config file example:
+    </para>
+    <programlisting>
+auth     required       pam_securetty.so
+auth     required       pam_env.so
+auth     required       pam_nologin.so
+# optionally call: auth requisite pam_faillock.so preauth
+# to display the message about account being locked
+auth     [success=1 default=bad] pam_unix.so
+auth     [default=die]  pam_faillock.so authfail
+auth     sufficient     pam_faillock.so authsucc
+auth     required       pam_deny.so
+account  required       pam_unix.so
+password required       pam_unix.so shadow
+session  required       pam_selinux.so close
+session  required       pam_loginuid.so
+session  required       pam_unix.so
+session  required       pam_selinux.so open
+    </programlisting>
+    <para>
+      In the second example the module is called both in the <emphasis>auth</emphasis>
+      and <emphasis>account</emphasis> phases and the module informs the authenticating
+      user when the account is locked if <option>silent</option> option is not
+      specified in the <filename>faillock.conf</filename>.
+    </para>
+    <programlisting>
+auth     required       pam_securetty.so
+auth     required       pam_env.so
+auth     required       pam_nologin.so
+auth     required       pam_faillock.so preauth
+# optionally use requisite above if you do not want to prompt for the password
+# on locked accounts
+auth     sufficient     pam_unix.so
+auth     [default=die]  pam_faillock.so authfail
+auth     required       pam_deny.so
+account  required       pam_faillock.so
+# if you drop the above call to pam_faillock.so the lock will be done also
+# on non-consecutive authentication failures
+account  required       pam_unix.so
+password required       pam_unix.so shadow
+session  required       pam_selinux.so close
+session  required       pam_loginuid.so
+session  required       pam_unix.so
+session  required       pam_selinux.so open
+    </programlisting>
+  </refsect1>
+
+  <refsect1 id="pam_faillock-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/var/run/faillock/*</filename></term>
+        <listitem>
+          <para>the files logging the authentication failures for users</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><filename>/etc/security/faillock.conf</filename></term>
+        <listitem>
+          <para>the config file for pam_faillock options</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_faillock-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>faillock</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>faillock.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_faillock-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_faillock was written by Tomas Mraz.
+      </para>
+  </refsect1>
+
+</refentry>