summaryrefslogtreecommitdiffstats
path: root/modules/pam_faillock/README
diff options
context:
space:
mode:
Diffstat (limited to 'modules/pam_faillock/README')
-rw-r--r--modules/pam_faillock/README140
1 files changed, 140 insertions, 0 deletions
diff --git a/modules/pam_faillock/README b/modules/pam_faillock/README
new file mode 100644
index 0000000..3b63c6b
--- /dev/null
+++ b/modules/pam_faillock/README
@@ -0,0 +1,140 @@
+pam_faillock — Module counting authentication failures during a specified
+interval
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DESCRIPTION
+
+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 deny
+consecutive failed authentications.
+
+Normally, failed attempts to authenticate root will not 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 su or at the machine console (not
+telnet/rsh, etc), this is safe.
+
+OPTIONS
+
+{preauth|authfail|authsucc}
+
+ This argument must be set accordingly to the position of this module
+ instance in the PAM stack.
+
+ The preauth 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 authsucc is used.
+
+ The authfail 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.
+
+ The authsucc 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 preauth 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 pam_faillock as an account module.
+ In such configuration the module must be also called in the preauth stage.
+
+conf=/path/to/config-file
+
+ Use another configuration file instead of the default /etc/security/
+ faillock.conf.
+
+The options for configuring the module behavior are described in the
+faillock.conf(5) manual page. The options specified on the module command line
+override the values from the configuration file.
+
+NOTES
+
+Configuring options on the module command line is not recommend. The /etc/
+security/faillock.conf should be used instead.
+
+The setup of pam_faillock in the PAM stack is different from the pam_tally2
+module setup.
+
+Individual files with the failure records are created as owned by the user.
+This allows pam_faillock.so module to work correctly when it is called from a
+screensaver.
+
+Note that using the module in preauth without the silent option specified in /
+etc/security/faillock.conf or with requisite control field leaks an information
+about existence or non-existence of a 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.
+
+EXAMPLES
+
+Here are two possible configuration examples for /etc/pam.d/login. They make
+pam_faillock 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.
+
+In the first example the module is called only in the auth phase and the module
+does not print any information about the account being blocked by pam_faillock.
+The preauth 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.
+
+/etc/security/faillock.conf file example:
+
+deny=4
+unlock_time=1200
+silent
+
+
+/etc/pam.d/config file example:
+
+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
+
+
+In the second example the module is called both in the auth and account phases
+and the module informs the authenticating user when the account is locked if
+silent option is not specified in the faillock.conf.
+
+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
+
+
+AUTHOR
+
+pam_faillock was written by Tomas Mraz.
+